Skip to content
unbranchunbranchunbranch docs

Claude Code with @unbranch/kit

@unbranch/kit connects a code repository, and the coding agent working in it, to your team’s agreed model. It lets you check the work against that model. It needs Node.js 20 or later.

Set it up

Section titled “Set it up”

  1. At the repository’s root, run:

    Terminal window
    npx @unbranch/kit@latest init

    It looks first, then fills only what is missing. It lists what the repository already has (docs, a doc-sync command, progress skills, pre-push hooks, other MCP servers pointing at unbranch) and never overwrites any of it. It asks which project the repository builds and whether to install the unbranch skills.

  2. Open Claude Code at the repository’s root and allow the unbranch server when asked.

  3. Run /mcp, choose unbranch and sign in. Your browser opens unbranch so you can approve the connection.

  4. If you did not choose a project in step 1, ask Claude “which unbranch projects can I reach?”, then bind the repository:

    Terminal window
    npx @unbranch/kit@latest init --project <id>

  5. Try the commands: /unbranch:status, /unbranch:progress and /unbranch:link.

What it writes

Section titled “What it writes”
File What it holds
.unbranch.json Which unbranch project this repository builds, the server, where your docs are, and whether /unbranch:progress answers on its own.
.mcp.json unbranch as an MCP server for Claude Code. Any other servers in it are kept.
.claude/settings.json The unbranch skills, if you install them, written by Claude Code’s own plugin command.
CLAUDE.md A short note on the commands, between <!-- unbranch --> markers, only if you agree. Nothing else in the file is touched.

Commit them all, so the whole team shares the setup. None of them holds a password or a key: each person signs in through their own Claude Code.

The skills

Section titled “The skills”
Command What it does
/unbranch:progress Where the work stands, by agreed capability: built, in progress, parked, not started, under discussion, and work that no agreed capability covers. It reads your SNAPSHOT and BACKLOG docs together with unbranch. It also answers on its own when you ask what is done or what is next, unless autoProgress is false.
/unbranch:status What is waiting for you: proposals you have not answered, and work being delivered.
/unbranch:link Links each feature document to the capability it builds, with a line in its front matter after you confirm each one, and records which part of the product this repository builds.

The skills read and report. They never change your code, and progress and status run in a read-only subagent of their own, so they do not fill your working session with unbranch context.

Options

Section titled “Options”
Terminal window
npx @unbranch/kit init --project <id> --name "e-menu"   # bind without being asked
npx @unbranch/kit init --skills                         # install the skills without asking
npx @unbranch/kit init --yes                            # ask nothing (skills only with --skills)

Installed globally (npm i -g @unbranch/kit), the command is plain unbranch: unbranch init, unbranch doctor.

Check the setup

Section titled “Check the setup”
Terminal window
npx @unbranch/kit@latest doctor

doctor checks the files, that the server answers, whether another MCP server would clash with the project’s, and whether the skills are installed. Each failed check says what to run.

Monorepos and services

Section titled “Monorepos and services”

Every command uses the nearest .unbranch.json above the working directory. A monorepo can hold one per service directory. Several repositories can bind to the same project, each covering its own part of it, which is the normal setup for services. See Keeping a repository in step.