Waspflow
tnunamak/waspflow
Orquestração de agentes de código em tmux com estado persistente
Ver no GitHubOrquestrador de agentes de codificação (Claude, Codex, Grok) em sessões tmux duráveis. Permite spawnar workers, monitorar progresso, fazer correções e recuperar artefatos salvos de forma controlada.
Instalação
npx convez-ai tnunamak/waspflow1 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
Casos de uso
- Executar tarefas de coding com IA de forma durável e recuperável
- Monitorar e ajustar agentes de codificação em tempo real
- Reutilizar contexto e histórico de agentes em múltiplas execuções
Veredito

Ferramenta sólida para pipelines de automação de código com agentes, mas requer profunda familiaridade com shell, tmux e CLIs de provedores. Estável em modo de manutenção.
README
A tradução para o português deste README ainda está na fila.
waspflow
Waspflow runs coding-agent work in durable tmux lanes. Start a worker, inspect it, steer it, wait for a terminal turn, and deliberately reap its saved artifacts.
Status: maintenance mode — bug fixes only. Report bugs in GitHub Issues.
Quickstart
git clone https://github.com/tnunamak/waspflow /path/to/waspflow
cd /path/to/waspflow && ./install.sh
export PATH="$HOME/.local/bin:$PATH" # or the directory printed by install.sh
waspflow doctor
waspflow demo --provider codex --run
Replace codex with an installed provider, such as claude, grok, or antigravity (agy). install.sh creates a symlink in $HOME/.local/bin unless WASPFLOW_INSTALL_BIN is set.
What a lane contains
A lane keeps its prompt, transcript, session details, final git capture, and state under $WASPFLOW_HOME (default: ${XDG_STATE_HOME:-$HOME/.local/state}/waspflow). It is useful when a worker needs follow-up instructions or you need to recover its state after closing a terminal.
waspflow spawn --provider codex --accept-provider-default --lane fix -- \
"Find and fix the failing test."
waspflow wait fix
waspflow revise fix -- "Add a regression test."
waspflow wait fix --reap
Use waspflow exec for a headless, one-shot task that does not create a lane:
waspflow exec --provider claude --accept-provider-default -- \
"Summarize the public functions in lib/core.sh."
Provider support matrix
supported means the adapter implements the command. partial means it works but has an important evidence limit.
| Provider | spawn | wait (completion detection) | revise (steer) | reap | exec |
|---|---|---|---|---|---|
| Claude | supported | supported | supported | supported | supported |
| Codex | supported | partial — rollout correlation risk | supported | supported | supported |
| Grok | supported | partial — weaker completion evidence | partial — weaker submission evidence | supported | supported |
Antigravity (agy) | partial — receipt-based submission | partial — receipt-based completion | partial — headless revise only | supported | supported |
| Qwen | supported | supported | supported | supported | supported |
DeepSeek (dsh) | supported | supported | unsupported — start a new lane with the complete task | supported | supported |
Claude has the strongest completion detection: Waspflow waits for terminal turn events and vetoes completion while known child or background-shell work remains active. Codex correlates rollout events with the lane’s turn; very new Codex versions can still drift from that event shape. Grok and Antigravity deliberately fail closed when submission or completion evidence is insufficient.
On first Codex use, an update or trust menu can appear. Waspflow refuses to paste into an unresolved startup menu because an Enter could select an unsafe menu item instead of submitting your task, so the spawn exits 3 and the lane stays recorded but never ran. Answer the menu in the pane (waspflow attach <lane>), then run waspflow reap <lane> --force and spawn again. A lane stopped at a menu cannot be resumed in place, and its reap reports report_missing.
Requirements
Required tools are Bash 4 or later, GNU-compatible find and timeout, tmux, jq, awk, python3, git, flock, and perl, plus uuidgen or Linux /proc/sys/kernel/random/uuid, and at least one provider CLI. For DeepSeek, also configure its dsh headless profile. waspflow doctor checks basic availability before you start; it does not establish full platform compatibility. See prerequisites for installation notes.
Providers map to executables as follows: claude, codex, grok, antigravity → agy, qwen, and deepseek → dsh.
Common commands
| Command | Purpose |
|---|---|
spawn --provider … --lane NAME -- TASK | Start a durable lane. |
wait NAME [--reap] | Poll until a terminal turn; optionally reap it. |
peek NAME | Inspect the tmux pane for diagnosis. |
status NAME / list | Inspect saved lane state. |
revise NAME -- MESSAGE | Send a follow-up instruction. |
reap NAME | Finalize a terminal lane. |
reconcile --json | Read-only fleet recovery inventory. |
doctor | Check dependencies and fleet warnings. |
Use --isolate on spawn when workers should get separate Git worktrees. --report PATH requires a non-empty report before normal reaping succeeds. See waspflow help for the complete option reference.
Known limitations
- Lanes keep running if the spawning agent dies, but Waspflow cannot push completion into a new session. Use
waspflow list,status, orwait; usewaspflow reconcile --jsonanddoctorto investigate uncertain or orphaned state. - There is no completion callback:
waitpolls provider logs. - Worktree isolation is not an OS sandbox. Lanes run provider CLIs with permissive provider modes; only run tasks you trust.
- Waspflow uses
systemd-run --user --scopefor scope tracking when available. Without it, it warns and continues with tmux-only supervision; lifecycle state can remain unknown and cleanup has less process-tree evidence. - Set
WASPFLOW_TMUX_SOCKET=nameto make every Waspflow tmux call usetmux -L nameinstead of your default tmux server. Export it in every shell that manages those lanes; a new shell without it looks at the default server and will not see them. reviseon Codex can report "not confirmed submitted" even though the message was applied. Runwaspflow peek NAMEbefore sending it again.- Codex lanes use whichever
codexthe lane's login shell resolves, which can differ from the one in your current shell. If a stale copy shows an update prompt, update or remove the older install. reaprefuses a live lane that the provider does not report as idle unless you pass--force.- Legacy tmux windows without Waspflow ownership tags are not adopted automatically; explicit legacy adoption is required for parking.
- Provider CLIs change their TUIs and event formats. Live behavior can drift; stalled waits should be diagnosed with
waspflow peek. - Billing has no guarantee. Subscription versus API billing depends on the provider’s active authentication; read
waspflow doctorbefore a large run.
Security and operations
Use a dedicated tmux socket when you do not want Waspflow windows on your normal server:
export WASPFLOW_TMUX_SOCKET=waspflow
waspflow doctor
The default state directory holds prompts and transcripts. Treat it as sensitive local data. WASPFLOW_HOME changes where that state is stored.
More documentation
- Full reference (selection gates, worktrees, reports, environment variables, wait internals)
- First run
- Prerequisites
- Project checks
- MCP behavior
Verify
The test suite requires Bash 4 or later and ripgrep (rg). Run it with:
scripts/verify.sh
License
Apache-2.0. See LICENSE.