{"id":50008569,"url":"https://github.com/clipboardhealth/groundcrew","last_synced_at":"2026-06-11T03:01:48.844Z","repository":{"id":358559424,"uuid":"1240767751","full_name":"ClipboardHealth/groundcrew","owner":"ClipboardHealth","description":"Dispatch your ticket backlog to local, interactive AI coding agents. One git worktree per ticket, sandboxed by default.","archived":false,"fork":false,"pushed_at":"2026-06-06T19:06:29.000Z","size":3761,"stargazers_count":39,"open_issues_count":5,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T20:21:00.925Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ClipboardHealth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-16T14:45:40.000Z","updated_at":"2026-06-06T19:03:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"a4559d1e-8bff-4762-a24c-41abb5046705","html_url":"https://github.com/ClipboardHealth/groundcrew","commit_stats":null,"previous_names":["clipboardhealth/groundcrew"],"tags_count":88,"template":false,"template_full_name":null,"purl":"pkg:github/ClipboardHealth/groundcrew","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClipboardHealth%2Fgroundcrew","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClipboardHealth%2Fgroundcrew/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClipboardHealth%2Fgroundcrew/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClipboardHealth%2Fgroundcrew/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ClipboardHealth","download_url":"https://codeload.github.com/ClipboardHealth/groundcrew/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClipboardHealth%2Fgroundcrew/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34180147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-05-19T20:01:01.960Z","updated_at":"2026-06-11T03:01:48.839Z","avatar_url":"https://github.com/ClipboardHealth.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"groundcrew\" src=\"./static/groundcrew-wordmark.svg\" height=\"96\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Dispatch your task backlog to local, interactive AI coding agents. One git worktree per task, sandboxed by default.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@clipboard-health/groundcrew\"\u003e\u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/v/@clipboard-health/groundcrew?style=flat-square\u0026label=npm\u0026color=F7C600\u0026labelColor=111111\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@clipboard-health/groundcrew\"\u003e\u003cimg alt=\"downloads\" src=\"https://img.shields.io/npm/dw/@clipboard-health/groundcrew?style=flat-square\u0026label=downloads\u0026color=111111\u0026labelColor=111111\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/ClipboardHealth/groundcrew/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"ci\" src=\"https://img.shields.io/github/actions/workflow/status/ClipboardHealth/groundcrew/ci.yml?style=flat-square\u0026label=ci\u0026color=77d94e\u0026labelColor=111111\"\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg alt=\"license\" src=\"https://img.shields.io/npm/l/@clipboard-health/groundcrew?style=flat-square\u0026label=license\u0026color=111111\u0026labelColor=111111\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"./static/demo.tape\"\u003e\u003cimg alt=\"Groundcrew dispatching tasks into tmux panes with coding agents running in parallel\" src=\"./static/demo.gif\" width=\"800\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nGroundcrew 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)_.\n\n## Why\n\n- **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.\n- **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.\n- **One worktree per task.** Agents work in parallel without stepping on each other.\n- **Sandboxed by default.** Safehouse or Docker Sandboxes isolate each agent on the host; `none` is an explicit escape hatch.\n- **Pluggable task sources.** Linear by default; Jira and local files via [task sources](./docs/task-sources.md).\n- **Multi-agent routing.** Ships `claude` and `codex` presets; bring your own CLI in config.\n\n## Prerequisites\n\n`crew doctor` checks all of these, so you can install as you go.\n\n- **Node \u003e= 24:** [nvm](https://github.com/nvm-sh/nvm): `nvm install 24`.\n- **git:** e.g., `brew install git`, `apt install git`.\n- **A terminal multiplexer:** [tmux](https://github.com/tmux/tmux/wiki/Installing) (cross-platform), [cmux](https://cmux.com/) (macOS), or [zellij](https://zellij.dev/).\n- **An agent CLI:** [Claude Code](https://code.claude.com/docs/en/quickstart) and/or [Codex](https://developers.openai.com/codex/quickstart?setup=cli).\n- **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`.\n\n## Quickstart\n\n```bash\n# 1. Install groundcrew.\nnpm install -g @clipboard-health/groundcrew@latest\n\n# 2. Scaffold a global config. Agents are sandboxed by default\n#    (Safehouse/Docker Sandboxes); add --runner none to run unsandboxed on the host.\ncrew init --global --project-dir ~/dev --repo OWNER/REPO --agent claude\n\n# 3. Run the clone commands printed by `crew init`.\n\n# 4. Safehouse runs use groundcrew's bundled clearance allowlist automatically.\n#    Add extra hosts later via CLEARANCE_ALLOW_HOSTS or CLEARANCE_ALLOW_HOSTS_FILES.\n\n# 5. Using Linear? Export your API key. (Jira and other trackers: see Task Pickup.)\nexport GROUNDCREW_LINEAR_API_KEY=\"lin_api_...\"\n\n# 6. Verify setup, then dispatch.\ncrew doctor\ncrew run --watch\n```\n\n`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.\n\n## Task Pickup\n\n**Not on Linear?** Use Jira or local files via [task sources](./docs/task-sources.md).\n\nLinear works out of the box: assign tasks to yourself and add an `agent-*` label.\n\n- `agent-claude`, `agent-codex`, or `agent-\u003cname\u003e` routes to that agent.\n- `agent-any` routes to the enabled agent with the most session headroom, after skipping agents over their session limit or weekly paced budget.\n- Tasks without an `agent-*` label are ignored by `crew run`; dispatch one manually with `crew start \u003cTASK\u003e`.\n\nGroundcrew scans `workspace.knownRepositories` to infer which repo a task belongs to.\n\nA task blocked by non-terminal blockers is skipped until those blockers are done.\n\n### The task description is the prompt\n\nGroundcrew 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.\n\nWrite 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.\n\n## Commands\n\n```bash\ncrew init [--global | --local] [--force] [--dry-run]     # create a crew.config.ts\n          [--project-dir \u003cdir\u003e] [--repo \u003crepo\u003e]...\n          [--runner \u003cauto|safehouse|sdx|none\u003e] [--agent \u003cclaude|codex\u003e]\ncrew doctor                                              # check setup\ncrew source list|verify [\u003csource\u003e]                       # inspect configured task sources\ncrew task list [--source \u003cname\u003e]                         # list tasks across sources\ncrew task get \u003cTASK\u003e [--source \u003cname\u003e] [--prompt]        # inspect one task or its prompt\ncrew task create \"Title\" --source \u003cname\u003e [--agent \u003cname\u003e] # create a source task\ncrew task validate [\u003csource\u003e]                            # validate task content\ncrew status [\u003cTASK\u003e]                                   # inspect current state or one task\ncrew run [--watch]                                       # one-shot or --watch forever\ncrew start \u003cTASK\u003e                                      # provision + launch one task now\ncrew stop \u003cTASK\u003e [--reason \u003ctext\u003e]                     # stop workspace, keep worktree\ncrew resume \u003cTASK\u003e                                     # reopen a paused task\ncrew cleanup [--force] \u003cTASK\u003e                          # tear down every worktree for a task\ncrew upgrade [\u003cversion\u003e]                                 # reinstall crew globally through npm\n```\n\nSee [command details](./docs/commands.md) for status output, doctor behavior, and the stop/resume workflow.\n\n## Configuration\n\nWorkspace settings and at least one enabled agent are required; everything else has a default.\n\n```ts\nimport type { Config } from \"@clipboard-health/groundcrew\";\n\nexport default {\n  workspace: {\n    projectDir: \"~/dev\",\n    // Optional: all worktrees go here regardless of where each repo lives.\n    // worktreeDir: \"~/dev/worktrees\",\n    // Strings live under projectDir; use { name, projectDirOverride } to override per repo.\n    knownRepositories: [\"OWNER/REPO\"],\n  },\n  agents: {\n    default: \"claude\",\n    definitions: {\n      claude: {},\n    },\n  },\n  defaults: {\n    hooks: {\n      // No-op placeholder; replace with your repo's setup, e.g. \"npm ci\".\n      prepareWorktree: \"true\",\n    },\n  },\n} satisfies Config;\n```\n\nChanging `workspace.worktreeDir` only affects worktrees discovered under the new\nroot. Clean up existing worktrees before switching it, or temporarily unset\n`worktreeDir` when you need `crew cleanup` to find worktrees created beside the\nrepos.\n\nThere is no `linear` config block. Groundcrew reads `GROUNDCREW_LINEAR_API_KEY` first, then falls back to `LINEAR_API_KEY`.\n\n## Reference\n\n- [Configuration](./docs/configuration.md): discovery order, repo layout, scripted/sparse-checkout (graft) worktrees, full config table, prompt customization.\n- [Runners](./docs/runners.md): Safehouse, Docker Sandboxes, and the `none` escape hatch.\n- [Credentials](./docs/credentials.md): Linear API keys, 1Password, build secrets, and `preLaunch`.\n- [Prepare worktree hooks](./docs/setup-hooks.md): `.groundcrew/config.json` `hooks.prepareWorktree` for per-repo dependency setup.\n- [Task sources](./docs/task-sources.md): custom shell/Jira/local-plan adapters.\n- [Development](./docs/development.md): local source workflow and README/demo asset regeneration.\n- [Troubleshooting](./docs/troubleshooting.md): common operational pitfalls and fixes.\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclipboardhealth%2Fgroundcrew","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclipboardhealth%2Fgroundcrew","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclipboardhealth%2Fgroundcrew/lists"}