The problem

Coding agents made parallel work cheap. You start a session per task, each in its own worktree, and an
hour later you have six of them. Then you're lost:

• Which terminal is working on which ticket? Which worktree is on port 5193?
• Is the PR for #712 open? Did its CI go red while you were in another session?
• Which worktrees are merged and just sitting there holding 1 GB of node_modules and a port?
• The agent spends half its turns re-deriving the same gh / git / curl rituals, and gets them wrong.

nanoflow keeps ticket → worktree → branch → ports → PR → CI → teardown connected, shows it live inside
Claude Code, and turns every ritual into one deterministic command.

✨ What you get

A live dashboard pane

/nanoflow opens a pane next to your session:

• Your session's worktree is framed and badged, so you always know where this agent is.
• Everything is a link: the ticket, the PR, the failing CI run, each running service, the worktree folder.
• Select a worktree for actions: ▶ Start dev, ■ Stop, 🌐 Open app, 🔀 Open PR, 📋 Copy path, and
  🧹 Teardown (offered once its PR is merged, and it asks first).
• Tickets tab: your board's Ready / In progress / In review columns. ▶ Start a ticket (the agent runs
  the kickoff), jump to the worktree already on it, or create a new one.
• Activity tab: the last 50 moments, linked.

A status line that tracks the task

#712 Sites go offline… │ ✓ticket ✓branch ✓code ✓checks ✓PR #713 ✗CI ○merged │ 8 worktrees · 2 running │ ⏳ tests

Toasts on every moment that matters

Worktree created or removed · a service came up (with its URL) or went down · PR opened, merged or
closed · CI turned green or red · ticket closed · tests, typecheck, lint, e2e passed or failed · a red
test turned green (your bug repro now passes) · a skill loaded · the Playwright browser opened, saved a
screenshot, closed · and after a merge: "Tear down app-712-site-offline? Close the browser and delete your
screenshots too."

Dev skills

Bundled with the plugin, written for agents, and they use the CLI:

🚀 Install

1. The Claude Code plugin (dashboard, status line, toasts, skills):

/plugin install nanoflow --marketplace nanosite-ai/nanoflow

2. The CLI (optional but recommended; the pane works without it, from plain git + gh):

npm install -g @nanosite/nanoflow     # gives you `nanoflow` and the short `nf`

3. In your repo:

nf init --board <org>/<project-number> --team   # writes .claude/nanoflow.json; --team offers the plugin to teammates
nf doctor                                       # checks git, gh auth, config, board

Edit the services in .claude/nanoflow.json (ports and start commands), commit .claude/, and you're done.
With --team, everyone who trusts the repo in Claude Code is offered the plugin automatically.

Requirements: git, the GitHub CLI (gh auth login; add -s project for
boards), Node ≥ 20.12 for the CLI. The dashboard, status line and toasts use Claude Code mods
(function-hook plugins), which are rolling out; on a build without them, the CLI and the skills still
work on their own.

🔌 Ports per worktree, one shared database

Each worktree gets a slot. The main checkout is slot 0; every service's port is base + slot × step:

nf wt create (or nf task start) picks the next free slot, copies your gitignored files (.env…) from
the main checkout so secrets and the database are shared, writes the slot's ports into them, and
records the slot. nf up exports the slot's env (PORT, VITE_PORT, API_URL… whatever you map) and
waits until each service answers. So two branches run side by side on one machine against the same data.

Need a branch with its own database (say, a divergent migration)? Map it in that worktree's copied
.env, e.g. DATABASE_URL=…/app_712. Or for every worktree: "env": { "worktree": { "QUEUE_PREFIX": "jobs-{feature}" } } keeps shared queues apart. Per-worktree databases are on the roadmap.

⚡ The CLI: fewer tokens, fewer mistakes

An agent doing a ritual by hand runs five to fifteen tool calls: look the issue up, find the board item
id in a 1,000-item JSON dump, set the column, create the worktree, copy and patch the .env files, pick a
free port, install, rename the session, comment on the issue. Each call costs tokens twice (the command
and its output), and each is a chance to get it wrong.

nf task start 712 is one call with a six-line answer.

This comes from our own monorepo, where nanoflow started as an in-house CLI. Before it existed, in two weeks
of agent sessions we counted:

• 226 hand-rolled board edits, 39 of them failed (missing jq, wrong owner, empty id);
• 167 curl polling loops waiting for a dev server to come up;
• session titles skipped so often that nobody could tell the terminals apart.

nf board set, nf up --bg (waits until the app answers) and nf task start replaced them: written once,
tested, the same every time.

The commands

Full reference: docs/cli.md.

🧪 Tests, e2e and screenshots

• nf check runs whatever you map ("checks": { "typecheck": "…", "test": "…", "e2e": "npx playwright test" }).
• The plugin recognises test runners (vitest, jest, pytest, go test, cargo test, npm test…), tsc,
  eslint and playwright test with no config, and toasts each pass or fail. A check that goes from red
  to green raises "now passes".
• Playwright MCP sessions are tracked: opening, screenshots, closing. At teardown you're reminded to close
  the browser and delete local screenshots.
• --shots puts screenshots on one orphan branch (assets/pr-screenshots/pr-<n>-<slug>/) and embeds them
  in the PR body. They render inline (private repos too) and never enter the merge diff.

🧩 Works with

⚙️ Configuration

One committed file, .claude/nanoflow.json, read by both the plugin and the CLI. Everything is optional.

{
  "$schema": "https://raw.githubusercontent.com/nanosite-ai/nanoflow/main/nanoflow.schema.json",
  "github": { "board": { "owner": "acme", "number": 3 } },
  "services": [
    { "name": "web", "base": 5173, "step": 10, "open": true, "start": { "run": "npm run dev", "cwd": "apps/web" } },
    { "name": "api", "base": 3001, "step": 10, "path": "/healthz", "start": { "run": "npm start", "cwd": "apps/api" } }
  ],
  "env": {
    "export": { "VITE_PORT": "{port:web}", "API_URL": "{origin:api}" },
    "files": { "apps/api/.env": { "PORT": "{port:api}" } }
  },
  "worktree": { "copy": [".env", "apps/api/.env"], "install": "npm install" },
  "checks": { "typecheck": "npm run typecheck", "lint": "npm run lint", "test": "npm test" },
  "provider": { "snapshot": ["nanoflow", "flow", "--json"], "local": ["nanoflow", "flow", "--json", "--local"] }
}

Every field, the placeholders and the pane's action buttons: docs/config.md.

🗺️ Roadmap

• Per-worktree databases (create / drop with the worktree).
• Linear and Jira ticket titles and status.
• Agent-session awareness: which Claude Code session is in which worktree, across terminals.

🤝 Contributing

Issues and PRs welcome. Layout: the plugin is the repo root (hooks/, types/, skills/), the CLI is
cli/. We build nanoflow with nanoflow: the repo's own .claude/nanoflow.json drives nf task start,
nf check and nf pr create, and the dashboard shows our worktrees while we work.

• nf check runs everything: the CLI's typecheck and tests, claude plugin validate . and claude plugin test ..
• npm test in cli/ builds, then runs the unit tests, the --help/docs checks and the end-to-end suite:
  the whole task lifecycle on a throwaway repo with a real service and a fake gh, so it never touches
  GitHub. NANOFLOW_GH=<script.mjs> is the hook that swaps gh for the fake.
• CI runs both on Linux, macOS and Windows for every PR.

New CLI commands need --help examples (a test enforces it), --json output and --dry before side
effects. Regenerate the reference with nf docs --write.

Made by nanosite.ai

nanoflow is built and used daily by nanosite.ai. It grew out of the CLI and rituals
we use to run many agent sessions in parallel on our own monorepo, and we open-sourced it so you don't have
to rebuild it. Questions, ideas, war stories: open an issue.

License

MIT © nanosite.ai