Local Runner

Why use it

• Zero compute credits — runs on your machine, not Shipchart infrastructure
• Full environment access — your database, your test suite, your tools
• Uses your own auth — no API keys to configure in Shipchart
• Concurrent tasks — run multiple tasks simultaneously with git worktree isolation
• Automatic PRs — changes are committed, pushed, and a PR is opened via GitHub CLI

Prerequisites

• Shipchart CLI installed and authenticated (shipchart auth login)
• Project linked via .shipchart.yml (shipchart init)
• Codex CLI or Claude Code installed and authenticated
• GitHub CLI (gh) installed and authenticated for automatic PR opening (recommended; required for PR code review delegations, as the agent uses gh pr review to post comments)
• Git configured with push access to the repo

Quick start

cd ~/projects/your-app
shipchart init
shipchart worker

The worker will connect to Shipchart and begin polling for delegated tasks. You'll see a status message confirming the connection and the coding agent it detected.

Configuration flags

shipchart worker --agent claude --max-concurrent 3 --name "Dev Machine"

Agent binary overrides (optional)

If the worker cannot detect a local agent binary (common when GUI apps have a different PATH), set explicit binary paths. In the macOS app, open Worker settings and fill the optional Codex/Claude/Gemini binary path fields.

For CLI-only usage, you can set environment variables before starting the worker:

export SHIPCHART_AGENT_CODEX_PATH=~/.local/bin/codex
export SHIPCHART_AGENT_CLAUDE_PATH=~/.local/bin/claude
export SHIPCHART_AGENT_GEMINI_PATH=~/.local/bin/gemini
shipchart worker

How it works

1. 1Start shipchart worker in your project directory
2. 2Delegate a task in the Shipchart web UI, selecting "Local Runner"
3. 3The CLI picks up the task within seconds
4. 4A git worktree is created for isolation — your working directory is untouched
5. 5Codex or Claude runs in the worktree with full local environment access
6. 6Changes are committed, pushed, and a PR is opened automatically
7. 7The worktree is cleaned up
8. 8Results appear in the Shipchart web UI

PR code reviews

The Local Runner can also perform AI-assisted code reviews on pull requests. From the Code tab on your project page, click the Review button next to any PR. The agent will check out the PR branch, review the diff for bugs, security issues, and code quality concerns, then post review comments directly on GitHub using the gh CLI.

Requirements: The gh CLI must be installed and authenticated on the machine running the local worker. The agent uses gh pr review to submit comments, so ensure the authenticated GitHub account has write access to the repository.

Worktree isolation

Each task runs in its own git worktree inside a sibling .shipchart-tasks/ directory. Your main checkout is never modified, so you can continue working while tasks execute. Multiple tasks can run concurrently in separate worktrees without interfering with each other.

your-app/                  # Your working directory (untouched)
.shipchart-tasks/
  task-abc123/             # Worktree for task 1
  task-def456/             # Worktree for task 2

Graceful shutdown

Press Ctrl+C once to initiate a graceful shutdown — the worker will stop accepting new tasks and wait for any active tasks to finish before disconnecting. Press Ctrl+C again to force an immediate exit.

Local Runner vs Shipchart Runner

Choose the runner that best fits your workflow.

Troubleshooting