Quickstart

This takes you from a machine with no Kotharo to a ticket the team has sized, planned and built, in one repo.

Before you start

• Claude Code 2.1.295 or later. Check with claude --version.
• Python 3.11 or later, as python3, py -3 or python.
• On Windows, Git for Windows, so hooks run in Git Bash.
• A git repo you work in, and a ticket for it. A small, clear one is best for a first run, such as a bug fix or a change with acceptance criteria. A GitHub issue works as well as a Jira or Linear ticket.

1. Install the plugin

In a terminal, add the marketplace:

claude plugin marketplace add https://plugins.kotharo.com/marketplace.json

Then install the plugin:

claude plugin install kotharo@kotharo

To install from inside Claude Code instead, see Install.

2. Open Claude Code in your repo

Start a new session in the repo, so the plugin loads:

claude

3. Connect your tools

/kotharo:setup

Setup looks at your connected MCP servers, command line tools and CI files, and asks only what it can't tell, such as which ticketing tool this repo uses and how often the team should stop to ask. Answer its questions, read the list of changes it proposes, and give your OK.

It ends with the steps only you can do, such as signing in to a server with /mcp or installing a command line tool. Do them, start a new session so new connections load, and run /kotharo:setup again. It says so when everything is ready.

If you don't run Claude Code in auto mode, give your OK to the permissions block setup proposes for the repo's .claude/settings.json. Without it, every git and test command the team runs raises a permission prompt.

If the repo has no CLAUDE.md, or a thin one, run /kotharo:create-claude-md now. It asks you for each value, such as how to build and test, and the team reads the file on every ticket.

4. Start a branch for the ticket

The team works on the branch you are on, and it never ships from main or master. Start a branch off your default branch, named for the ticket:

git switch -c feature/ABC-123-short-name

5. Hand the team a ticket

/kotharo:team ABC-123

Use your own ticket key. For a GitHub issue, the number works, as in /kotharo:team 42. You can also describe the work in a sentence: with a ticketing tool connected, the team drafts the ticket and asks you once before it creates it, and with none, your description is the ticket.

6. Answer the stops

The team reads the ticket and the code, sizes the work into a lane, derives acceptance criteria, and starts. It stops only when a decision is yours. At the default balanced level:

• A clear ticket plays back what the team understood and starts. It stops you once, at the end card, with what the change is for, its riskiest area, the tests and reviews that ran, and the diff. Its default choice, Ship, commits, pushes and opens the PR with one yes, and reviews again only if the code changed since the team's review.
• A new feature stops you twice: at scope, before it designs and builds, and at the end card.

Each stop shows in the band and a stop card, with its choices and the default first. Pick one, or answer in your own words. Then the pull request goes through its checks and review, and you merge it. The team sees the merge on its own and finishes the ticket's close-out.

Where to go next

• Lanes and stops: when the team stops, and why.
• Autonomy levels: have it stop more or less.
• Worklogs and continuity: pick up where you left off in a new session.
• Troubleshooting: if something didn't work.

Next: Update and uninstall. All docs