ClipboardHealth/groundcrew: dispatch your Linear backlog to AI coding agents. One git worktree

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

$ crew doctor --ticket HRD-446
groundcrew doctor --ticket HRD-446 (Add retry logic to the sync job)
────────────────────────────────────────────────────────────────────

Resolution
  [ok] Ticket exists in Linear ("Add retry logic to the sync job")
  [ok] Status is Todo
  [ok] Has agent-* label (agent-claude)
  [ok] Model resolves from agent-* label (model "claude")
  [ok] Description mentions known repo (owner/repo)
  [ok] Resolved repo is cloned locally (/dev/workspaces/owner/repo)

Eligibility
  [ok] No active blockers
  [ok] Model "claude" usage under sessionLimitPercentage (12% (limit 85%))
  [ok] In-progress cap not hit (2/4 used)

→ would be dispatched on next tick

Why

• Linear-native. Polls a project, respects agent-* labels, honors blockers.
• One worktree per ticket. Agents work in parallel without stepping on each other.
• Local-first sandboxing. Safehouse on macOS, Docker Sandboxes on Linux, or an explicit none escape hatch.
• Multi-agent. Ships with claude and codex; bring your own CLI by dropping a definition into crew.config.ts.

Install

npm install -g @clipboard-health/groundcrew

Installs the crew binary. @clipboard-health/clearance is pulled in transitively and provides the clearance / clearance-ensure bins used by Safehouse runs.

Quickstart

1. Install prereqs. Node 24, git, cmux or tmux, and the agent CLIs themselves (claude, codex, cursor-agent, …). Optional: codexbar for session-usage gating.

2. Pick an isolation runner. See Runners — auto resolves to safehouse on macOS and sdx on Linux/WSL.

3. Create a Linear project to scope your work. Any team works — make a project inside it and drop tickets in. The orchestrator polls by project, not by team.

4. Configure. Copy the shipped example into XDG config and edit:

   mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/groundcrew"
   cp "$(npm root -g)/@clipboard-health/groundcrew/crew.config.example.ts" \
      "${XDG_CONFIG_HOME:-$HOME/.config}/groundcrew/crew.config.ts"
   $EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/groundcrew/crew.config.ts"
   

   Or drop crew.config.ts at the root of any repo you run crew from — crew discovers it via cosmiconfig project-walk. Any of crew.config.{ts,mjs,js,json}, .crewrc{,.json,.ts}, .config/crew.config.{ts,json}, or .config/crewrc{,.json} work.

   Set linear.projects[].projectSlug (paste the trailing slug of your Linear project URL, e.g. ai-strategy-5152195762f3), workspace.projectDir, and workspace.knownRepositories. Defaults cover everything else. To watch multiple projects from one crew instance, add more entries to linear.projects; they all share the same orchestrator.maximumInProgress budget.

   Then clone each repo before the first crew run — groundcrew creates per-ticket worktrees from these clones, it does not auto-clone:

   crew setup repos              # clone all missing entries via gh
   crew setup repos --dry-run    # preview
   crew setup repos owner/repo   # restrict to one entry
   

   crew setup repos is idempotent; already-cloned repos report [exists]. Bare-name entries (no owner/) are skipped — clone them manually into <projectDir>/<name>.

5. Export a Linear API key. crew reads GROUNDCREW_LINEAR_API_KEY first, then falls back to LINEAR_API_KEY.

   export GROUNDCREW_LINEAR_API_KEY="lin_api_..."
   

   Using 1Password (op) for the key

   echo "GROUNDCREW_LINEAR_API_KEY='op://<vault>/LINEAR_API_KEY/credential'" > .env.1password
   op run --env-file .env.1password -- crew doctor
   

6. Run.

   crew doctor                    # check setup
   crew run --dry-run             # preview without provisioning
   crew run --watch               # poll forever
   

Secrets

Groundcrew forwards a small allowlist of build-time secrets from your shell into the setup phase (so npm install can authenticate against private registries) and then strips them before the agent runs. The agent process never inherits these values in its environment.

Recognized names. Defined in BUILD_SECRET_NAMES:

• NPM_TOKEN
• BUF_TOKEN

Set them in the shell you run crew from. Anything not in this list is ignored by the secret-shuttling path.

Flow. For each ticket:

1. If any recognized var is set and non-empty, groundcrew writes secrets.env (mode 0600) into the ticket's temp prompt dir as KEY='value' lines — see stageBuildSecrets in src/commands/setupWorkspace.ts.
2. The launch script sources secrets.env with set -a so the values are exported into the setup phase only (and under sdx, forwarded into the sandbox via -e KEY flags).
3. After setup completes, the script unsets every name in BUILD_SECRET_NAMES and then rm -rfs the entire prompt dir (including secrets.env) before exec'ing the agent. See sourceSecretsLine / unsetSecretsLine and the rm -rf / exec lines in src/lib/launchCommand.ts. The rollback path on setup failure (src/commands/setupWorkspace.ts) wipes the prompt dir too.

Net effect: by the time the agent process exists, the values are gone from the environment and the file is gone from disk.

Runners

local.runner picks the local isolation backend. auto resolves per platform.

For sdx: each model that runs under it needs a sandbox: { agent: "<sbx-agent>" } block in crew.config.ts. Groundcrew names sandboxes groundcrew-<agent> (e.g. groundcrew-claude) and reuses one sandbox per agent across repos and tickets. First-time agent auth happens inside the sandbox the first time it launches. To bootstrap manually instead, run sbx create --name groundcrew-<agent> <agent> <projectDir> once.

CLEARANCE_ALLOW_HOSTS="api.openai.com,auth.openai.com,api.anthropic.com,mcp.linear.app,api.linear.app" \
crew run --watch

CLEARANCE_ALLOW_HOSTS_FILES="$(npm root -g)/@clipboard-health/groundcrew/clearance-allow-hosts:$HOME/.config/clearance/personal-allow-hosts" \
crew run --watch

Configuration

Three keys are required; everything else has a default.

crew resolves config as: GROUNDCREW_CONFIG if set → project-walk from cwd (cosmiconfig: crew.config.{ts,mjs,js,json}, .crewrc{,.json,.ts}, .config/crew.config.{ts,json}, .config/crewrc{,.json}) → ${XDG_CONFIG_HOME:-$HOME/.config}/groundcrew/crew.config.ts (also accepts legacy config.ts for one release). The branch prefix (<prefix>-<TICKET>) is derived from os.userInfo().username — not configurable.

Agent selection uses Linear labels: agent-claude, agent-codex, agent-<name>. crew run without --ticket only fetches tickets carrying an agent-* label — the GraphQL query filters server-side, so unlabeled tickets are never returned by Linear and do not appear on the board. Use crew run --ticket <TICKET> to provision an unlabeled ticket on demand (falls back to models.default). agent-any routes to the model with the most available session capacity. Todo tickets blocked by non-terminal blockers are skipped until their blockers reach a terminal status.

Prompt customization

Groundcrew ships one model-agnostic unattended prompt by default. It tells the agent to make reasonable assumptions, follow repository instructions, run documented verification, review its diff, open a PR when GitHub/gh is available, and include a workspace continuation hint when known.

For a personal workflow, keep the prompt next to your local config and load it with readFileSync:

import { readFileSync } from "node:fs";

export default {
  // ...
  prompts: {
    initial: readFileSync(new URL("./initial-prompt.md", import.meta.url), "utf8"),
  },
};

This keeps package defaults portable while letting your private config reference team-specific statuses, tools, plugins, or review loops.

// crew.config.ts
export default {
  // …
  models: {
    default: "claude",
    definitions: {
      codex: { disabled: true },
    },
  },
};

Per-repo setup hook

When groundcrew launches a worktree, if .groundcrew/setup.sh exists in the repo root it's invoked as bash .groundcrew/setup.sh --deps-only before the agent starts; otherwise nothing runs. The same convention applies inside the sdx sandbox (overridable per-model via models.definitions.<name>.sandbox.setupCommand). No implicit npm install, uv sync, or anything else — groundcrew is language-agnostic, so opt in by adding the script.

The --deps-only contract

The flag tells the script "you're being called by an automated system before an agent launches — skip anything interactive or one-time-only." The same script handles both modes; branch on $1. The name is historical and Node-flavored, but the semantic is language-neutral:

• With --deps-only: do the cheap recurring work this worktree needs (lockfile install, generate types, etc.). No prompts, no global installs, no nvm / pyenv bootstrap that the host should already have.
• Without the flag: full interactive bootstrap. Use this path when an engineer runs the script by hand for first-time onboarding, or when wiring it into another tool's SessionStart hook.

Setup failures are advisory — groundcrew logs the non-zero exit and still launches the agent so a flaky network or stale lockfile doesn't block the session.

Examples

Python (uv):

#!/usr/bin/env bash
set -euo pipefail
if [ "${1:-}" = "--deps-only" ]; then
  uv sync --dev
else
  uv sync --dev
  # ... extra one-time bootstrap (e.g., pre-commit install, db seed) ...
fi

Node (npm):

#!/usr/bin/env bash
set -euo pipefail
if [ "${1:-}" = "--deps-only" ]; then
  npm clean-install
else
  npm clean-install
  # ... extra one-time bootstrap (e.g., husky install, codegen, link local packages) ...
fi

Docs-only or polyglot repo with no install step:

Omit the script. With nothing at .groundcrew/setup.sh, groundcrew skips the hook silently — fine for documentation repos, polyglot monorepos where setup happens per-package, or anywhere the per-worktree work is genuinely zero.

For a more comprehensive real-world example (nvm bootstrap, hash-based skip-on-no-changes caching, portable SHA-256 detection), see this repo's own .groundcrew/setup.sh. It's also symlinked at .claude/setup.sh so the same script doubles as a Claude Code SessionStart hook for this repo — that symlink is local convenience, not part of groundcrew's contract.

Generating it with an agent

To have a coding agent (Claude Code, Cursor, etc.) scaffold .groundcrew/setup.sh for a repo you're onboarding, see docs/setup-hook-agent-prompt.md — it encodes the contract above as a copy-pasteable prompt.

Commands

crew doctor                                              # full setup check
crew doctor --ticket <TICKET> [--no-linear] [--no-fetch] # full ticket lifecycle (dispatch + recovery)
crew run                                                 # one-shot dispatch
crew run --watch                                         # poll forever
crew run --ticket <TICKET>                               # provision one ticket and exit
crew setup repos [--dry-run] [<repo>...]
crew interrupt <TICKET> [--reason <text>]                # stop the live workspace, keep the worktree
crew resume <TICKET>                                     # reopen an existing ticket worktree
crew cleanup <TICKET>                                    # tear down every worktree carrying this ticket

crew doctor --ticket <TICKET> covers the full per-ticket lifecycle: pre-dispatch eligibility (Todo status, agent-* label, model resolution, repository mention, local clone, blockers, model session usage, in-progress capacity) and post-dispatch local-state recovery (recorded run state, host worktree, workspace pane, local branch, remote branch, open PR). Verdict precedence starts with PR outcomes (pr-open > pr-merged). Recorded failed launches report before ordinary local recovery, interrupted runs report concrete recoverable git work first when it exists and otherwise report interrupted, and ordinary post-dispatch cases report in-flight before recoverable. If none of those apply, doctor falls through to unresolvable > ineligible > would-dispatch > lost. Exits 0 on would-dispatch, pr-open, or pr-merged; any other verdict exits 1. --watch and --ticket are mutually exclusive. To inspect codexbar session windows directly, run codexbar usage.

crew doctor --ticket <ticket>

Diagnose where a ticket is in its lifecycle and what to do next. Runs the same resolution and eligibility chain as the dispatcher, plus probes recorded run state, host worktree, workspace pane, local branch, remote branch, and PR; prints a single verdict with a copy-pasteable recovery step when one applies.

Flags:

• --no-linear — skip the Linear GraphQL call. Resolution and Eligibility sections are skipped; verdicts that need only local state (in-flight, recoverable, pr-open, pr-merged, lost) still fire.
• --no-fetch — skip the upfront git fetch origin <branch> before checking remote presence.

The Workspace section appends an attach hint to the pane name when the workspace backend exposes one (e.g. tmux attach -t <session>:<pane> or cmux attach <name>), so the verdict line is immediately actionable. The hero above shows a passing pre-dispatch run; here's the same command on a ticket that's already past dispatch:

groundcrew doctor --ticket HRD-442 (Multi-event extractor: year inference can produce date_start > date_end)
────────────────────────────────────────────────────────────────────────────────────────────────────────────

Resolution
  [ok] Ticket exists in Linear ("Multi-event extractor: year inference can produce date_start > date_end")
  [ok] Status is Todo
  (skipped — post-dispatch — pre-dispatch checks are irrelevant)

Eligibility
  (skipped — post-dispatch — pre-dispatch checks are irrelevant)

Run state
  [ok] Local run state (running)
  [ok] Recorded model (claude)
  [ok] Recorded worktree (/Users/paul/dev/groundcrew-workspaces/herds-social/herds-hrd-442)
  [ok] Recorded branch (paul-hrd-442)
  [ok] Resume count (0)

Worktree
  [ok] Host worktree exists (/Users/paul/dev/groundcrew-workspaces/herds-social/herds-hrd-442)
  [--] Working tree clean (0 modified, 1 untracked)
  [ok] Branch checked out (paul-hrd-442)

Workspace
  [ok] Workspace pane open (hrd-442 — attach: `tmux attach -t groundcrew:hrd-442`)

Local branch
  [ok] Local branch exists (paul-hrd-442, 2 ahead / 0 behind origin/main)

Remote branch
  [ok] Branch present on origin

Pull request
  [ok] Open PR for this branch (#224 https://github.com/herds-social/herds/pull/224)

→ pr-open: https://github.com/herds-social/herds/pull/224 (#224)

Recovering a stranded ticket

The verdict on the last line maps to a recovery action:

crew interrupt <ticket>

Stop a live workspace pane while preserving the ticket worktree and branch. This is the manual pause button for cases where you need terminal capacity back, want to stop an agent that is going in the wrong direction, or need to inspect the diff before letting another agent continue.

crew interrupt HRD-442 --reason "wrong implementation direction"
crew doctor --ticket HRD-442
crew resume HRD-442

The command closes the cmux/tmux workspace when it exists, records local run state under the groundcrew state directory, and never tears down the worktree. If the workspace was already gone but the worktree is still present, interrupt records that fact so doctor can point at the preserved branch instead of reporting a mystery ticket.

crew resume <ticket>

Reopen an existing ticket worktree with a continuation prompt. Resume never creates a new worktree; if none exists, it fails and leaves re-dispatch to crew run --ticket <ticket>.

The resume prompt tells the agent to inspect current git status and diff before editing, includes the previous interrupt reason when recorded, and reuses the recorded model, repository, branch, runner, sandbox, and workspace backend. When no run-state file exists but a worktree does, resume falls back to Linear resolution for the model and ticket context.

Troubleshooting

First stop for "labeled but not on the board": crew doctor --ticket <ticket> lists every check the dispatcher runs and flags the failing one.

Development

Clone the repo and the crew / crew:op scripts execute straight from TypeScript source — no build step needed.

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

node --run crew:op -- run --watch

Both forms discover config via cosmiconfig — project-walk from cwd for crew.config.ts and friends, then ${XDG_CONFIG_HOME:-$HOME/.config}/groundcrew/crew.config.ts (legacy config.ts is still accepted for one release). Set GROUNDCREW_CONFIG to point elsewhere. The crew:op wrapper additionally reads ${XDG_CONFIG_HOME:-$HOME/.config}/groundcrew/op.env (1Password env-file with op:// references resolved at launch).

Logs land in ${XDG_STATE_HOME:-$HOME/.local/state}/groundcrew/groundcrew.log by default (override via logging.file). The "Loaded config from …" line at startup tells you which config won.

Source edits in src/** are picked up on the next invocation. Requires Node ≥ 24.3 (native .ts type stripping).