convez.ai
AgenteAutomaçãoAvançado
frapercan

Agent Farm

frapercan/agent-farm

Orquestrador eficiente de agents Claude com estado persistente e escopo de permissões

Ver no GitHub
InicialPluginScore · de 0 a 100

Orquestrador manual de agents Claude especializados que spawna subagents sob demanda com estado SQLite e escopos de permissão isolados por agent. Otimizado para trabalho de engenharia de longa duração sem desperdício de tokens em loops sempre-ativos.

Instalação

$npx convez-ai frapercan/agent-farm

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
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 dias
Versão
—
Issues abertas
39
Contribuidores
1

Casos de uso

  • Automação de deploys com escalação inteligente para Claude apenas em falhas
  • Coordenação de múltiplos agents especializados (executor, doc-writer, shepherd) em projetos grandes
  • Processamento em batch de tarefas custosas com agents headless persistentes ou one-shot

Veredito

Solução robusta para times que precisam orquestrar múltiplos agents Claude em paralelo, reduzindo consumo de tokens ao invocar IA apenas sob demanda. Requer experiência em Python e conhecimento do ecosistema Claude para extrair máximo valor.

README

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

agent-farm

Manual-orchestration agent farm. A conductor session spawns specialised Claude Code agents (subagents, headless one-shots, headless persistents) on demand, records their state in sqlite, and gives the human a single tabla-de-mando to drive long-running engineering work without paying for a wall-to-wall cron baseline.

The agent zoo is project-agnostic by construction: agents are defined as a prompts/<name>.md + agents/<name>.yaml pair, registered via the registry helpers in scripts/lib/, and dispatched by the conductor or by slash commands. Wire any project in by writing its prompts and pointing the agents at its repos.

Why this exists

Always-on agentic loops (cron + Claude every 5-30 min) burn token budget even on quiet days. Long-running deploys leave a Claude session blocked just to babysit a healthy process. Per-project orchestrators leak credentials between unrelated repos. agent-farm separates the three concerns:

  • bash happy-path for any deterministic work (deploys, embeddings dispatch), invoking Claude only on failure
  • subagents on demand for cognitive work (executor, doc-writer, shepherd) spawned by a conductor in natural language
  • per-agent permission scope baked into each agent yaml, no global blast-radius

Token efficiency analysis with concrete numbers: see docs/token-savings.md.

Agent zoo (current)

Persistent services

AgentKindModelPurpose
deploy-keeperheadless persistenthaikukeep develop deployed on the configured tunnel; escalate to Claude only on failure

One-shot batch jobs (headless)

AgentKindModelPurpose
embeddings-runnerheadlesshaikudispatch + poll PROTEA /jobs for massive embedding batches

Subagents (spawned by conductor via Agent tool)

AgentKindModelPurpose
executorsubagentopusimplement one master plan slice, open PR
janitorsubagenthaikutrivial CI/PR cleanup across the repo stack
shepherdsubagentsonnetscan state + recommend next priorities
doc-writersubagentsonnetsync docs ↔ código, write ADRs
thesis-writersubagentsonnetsync LaTeX manuscript with código + experiments
playwright-platformsubagenthaikue2e test the platform UI live
bioinfo-quicksubagentsonnetchoose + run next experiment in the lab repo
ux-reviewersubagentsonnetaudit UX of platform, prioritized findings
frontend-designersubagentopusimplement UX recommendations on the web app, open PR

Add a new one: cp agents/_template.yaml agents/<new>.yaml + write prompts/<new>.md.

Layout

agent-farm/
├── README.md
├── agents/                      # type registry (one yaml per agent type)
│   ├── _template.yaml
│   └── <name>.yaml
├── prompts/                     # system prompt bodies (one per agent)
│   ├── conductor.md
│   └── <name>.md
├── scripts/
│   ├── init.sh                  # init sqlite from schema
│   ├── spawn.sh                 # spawn an agent (headless kinds)
│   ├── spawn-subagent.sh        # spawn helper for the Agent tool
│   ├── status.sh                # tabla live tasks
│   ├── kill.sh                  # cancel + cleanup
│   ├── cleanup.sh               # GC stale tmux/worktrees
│   ├── plan-progress.sh         # parse plans/<loop>/PLAN.md + join sqlite
│   ├── launch-conductor.sh      # boot the conductor in tmux
│   ├── lib/                     # shared bash + python helpers
│   ├── hooks/                   # worktree lifecycle hooks
│   └── services/                # per-persistent-agent supervisor + tick
├── docs/
│   └── token-savings.md         # cost analysis + 5 levers
├── state/
│   ├── schema.sql
│   └── tasks.sqlite             # created by init.sh; gitignored
└── results/                     # per-task artifacts; gitignored

state/ and results/ are runtime data, not source — they are gitignored.

Bootstrap

# 1. create sqlite
bash ~/Thesis2/agent-farm/scripts/init.sh

# 2. boot conductor — autoyes ON by default
bash ~/Thesis2/agent-farm/scripts/launch-conductor.sh

# 3. attach
tmux attach -t agent-farm

Inside the conductor session, paste:

Lee ~/Thesis2/agent-farm/prompts/conductor.md y operá como conductor.

Autoyes modes (set via env var at launch)

AGENT_FARM_AUTOYES=Behavior
1 (default)--dangerously-skip-permissions — zero prompts anywhere
accept--permission-mode acceptEdits — auto on edits + safe bash; prompts on rm, push, etc
0no flag — every tool prompt asked

To change after launch: tmux kill-window -t agent-farm:conductor && AGENT_FARM_AUTOYES=accept bash launch-conductor.sh.

Headless agents (deploy-keeper, embeddings-runner) are independent of this — they always launch with --dangerously-skip-permissions per their yaml permissions: bypassPermissions. Only the conductor's mode (which subagents inherit) is configurable here.

Daily use

From the conductor session (natural language)

Inside the conductor tmux window, just talk:

  • "spawn deploy-keeper" → conductor calls spawn.sh deploy-keeper
  • "smoke test the docs" → conductor uses the Agent tool with the docs prompt
  • "what's running?" → conductor runs status.sh
  • "kill the bioinfo task" → conductor finds task_id and runs kill.sh

Slash commands (also work from any session)

Install the slash commands to ~/.claude/commands/:

bash ~/Thesis2/agent-farm/commands/install.sh

Then use:

/agent-farm-conductor                # load conductor identity (run first)
/agent-farm-agents                   # list agent types
/agent-farm-spawn <agent> [spec]     # spawn (headless via shell, subagent via Agent tool)
/agent-farm-status [task_id|--all]   # tabla of live (or detail / 24h history)
/agent-farm-kill <task_id>           # cancel + cleanup
/agent-farm-cleanup                  # GC stale tmux/worktrees
/agent-farm-plan [`--phase` PH|`--next`]  # plan progress, next pickable slice

Plan tracking

The agent-farm is plan-aware. The canonical plan store lives at plans/<loop>/PLAN.md (one Markdown file per loop, each ### <title> slice carrying a yaml frontmatter block with id, phase, loop, status, deps, priority, etc; see plans/README.md). scripts/plan-progress.sh walks every loop's plan, joins with the sqlite executor task history (via the spawn_args.slice convention), and reports which slices are pickable, in flight, blocked, or done. --next picks the highest-priority pickable slice across all loops.

Convention: every executor spawn MUST include slice and phase in spawn_args (the executor prompt enforces this). Example:

/agent-farm-spawn executor '{"slice":"FARM-2.7","phase":"F-FARM-2","notes":"refactor plan_parser to read plans/<loop>/PLAN.md"}'

Direct shell (when scripting / automation)

bash ~/Thesis2/agent-farm/scripts/spawn.sh deploy-keeper
bash ~/Thesis2/agent-farm/scripts/status.sh
bash ~/Thesis2/agent-farm/scripts/kill.sh <task_id>
bash ~/Thesis2/agent-farm/scripts/cleanup.sh --apply

See also

  • docs/features/ (one markdown page per first-class capability, auto-indexed by docs/features/README.md)
  • docs/token-savings.md — concrete cost analysis, daily budget table, the 5 levers that keep this cheap
  • prompts/conductor.md — conductor system prompt (read first if you're orchestrating manually)
  • agents/_template.yaml — copy this to add a new agent type

Quick reference card

SPAWN:     /agent-farm-spawn <agent> [spec]   OR    bash scripts/spawn.sh <agent>
STATUS:    /agent-farm-status                  OR    bash scripts/status.sh
KILL:      /agent-farm-kill <task_id>          OR    bash scripts/kill.sh <id>
CLEANUP:   /agent-farm-cleanup                 OR    bash scripts/cleanup.sh --apply
AGENTS:    /agent-farm-agents                  OR    ls agents/*.yaml
ATTACH:    tmux attach -t agent-farm
SUPERVISOR LOG: tmux attach -t agent-farm → Ctrl-b w → pick supervisor window
Ver o original no GitHub

Bom para

Relacionados