groundcrew

Dispatch your ticket backlog to local, interactive AI coding agents. One git worktree per ticket, sandboxed by default.

Groundcrew watches assigned tickets, creates isolated worktrees, launches agent CLIs in dedicated terminals, and leaves each ticket's work on its own PR-ready branch. For the backstory, read Tickets to pull requests while you sleep.

Why

Local. Agents run on your machine with your tools, shell, and credentials. That makes them more steerable than remote agents, and easy to nudge when they drift.
Interactive. Each ticket launches the real claude or codex CLI in its own terminal pane, not a wrapper that approximates it. Watch any session live and take over when you need to.
One worktree per ticket. Agents work in parallel without stepping on each other.
Sandboxed by default. Safehouse or Docker Sandboxes isolate each agent on the host; none is an explicit escape hatch.
Pluggable ticket sources. Linear by default; Jira and local files via ticket sources.
Multi-agent routing. Ships claude and codex presets; bring your own CLI in config.

Prerequisites

crew doctor checks all of these, so you can install as you go.

Node >= 24: nvm: nvm install 24.
git: e.g., brew install git, apt install git.
A terminal multiplexer: tmux (cross-platform) or cmux (macOS).
An agent CLI: Claude Code and/or Codex.
A sandbox runner: Docker Sandboxes (cross-platform) or Safehouse on macOS. Skip only with --runner none.

Quickstart

# 1. Install groundcrew.
npm install -g @clipboard-health/groundcrew

# 2. Scaffold a global config. Agents are sandboxed by default
#    (Safehouse/Docker Sandboxes); add --runner none to run unsandboxed on the host.
crew init --global --project-dir ~/dev --repo OWNER/REPO --model claude

# 3. Run the clone commands printed by `crew init`.

# 4. Using Linear? Export your API key. (Jira and other trackers: see Ticket Pickup.)
export GROUNDCREW_LINEAR_API_KEY="lin_api_..."

# 5. Verify setup, then dispatch.
crew doctor
crew run --watch

crew init --global writes config to ${XDG_CONFIG_HOME:-$HOME/.config}/groundcrew/. Pass --repo more than once for multiple repos. --model claude or --model codex chooses the single built-in model preset to enable in the generated config.

Ticket Pickup

Not on Linear? Use Jira or local files via ticket sources.

Linear works out of the box: assign tickets to yourself and add an agent-* label.

agent-claude, agent-codex, or agent-<name> routes to that model.
agent-any routes to the enabled model with the most available capacity.
Tickets without an agent-* label are ignored by crew run; dispatch one manually with crew start <TICKET>.

Groundcrew scans workspace.knownRepositories to infer which repo a ticket belongs to.

A ticket blocked by non-terminal blockers is skipped until those blockers are done.

Commands

crew init [--global | --local] [--force] [--dry-run]     # create a crew.config.ts
          [--project-dir <dir>] [--repo <repo>]...
          [--runner <auto|safehouse|sdx|none>] [--model <claude|codex>]
crew doctor                                              # check setup
crew status [<TICKET>]                                   # inspect current state or one ticket
crew run                                                 # one-shot orchestration
crew run --watch                                         # poll forever
crew start <TICKET>                                      # provision + launch one ticket now
crew stop <TICKET> [--reason <text>]                     # stop workspace, keep worktree
crew resume <TICKET>                                     # reopen a paused ticket
crew cleanup <TICKET>                                    # tear down every worktree for a ticket
crew upgrade [<version>]                                 # reinstall crew globally through npm

See command details for status output, doctor behavior, and the stop/resume workflow.

Configuration

Workspace settings and at least one enabled model are required; everything else has a default.

import type { Config } from "@clipboard-health/groundcrew";

export default {
  workspace: {
    projectDir: "~/dev",
    knownRepositories: ["OWNER/REPO"],
  },
  local: {
    runner: "auto",
  },
  models: {
    default: "claude",
    definitions: {
      claude: {},
    },
  },
  defaults: {
    hooks: {
      // No-op placeholder; replace with your repo's setup, e.g. "npm ci".
      prepareWorktree: "true",
    },
  },
} satisfies Config;

There is no linear config block. Groundcrew reads GROUNDCREW_LINEAR_API_KEY first, then falls back to LINEAR_API_KEY.

Reference

Configuration: discovery order, repo layout, full config table, prompt customization.
Runners: Safehouse, Docker Sandboxes, and the none escape hatch.
Credentials: Linear API keys, 1Password, build secrets, and preLaunch.
Prepare worktree hooks: .groundcrew/config.json hooks.prepareWorktree for per-repo dependency setup.
Ticket sources: custom shell/Jira/local-plan adapters.
Troubleshooting: common operational pitfalls and fixes.

Development

Clone the repo and run the CLI from TypeScript source:

cd ~/dev/c/groundcrew
node --run crew -- doctor

# With 1Password for GROUNDCREW_LINEAR_API_KEY:
node --run crew:op -- run --watch

Both forms discover config through cosmiconfig. Source edits in src/** are picked up on the next invocation. Requires Node >= 24.

Regenerate the README demo with VHS:

./static/render-demo.sh

License

MIT

Why