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
◆  16 skills in .claude/skills (16 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-triageSort what to build: ready, plan, question, drop
/branch-planAn approved spec, then steps you can check off
/branch-buildExecute a plan, fix, task, or prototype
/branch-reviewFresh eyes on the diff, security, release checklist
/branch-shipFinal checks, pull request, version bump
/branch-tendKeep the PR moving: fix checks, answer comments
/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
3 work items · 2 ideas · 4 plans · last: branch-build "webhook retries"

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

In your repo

Ideas, plans, work cards 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/  specs/  retros/  work/  evidence/
  activity.jsonl   what ran, what's next
  metrics.jsonl    outcome snapshots for retro
  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
branch reviewFresh agent session on the diff
branch pullPull a GitHub issue into the queue
branch workBuild a card in its own git worktree
branch tickAdvance the queue once — for schedulers
branch metricsCards, runs, findings — outcome counts

Privacy

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