Run Claude Code agents from a local task board
Write a card, assign Claude Code, move it to To Do. PortBay launches the CLI you already have installed, points it at the card, and the work happens in a running local project on your Mac.
HeadlessHow do I run multiple Claude Code agents at once?
Two problems have to be solved separately: isolation and verification. Claude Code covers isolation itself — claude --worktree auth gives each run its own checkout and branch, and claude agents lists what is in flight. What a worktree lacks is somewhere to run: no server, no database, no URL to check the work at. PortBay supplies that half. Each card is a Markdown file in .portbay/tasks/; move one to To Do and PortBay launches Claude Code as a headless CLI subprocess pointed at that card, inside the project's running environment — a real .test domain with trusted HTTPS, a per-project database, captured mail. The run reads .portbay/HANDOFF.md first, comments what it changed, and advances the card; a strike system stops a failing card after 3 runs by default. Settings → Integrations writes the MCP config, so a connected session can drive the board itself.
Verified against the product, 2026-07-10.
One card, one Claude Code run
Assign Claude Code, move the card to To Do, and PortBay dispatches it into the running project. The card comes back with comments and a summary of what changed.
Your first Claude Code card
Six steps from a clean Mac to a Claude Code run you can review at a real URL. Every command runs as written.
- Install PortBay
- Add your project
- Connect Claude Code over MCP (optional)
- Write a card and assign Claude Code
- Move the card to To Do
- Review the work at a real URL
Install PortBay
Homebrew installs the app and the bundled portbay CLI. Prefer a direct download? Grab the DMG from GitHub Releases and drag PortBay.app into Applications.
brew tap portbay-app/portbay && brew install --cask portbayAdd your project
Click Add project in the app, pick the folder, and confirm the detected type, hostname and port. Save, then start it. Your project now answers at its own .test URL over HTTPS. The CLI does the same from a terminal.
portbay add ~/code/myappConnect Claude Code over MCP (optional)
Settings → Integrations detects the agent CLIs on your Mac and writes the MCP config for each client, Claude Code included. Or add it from the terminal. A connected session can read the board, claim cards and move them forward.
claude mcp add portbay -- /opt/homebrew/bin/portbay-mcpWrite a card and assign Claude Code
Describe the task the way you would brief a teammate. Assign Claude Code on the card itself, or set it as the board default so every card without its own agent uses it. The card is a plain Markdown file in your repo.
.portbay/tasks/fix-signup-validation.mdMove the card to To Do
Auto-dispatch launches Claude Code the moment the card lands. Manual mode queues the card and asks you to confirm each run. A concurrency cap keeps a busy board from launching ten agents at once.
Review the work at a real URL
The agent edits your repo, checks its work against the running project, comments what it changed, and appends a hand-off entry to .portbay/HANDOFF.md. Open the project URL and review. Turn on Require review to hold agent-reported work for your approval.
https://myapp.testThe same task, without the board
Claude Code manages worktrees and background sessions on its own, and that solves the checkout half. What each worktree still lacks is an environment: no running server, no database, no URL to open.
PortBay closes the verification gap: the card dispatches into a project that is already running, at a URL both you and the agent can open, and the hand-off note carries the context to the next run.
# Claude Code manages the worktrees itselfclaude --worktree auth # isolated checkout, own branchclaude -w billingclaude agents # dashboard of running sessions # what a worktree still doesn't have:# a running server, a database, a mail inbox,# a URL where you (or the agent) can check the work# the session ends; the context ends with it
The pieces underneath
Asked before downloading
Does PortBay need an Anthropic API key to run Claude Code?
No. PortBay launches the Claude Code CLI you already have installed, under your existing account. It ships no model of its own and adds no key of its own. If Claude Code works in your terminal, it works from the board.
Can I run several Claude Code agents in parallel?
Yes. Each card dispatches its own run, and a board-level concurrency cap decides how many run at once. A card can also create or switch to its own git branch on dispatch, so parallel agents don't fight over the working tree.
Can Claude Code drive the board itself over MCP?
Yes. Settings → Integrations writes the MCP config for Claude Code. A connected session reads the hand-off, claims the next card, posts progress and touched files, then updates the hand-off and moves the card forward. Three read-only resources expose the project context, the board and the hand-off.
What happens when a Claude Code run keeps failing?
Each run that ends without Done adds a strike. At the cap, 3 by default, the card stops auto-dispatching and lands in Blocked with a comment. Before that, an optional rescue attempt hands the last try to a stronger agent, and a teacher step distills the failure into a lesson in .portbay/LEARNINGS.md that every later run reads.
Give your projects and your agents a real local home.
Download for macOSFree & open source · macOS 11+ on Apple Silicon · Pro from $10/mo