Claude Code Dispatch Skill

Dispatch development tasks to Claude Code with automatic notification on completion. Zero polling, zero token waste.

Architecture

dispatch.sh
  → write task-meta.json
  → launch Claude Code via claude_code_run.py (PTY wrapper)
  → [Agent Teams: --agents JSON defines Testing Agent + custom subagents]
  → Claude Code finishes → Stop/TaskCompleted hook fires automatically
    → notify-agi.sh reads meta + output
    → writes latest.json
    → sends Telegram notification (group + callback)
    → writes pending-wake.json (heartbeat fallback)

Quick Reference

Basic dispatch

⚠️ Always use nohup + background (&) — dispatch runs until done.

nohup bash scripts/dispatch.sh \
  -p "Build a Python REST API with FastAPI" \
  -n "my-api" \
  -g "-5006066016" \
  --permission-mode bypassPermissions \
  --workdir /home/ubuntu/projects/my-api \
  > /tmp/dispatch-my-api.log 2>&1 &

With Agent Teams

nohup bash scripts/dispatch.sh \
  -p "Build a full-stack app with React + Express" \
  -n "fullstack-app" \
  --agent-teams \
  --permission-mode bypassPermissions \
  --workdir /home/ubuntu/projects/fullstack-app \
  > /tmp/dispatch-fullstack.log 2>&1 &

When --agent-teams is passed without --agents-json, a default Testing Agent is auto-defined via the --agents CLI flag (structured JSON, not prompt injection).

With cost controls

nohup bash scripts/dispatch.sh \
  -p "Refactor the database layer" \
  -n "db-refactor" \
  --max-budget-usd 5.00 \
  --max-turns 50 \
  --fallback-model sonnet \
  --permission-mode bypassPermissions \
  --workdir /home/ubuntu/projects/my-app \
  > /tmp/dispatch-refactor.log 2>&1 &

With custom subagents

nohup bash scripts/dispatch.sh \
  -p "Build CLI tool" \
  -n "cli-tool" \
  --agent-teams \
  --agents-json '{"security-reviewer":{"description":"Security expert","prompt":"Review for vulnerabilities","tools":["Read","Grep","Glob"],"model":"opus"}}' \
  --permission-mode bypassPermissions \
  --workdir /home/ubuntu/projects/cli-tool \
  > /tmp/dispatch-cli.log 2>&1 &

With git worktree isolation

nohup bash scripts/dispatch.sh \
  -p "Implement feature X" \
  -n "feature-x" \
  --worktree feature-x \
  --permission-mode bypassPermissions \
  --workdir /home/ubuntu/projects/my-app \
  > /tmp/dispatch-feature.log 2>&1 &

All Parameters

Param	Short	Description
`--prompt`	`-p`	Task description (required*)
`--prompt-file`		Read prompt from file (required*)
`--name`	`-n`	Task name for tracking
`--group`	`-g`	Telegram group ID for notifications
`--workdir`	`-w`	Working directory
`--agent-teams`		Enable Agent Teams mode
`--agents-json`		Custom subagent definitions (JSON)
`--teammate-mode`		Display: `auto` / `in-process` / `tmux`
`--permission-mode`		`bypassPermissions` / `plan` / `acceptEdits` / `default`
`--allowed-tools`		Tool allowlist
`--disallowed-tools`		Tool denylist
`--model`		Model override (sonnet/opus/haiku/full name)
`--fallback-model`		Auto-fallback when primary is overloaded
`--max-budget-usd`		Maximum dollar spend before stopping
`--max-turns`		Maximum agentic turns
`--worktree`		Git worktree name for isolation
`--no-session-persistence`		Don't save session to disk
`--append-system-prompt`		Append text to system prompt
`--append-system-prompt-file`		Append system prompt from file
`--mcp-config`		Load MCP servers from JSON file
`--verbose`		Enable verbose logging
`--callback-group`		Callback to dispatching agent's group
`--callback-dm`		DM callback user ID
`--callback-account`		DM callback bot account
`--session`	`-s`	Callback session key

* One of --prompt or --prompt-file is required.

Hook Setup

See references/hook-setup.md for full hook configuration. The skill uses Stop, TaskCompleted, and SessionEnd hooks with the notify-agi.sh script. HTTP hooks are also supported as an alternative.

Prompt Tips

See references/prompt-guide.md for examples and best practices, including cost control, Agent Teams, worktree isolation, custom subagents, and MCP integration.

Debugging

# Watch hook log
tail -f data/claude-code-results/hook.log

# Check latest result
cat data/claude-code-results/latest.json | jq .

# Check task metadata
cat data/claude-code-results/task-meta.json | jq .

# Test Telegram delivery
openclaw message send --channel telegram --target "-5006066016" --message "test"

# Check dispatch log
tail -f /tmp/dispatch-*.log

Gotchas

Must use PTY wrapper — Direct claude -p can hang in exec environments
Hook fires twice — Stop + SessionEnd both trigger; .hook-lock deduplicates (30s window)
Hook stdin is empty in PTY — Output read from task-output.txt, not stdin
tee pipe race — Hook sleeps 1s for pipe flush before reading output
Meta freshness — Hook validates meta age (<2h) and session ID
Agent Teams cost — Use --max-budget-usd to cap spend on multi-agent tasks
Rate limits — Claude Code has daily rate limits resetting at 11:00 UTC; check hook.log for "limit" messages