Brief your coding agent on your repo before it writes a line.

branch turns your stack, commands and conventions into a context file, then adds skills that take a rough idea to a merged pull request. For Claude Code and Codex.

$ bunx @anturno/branch init

Requires Bun 1.4+ or Node.js 22+.

$ bunx @anturno/branch init
┌  branch 0.0.1
│
◇  Scanned tidepool
│  Languages: Python
│  Package manager: uv
│  Frameworks: FastAPI
│  Tests: pytest
│  Services: PostgreSQL, Sentry
│  Env vars: 9
│
◆  .branch/context.json created
◆  13 skills in .claude/skills (13 new, 0 updated, 0 unchanged)
◆  CLAUDE.md: branch block added
│
└  Next: open Claude Code in this repo and run /branch-start

How it works

Scan

Reads manifests, lockfiles, workspace config, CI and deploy files, and env var names. Writes .branch/context.json.
Install

Adds the workflow skills to .claude/skills and a short block to CLAUDE.md. Use --host codex for AGENTS.md.
Work

Run /branch-start. Your agent writes .branch/CONTEXT.md (stack, commands, conventions, gotchas) and works from it every session.

Workflow

/branch-startBrief the agent, list next moves
/branch-ideaWrite it down or poke holes in it
/branch-planSteps you can check off, or a design
/branch-buildExecute a plan, fix, or prototype
/branch-reviewBugs, security, release checklist
/branch-shipFinal checks, pull request, version bump
/branch-reflectWhat shipped, what to change

Home screen

Run a command bare and it asks what you need. Add a few words and it goes straight there.

❯ /branch-start

branch · tidepool
Python · FastAPI · uv
2 ideas · 4 plans · last: branch-build "webhook retries"

What next?
1. Capture or pressure-test an idea    /branch-idea
2. Turn it into a plan                 /branch-plan
3. Build from a plan, fix, or spike    /branch-build
4. Review the work                     /branch-review
5. Get it shipped                      /branch-ship
6. Look back                           /branch-reflect

In your repo

Ideas, plans and retros are plain files in the repo. The next session reads them and carries on.

.branch/
  context.json     deterministic scan
  CONTEXT.md       agent-written, read every session
  ideas/  plans/  retros/
  activity.jsonl   what ran, what's next
  manifest.json    hashes of installed skills

CLI

branch initScan, install skills, wire up CLAUDE.md
branch scanDiff the stack against the last scan
branch updateRefresh skills, keep your edits
branch doctorCheck the install
branch infoPrint state as JSON
branch startOpen the agent on /branch-start

Privacy

The scan never opens .env files and never sends anything anywhere. Everything else is read by your agent, on your machine.