open-agent-teams

open-agent-teams

Run any CLI agent as an executor inside a detached tmux session. Communication is: prompt in via CLI arg / send-keys, completion out via a file sentinel the agent touches, summary out via a result file the agent writes. File sentinels are used instead of tmux wait-for because a wait-for -S with no waiter is silently lost; files never race and allow timeouts.

All commands via the helper (make sure it runs from the skill dir):

SKILL_DIR/scripts/tdel

Initial setup (once per repo)

If the repo's CLAUDE.md (or AGENT.md) has no delegation rules yet, add the contents of references/CLAUDE.delegation-template.md to it — it defines the coordinator/executor roles and the ROLE: EXECUTOR prompt marker used below.

Workflow

1. Start an agent on a task:

   tdel start <session> "<agent-cmd>" "<prompt>"
   # e.g. tdel start hello "claude --dangerously-skip-permissions" "make a hello world page"
   

   This appends the done-protocol to the prompt automatically (write summary to result file, then touch the done file).

2. Wait for completion — ALWAYS via a background Bash task so you get woken up instead of blocking or polling:

   tdel wait <session> [timeout-sec]     # run with run_in_background: true
   

   Exit 0 = done (prints the agent's summary). Exit 124 = timeout (prints last pane lines for diagnosis). Non-zero also if the session died.

3. Review the output (tdel result <session>, plus inspect the actual files the agent changed). If iteration is needed:

   tdel send <session> "<feedback / next instruction>"
   tdel wait <session>                   # again, run_in_background
   

   Each send is a new turn with its own done/result files — no signal cross-talk between turns.

4. Debug a stuck or slow agent: tdel peek <session> [lines] shows the live pane. tdel status lists all sessions.

5. Stop when finished: tdel stop <session> (kills the session and removes state under /tmp/agent-delegate/<session>).

Harness reference

How to launch each CLI agent autonomously (prompt is passed as the last positional arg by tdel start):

Harness	agent-cmd for tdel start	Busy-pane signature	Exit	Interrupt
claude	claude --dangerously-skip-permissions (--model, --effort low..max)	esc to interrupt	/exit	Escape
codex	codex --dangerously-bypass-approvals-and-sandbox (--model, -c 'model_reasoning_effort="low..xhigh"')	esc to interrupt	/quit	Escape
grok	grok --always-approve (--model, --reasoning-effort low|medium|high)	Ctrl+c:cancel	Ctrl+Q twice within 1s (NOT /exit, NOT Ctrl+C)	Ctrl+C (Escape does NOT interrupt)
pi	pi (--model, --thinking low..max; no permission system — always autonomous)	Working...	/quit	Escape
opencode	opencode --prompt-style launch (--model provider/model)	esc interrupt (no "to")	/exit	double Escape (flaky mid-shell-command)

Busy signatures matter on timeout: peek and grep for the signature — present = still working (extend the wait), absent = idle (it likely finished without touching the done file, or is stuck at a prompt).

Trust dialogs (first run per repo/worktree): claude (trust/bypass-permissions confirm), codex ("Do you trust..."), and pi can each show a dialog that blocks the prompt from processing. After start, peek within ~20s; if a dialog is showing, accept it with tdel key <session> Enter and verify via another peek that the task started. grok skips its picker when launched inside a git repo root.

Slash/skill popup hazard: prompts beginning with / or $ (skill invocations: /<skill> on claude/grok, $<skill> on codex) open an autocomplete popup — a fast Enter selects the popup instead of submitting, and grok needs a genuine second Enter. tdel send handles this automatically (longer settle + double Enter for /- or $-prefixed prompts).

Resume after exit: codex codex resume <session-id>, grok grok --resume <session-id> (ids printed on quit), opencode relaunch with --continue.

Rules

• Prompts must be self-contained (context, constraints, expected output) — the executor can't see your conversation. Prefix with the repo's executor marker (ROLE: EXECUTOR ...) when the agent is Claude Code in a repo using the delegation rules (see Initial setup above).
• Prompts are flattened to one line before sending (newlines would submit a TUI input box early) — write them accordingly; put large specs in a file and reference the path.
• On timeout, peek first — agents sometimes finish but forget to touch the done file. If the work is visibly done, treat pane output + changed files as the result and stop or send a reminder.
• Don't trust capture-pane as the deliverable — it's a rendered TUI snapshot. The result file and the actual changed files are the source of truth.
• One task per session; parallel tasks = parallel sessions with distinct names.