mav/orchestrate-skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f5097928720adac8897ea230ce4f1f8f7273dc08
orchestrate-skill/README.md
mav f509792872 Add orchestrate skill: main-actor pattern + mav-agent/mav-tmux wrappers 
One bot owns the chat and delegates coding to persistent tmux sub-agents,
using a .done file marker for a reliable handoff (status/wait/result).
Includes README + install.sh for one-command setup.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-29 11:31:15 +02:00

1.9 KiB
Raw Blame History

orchestrate-skill

The main-actor pattern for bot teammates. One bot owns the chat and never blocks — it delegates real coding/build work to persistent tmux sub-agents, polls a done-marker, and reports results back.

One voice talks, hands stay clean.

What's inside

skill/SKILL.md   the skill itself (the playbook, conventions, anti-patterns)
bin/mav-agent    spawn/observe named claude or codex sub-agents (one tmux window each)
bin/mav-tmux     run a one-off command in the shared persistent tmux session
install.sh       drop the skill + wrappers into your ~/.claude and ~/.local/bin

Why

If you do heavy work inline in your own turn, the chat freezes and the work dies when your session compacts or restarts. Instead: spawn the work in a tmux window that outlives your turn, and use a real file marker for the handoff so you always know when it's finished — no prompt-sniffing, no guessing.

The clean handoff

Every mav-agent run writes, when the CLI exits:

  • /tmp/mav-agent/<name>.out — full stdout/stderr
  • /tmp/mav-agent/<name>.done — exit code (present only when finished)

mav-agent status / wait poll the marker. Present ⇒ done. That's the whole trick.

Install

git clone https://git.sevara.cloud/mav/orchestrate-skill.git
cd orchestrate-skill && ./install.sh

Requires tmux, plus claude and/or codex on PATH. Then the /orchestrate skill shows up in your Claude Code session and the mav-agent/mav-tmux CLIs are on your PATH.

The loop

  1. Acknowledge in chat fast — never a silent turn.
  2. mav-agent run <name> "<self-contained task with full context>"
  3. mav-agent wait <name> 60 (short) or end turn + mav-agent status <name> next wake.
  4. On done: mav-agent result <name>, summarize, reply. Check the exit code.
  5. mav-agent kill <name> once you've read it.

See skill/SKILL.md for the full reference.