https://github.com/clipboardhealth/groundcrew
Dispatch your ticket backlog to local, interactive AI coding agents. One git worktree per ticket, sandboxed by default.
https://github.com/clipboardhealth/groundcrew
agentic ai-agents automation claude claude-code cli cmux codex coding-agents developer-tools git-worktree jira linear local-first orchestrator parallel sandbox tmux typescript worktrees
Last synced: 7 days ago
JSON representation
Dispatch your ticket backlog to local, interactive AI coding agents. One git worktree per ticket, sandboxed by default.
- Host: GitHub
- URL: https://github.com/clipboardhealth/groundcrew
- Owner: ClipboardHealth
- License: mit
- Created: 2026-05-16T14:45:40.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-06T19:06:29.000Z (11 days ago)
- Last Synced: 2026-06-06T20:21:00.925Z (11 days ago)
- Topics: agentic, ai-agents, automation, claude, claude-code, cli, cmux, codex, coding-agents, developer-tools, git-worktree, jira, linear, local-first, orchestrator, parallel, sandbox, tmux, typescript, worktrees
- Language: TypeScript
- Homepage:
- Size: 3.59 MB
- Stars: 39
- Watchers: 0
- Forks: 5
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
Dispatch your task backlog to local, interactive AI coding agents. One git worktree per task, sandboxed by default.
Groundcrew watches assigned tasks, creates isolated worktrees, launches agent CLIs in dedicated terminals, and leaves each task's work on its own PR-ready branch. For the backstory, read _[Tickets to pull requests while you sleep](https://www.clipboardworks.com/resources/blog/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 task 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 task.** 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 task sources.** Linear by default; Jira and local files via [task sources](./docs/task-sources.md).
- **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](https://github.com/nvm-sh/nvm): `nvm install 24`.
- **git:** e.g., `brew install git`, `apt install git`.
- **A terminal multiplexer:** [tmux](https://github.com/tmux/tmux/wiki/Installing) (cross-platform), [cmux](https://cmux.com/) (macOS), or [zellij](https://zellij.dev/).
- **An agent CLI:** [Claude Code](https://code.claude.com/docs/en/quickstart) and/or [Codex](https://developers.openai.com/codex/quickstart?setup=cli).
- **A sandbox runner:** [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) (cross-platform) or [Safehouse](https://agent-safehouse.dev/) on macOS. Skip only with `--runner none`.
## Quickstart
```bash
# 1. Install groundcrew.
npm install -g @clipboard-health/groundcrew@latest
# 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 --agent claude
# 3. Run the clone commands printed by `crew init`.
# 4. Safehouse runs use groundcrew's bundled clearance allowlist automatically.
# Add extra hosts later via CLEARANCE_ALLOW_HOSTS or CLEARANCE_ALLOW_HOSTS_FILES.
# 5. Using Linear? Export your API key. (Jira and other trackers: see Task Pickup.)
export GROUNDCREW_LINEAR_API_KEY="lin_api_..."
# 6. 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. `--agent claude` or `--agent codex` chooses the single built-in agent preset to enable in the generated config.
## Task Pickup
**Not on Linear?** Use Jira or local files via [task sources](./docs/task-sources.md).
Linear works out of the box: assign tasks to yourself and add an `agent-*` label.
- `agent-claude`, `agent-codex`, or `agent-` routes to that agent.
- `agent-any` routes to the enabled agent with the most session headroom, after skipping agents over their session limit or weekly paced budget.
- Tasks without an `agent-*` label are ignored by `crew run`; dispatch one manually with `crew start `.
Groundcrew scans `workspace.knownRepositories` to infer which repo a task belongs to.
A task blocked by non-terminal blockers is skipped until those blockers are done.
### The task description is the prompt
Groundcrew sends each agent a generic unattended-execution prompt plus the task title and description. The prompt says how to work: read the repo instructions, make the smallest sensible change, verify it, and produce the requested output. The task description says what to do.
Write tasks as complete agent instructions: the goal, the context and constraints, links to logs or screenshots, how to verify, and the output you want. A vague task gets a vague PR.
## Commands
```bash
crew init [--global | --local] [--force] [--dry-run] # create a crew.config.ts
[--project-dir ] [--repo ]...
[--runner ] [--agent ]
crew doctor # check setup
crew source list|verify [] # inspect configured task sources
crew task list [--source ] # list tasks across sources
crew task get [--source ] [--prompt] # inspect one task or its prompt
crew task create "Title" --source [--agent ] # create a source task
crew task validate [] # validate task content
crew status [] # inspect current state or one task
crew run [--watch] # one-shot or --watch forever
crew start # provision + launch one task now
crew stop [--reason ] # stop workspace, keep worktree
crew resume # reopen a paused task
crew cleanup [--force] # tear down every worktree for a task
crew upgrade [] # reinstall crew globally through npm
```
See [command details](./docs/commands.md) for status output, doctor behavior, and the stop/resume workflow.
## Configuration
Workspace settings and at least one enabled agent are required; everything else has a default.
```ts
import type { Config } from "@clipboard-health/groundcrew";
export default {
workspace: {
projectDir: "~/dev",
// Optional: all worktrees go here regardless of where each repo lives.
// worktreeDir: "~/dev/worktrees",
// Strings live under projectDir; use { name, projectDirOverride } to override per repo.
knownRepositories: ["OWNER/REPO"],
},
agents: {
default: "claude",
definitions: {
claude: {},
},
},
defaults: {
hooks: {
// No-op placeholder; replace with your repo's setup, e.g. "npm ci".
prepareWorktree: "true",
},
},
} satisfies Config;
```
Changing `workspace.worktreeDir` only affects worktrees discovered under the new
root. Clean up existing worktrees before switching it, or temporarily unset
`worktreeDir` when you need `crew cleanup` to find worktrees created beside the
repos.
There is no `linear` config block. Groundcrew reads `GROUNDCREW_LINEAR_API_KEY` first, then falls back to `LINEAR_API_KEY`.
## Reference
- [Configuration](./docs/configuration.md): discovery order, repo layout, scripted/sparse-checkout (graft) worktrees, full config table, prompt customization.
- [Runners](./docs/runners.md): Safehouse, Docker Sandboxes, and the `none` escape hatch.
- [Credentials](./docs/credentials.md): Linear API keys, 1Password, build secrets, and `preLaunch`.
- [Prepare worktree hooks](./docs/setup-hooks.md): `.groundcrew/config.json` `hooks.prepareWorktree` for per-repo dependency setup.
- [Task sources](./docs/task-sources.md): custom shell/Jira/local-plan adapters.
- [Development](./docs/development.md): local source workflow and README/demo asset regeneration.
- [Troubleshooting](./docs/troubleshooting.md): common operational pitfalls and fixes.
## License
[MIT](./LICENSE)