claudeers.
// Claude Plugins

nanoflow

Run Claude Code tasks in parallel without losing track: each in its own worktree and ports, followed from ticket to PR to CI to teardown. By nanosite.ai

// Claude Plugins[ cli ][ api ][ web ][ claude ]#claude#ai-agents#claude-code#claude-code-plugin#developer-tools#git-worktree#plugins◷ MIT$open-sourceupdated about 1 month ago
Actively maintained
100/100
last commit 15 days ago
last release 15 days ago
releases 11
open issues 3
// star history

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up nanoflow (claude-plugin project) into my current project.
Found on https://claudeers.com/nanoflow
Repo: https://github.com/nanosite-ai/nanoflow
Homepage/docs: https://nanosite.ai
Detected install method: claude-plugin → /plugin install nanoflow@nanosite-ai/nanoflow
Category: plugins. Platforms: cli, api, web.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
active; community-verified: false. Confirm the source before running anything.
// or install directly (claude-plugin)
/plugin marketplace add nanosite-ai/nanoflow
/plugin install nanoflow@nanosite-ai/nanoflow
// or clone
git clone https://github.com/nanosite-ai/nanoflow

// compatibility

Platformscli, api, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageTypeScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

🌳 nanoflow

Run Claude Code tasks in parallel without losing track.

by nanosite.ai

Run many tasks at once with Claude Code, each in its own git worktree on its own ports, and see all of them at a glance: which ticket, which branch, which PR, whether CI is red, what's running, what's ready to tear down.

Install · What you get · The CLI · Config · CLI reference


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:

nanoflow in Claude Code: the agent picks up the dark mode ticket, which gets its own worktree and ports, writes the change, runs the checks and opens a PR. The pane beside the chat shows every worktree with its ticket, board column, PR, CI and ports, and updates live as CI goes green, the PR merges and the worktree is torn down

  • 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: ▶ Pick up its ticket (Claude moves it to In progress and plans the work; offered until it's under way), 🚀 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:

SkillWhat it makes the agent do
worktree-lifecycleticket first → worktree → work → PR → CI → merged → teardown with your approval
fix-bugreproduce with a failing test at the lowest layer, name the root cause, fix, watch it pass
pr-screenshotsverify visual changes in a real browser (Playwright MCP), attach before/after to the PR
wrap-up-summaryend every task with one scannable status footer

🚀 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:

ServiceSlot 0 (main)Slot 1Slot 2Slot N
web5173518351935173 + 10N
api3001301130213001 + 10N

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.

Why it helps an agentHow
Small outputsnf check prints one line per check and only the tail of a failure. nf ci --watch --failed-log waits without a poll loop and returns only the failing steps. nf pr comments returns unresolved threads, one line each.
One call, not tentask start, pr create (push + valid title + Closes #N + screenshots + board + title), wt remove (stop processes, delete, prune, branch).
Never blocksNo prompts without a TTY. A command that needs a yes fails fast and names --yes.
Parseable--json on every command; progress goes to stderr.
Safe--dry on everything that writes. wt remove refuses uncommitted or unpushed work. Teardown and anything destructive need an explicit yes.
Cross-platformWindows, macOS, Linux; npm/pnpm/yarn shims and Windows file locks handled.
Cheap on GitHubnf flow reads every worktree's ticket, PR, CI and the board in one GraphQL query.

The commands

RitualCommand
Start a task (issue → In progress → worktree → title → comment)nf task start <issue#> · nf task start --new "<title>" · Jira: nf task start ED-712 --type fix
A ticket for laternf ticket new "<title>" --type bug --definition "…"
Board columnsnf board list [ready] · nf board set <issue#> in-review
Worktreesnf wt create · nf wt list · nf wt remove <name> --delete-branch · nf wt clean
This slot's ports and envnf env
Run the app on the slot, wait until it answersnf up --bg · nf status · nf logs <svc> · nf kill
The repo's checks, condensednf check [typecheck test …]
Open the PRnf pr create --body-file pr.md --shots before.png after.png
Screenshots onto a PRnf shots <pr#> <files…> --attach
CInf ci --watch --failed-log · nf ci --rerun-failed
Review commentsnf pr comments · --reply <id> --body "…"
PR mergednf task done
Everything at oncenf flow (--json is the dashboard's feed)
The wrap-up footernf summary --what "…" --next "…"

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

Languages / frameworksAny. Services are just a port + a start command.
Package managersnpm, pnpm, yarn, bun (detected by nf init).
TicketsGitHub Issues + GitHub Projects (v2) boards, or Jira through Atlassian's acli, like gh (ticket.tracker: "jira", nf jira login): titles, statuses, moves, comments, new tickets. PRs and CI from GitHub (config).
OSWindows, macOS, Linux.
Your own CLIAlready have a dev CLI? Make it print the provider contract and the dashboard uses it instead.

⚙️ 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 tickets.
  • 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

// faq

What is nanoflow?

Run Claude Code tasks in parallel without losing track: each in its own worktree and ports, followed from ticket to PR to CI to teardown. By nanosite.ai. It is open-source on GitHub.

Is nanoflow free to use?

nanoflow is open-source under the MIT license, so it is free to use.

What category does nanoflow belong to?

nanoflow is listed under plugins in the Claudeers registry of Claude-compatible tools.

12 views
★ 15 stars
unclaimed
updated about 1 month ago

// embed badge

nanoflow on Claudeers
[![Claudeers](https://claudeers.com/api/badge/nanoflow.svg)](https://claudeers.com/nanoflow)

// retro hit counter

nanoflow hit counter
[![Hits](https://claudeers.com/api/counter/nanoflow.svg)](https://claudeers.com/nanoflow)

// reviews

// guestbook

0/500

// related in Claude Plugins

🔓

A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.

// pluginsmultica-ai/★ 230,631[ claude ]
🔓

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explainin…

// pluginsanthropics/⟨Python⟩★ 154,558[ claude ]
🔓

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

// pluginsHKUDS/⟨Python⟩★ 58,467◷ Apache-2.0[ claude ]
🔓

financial-services — a Claude ecosystem project on GitHub.

// pluginsanthropics/⟨Python⟩★ 41,027◷ Apache-2.0[ claude ]
→ see how nanoflow connects across the ecosystem