convez.ai
AgenteAutomaçãoAvançado
tnunamak

Waspflow

tnunamak/waspflow

Orquestração de agentes de código em tmux com estado persistente

Ver no GitHub
InicialPluginScore · de 0 a 100

Orquestrador 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/waspflow

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
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 semanas
Versão
v1.9.8
Issues abertas
9
Contribuidores
3

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.

Providerspawnwait (completion detection)revise (steer)reapexec
Claudesupportedsupportedsupportedsupportedsupported
Codexsupportedpartial — rollout correlation risksupportedsupportedsupported
Groksupportedpartial — weaker completion evidencepartial — weaker submission evidencesupportedsupported
Antigravity (agy)partial — receipt-based submissionpartial — receipt-based completionpartial — headless revise onlysupportedsupported
Qwensupportedsupportedsupportedsupportedsupported
DeepSeek (dsh)supportedsupportedunsupported — start a new lane with the complete tasksupportedsupported

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

CommandPurpose
spawn --provider … --lane NAME -- TASKStart a durable lane.
wait NAME [--reap]Poll until a terminal turn; optionally reap it.
peek NAMEInspect the tmux pane for diagnosis.
status NAME / listInspect saved lane state.
revise NAME -- MESSAGESend a follow-up instruction.
reap NAMEFinalize a terminal lane.
reconcile --jsonRead-only fleet recovery inventory.
doctorCheck 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, or wait; use waspflow reconcile --json and doctor to investigate uncertain or orphaned state.
  • There is no completion callback: wait polls 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 --scope for 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=name to make every Waspflow tmux call use tmux -L name instead 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.
  • revise on Codex can report "not confirmed submitted" even though the message was applied. Run waspflow peek NAME before sending it again.
  • Codex lanes use whichever codex the 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.
  • reap refuses 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 doctor before 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

Verify

The test suite requires Bash 4 or later and ripgrep (rg). Run it with:

scripts/verify.sh

License

Apache-2.0. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados