convez.ai
AgenteAutomaçãoAvançado
ClipboardHealth

Groundcrew

ClipboardHealth/groundcrew

Despache tarefas para agentes IA locais em worktrees sandboxed

Ver no GitHub
BomPluginScore · de 0 a 100

Agent que despacha tarefas do seu backlog para agentes de IA locais e interativos, cada um executando em uma git worktree isolada. Funciona com Claude Code ou Codex, monitorando fluxos de trabalho em tmux/zellij e deixando cada tarefa pronta para PR.

Instalação

$npx convez-ai ClipboardHealth/groundcrew

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
68
Forks
11
Acompanhando
0
Saúde
75%
Último commit
há 1 dia
Versão
groundcrew@4.53.5
Issues abertas
3
Contribuidores
18

Casos de uso

  • Automação de tickets em PRs prontas
  • Execução paralela de múltiplas tarefas de codificação
  • Fluxos de trabalho com agentes interativos monitoráveis

Veredito

Ferramenta madura e bem-arquitetada para quem quer agentes IA executando localmente com controle total. Exige setup substancial (Node 24+, multiplexador, sandbox runner) mas entrega isolamento real e workflows paralelos de alto valor.

README

A tradução para o português deste README ainda está na fila.

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.

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.
  • 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), cmux (macOS), or zellij.
  • 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@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.

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

  • agent-claude, agent-codex, or agent-<name> 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 <TASK>.

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

crew init [--global | --local] [--force] [--dry-run]     # create a crew.config.ts
          [--project-dir <dir>] [--repo <repo>]...
          [--runner <auto|safehouse|sdx|none>] [--agent <claude|codex>]
crew doctor                                              # check setup
crew source list|verify [<source>]                       # inspect configured task sources
crew task list [--source <name>]                         # list tasks across sources
crew task get <TASK> [--source <name>] [--prompt]        # inspect one task or its prompt
crew task create "Title" --source <name> [--agent <name>] # create a source task
crew task validate [<source>]                            # validate task content
crew status [<TASK>]                                   # inspect current state or one task
crew run [--watch]                                       # one-shot or --watch forever
crew start <TASK>                                      # provision + launch one task now
crew stop <TASK> [--reason <text>]                     # stop workspace, keep worktree
crew resume <TASK>                                     # reopen a paused task
crew cleanup [--force] <TASK>                          # tear down every worktree for a task
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 agent are required; everything else has a default.

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: discovery order, repo layout, scripted/sparse-checkout (graft) worktrees, 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.
  • Task sources: custom shell/Jira/local-plan adapters.
  • Development: local source workflow and README/demo asset regeneration.
  • Troubleshooting: common operational pitfalls and fixes.

License

MIT

Ver o original no GitHub

Bom para

Relacionados