agent-swarm-skill

Category: Tools & Productivity | Uploader: ayao99315 | Downloads: 0 | Version: v1.0（Latest）

Orchestrate multi-agent coding workflows in OpenClaw using tmux-driven Codex and Claude Code agents. Event-driven dispatch via git hooks, atomic task tracking, token accounting, cross-review, and Telegram notifications. Use when: (1) tasks should be parallelised across Codex + Claude Code agents, (2) you want event-driven swarm coordination with status tracking, (3) token usage needs to be logged per task. NOT for: simple one-liner edits, read-only analysis, or quick questions.

Changelog: Source: GitHub https://github.com/ayao99315/agent-swarm-skill

Directory Structure

Current level: Root

📁 docs/
- 📄 architecture.md 5.4 KB
- 📄 task-schema.md 6.5 KB
- 📄 troubleshooting.md 3.4 KB
📁 references/
- 📄 prompt-cc-frontend.md 2.0 KB
- 📄 prompt-cc-plan.md 1.4 KB
- 📄 prompt-cc-review.md 1.5 KB
- 📄 prompt-codex-deploy.md 2.5 KB
- 📄 prompt-codex-test.md 2.6 KB
- 📄 prompt-codex.md 2.3 KB
📁 scripts/
- 📄 agent-manager.sh 4.5 KB
- 📄 check-memory.sh 1.5 KB
- 📄 cleanup-agents.sh 2.4 KB
- 📄 dispatch.sh 6.5 KB
- 📄 health-check.sh 5.1 KB
- 📄 install-hooks.sh 5.1 KB
- 📄 milestone-check.sh 4.7 KB
- 📄 monitor.sh 2.7 KB
- 📄 on-complete.sh 8.8 KB
- 📄 parse-tokens.sh 3.2 KB
- 📄 spawn-agent.sh 4.5 KB
- 📄 update-agent-status.sh 1.1 KB
- 📄 update-task-status.sh 4.5 KB
📁 swarm/
- 📄 active-tasks.json.example 1.8 KB
- 📄 agent-pool.json.example 887 B
- 📄 hook-token.example 13 B
- 📄 notify-target.example 13 B
- 📄 project-dir.example 20 B
📄 .gitignore 140 B
📄 install.sh 4.6 KB
📄 LICENSE 1.1 KB
📄 README.md 7.6 KB
📄 README.zh.md 7.4 KB
📄 SKILL.md 5.7 KB

SKILL.md

---
name: agent-swarm-skill
description: "Orchestrate multi-agent coding workflows in OpenClaw using tmux-driven Codex and Claude Code agents. Event-driven dispatch via git hooks, atomic task tracking, token accounting, cross-review, and Telegram notifications. Use when: (1) tasks should be parallelised across Codex + Claude Code agents, (2) you want event-driven swarm coordination with status tracking, (3) token usage needs to be logged per task. NOT for: simple one-liner edits, read-only analysis, or quick questions."
metadata:
  {
    "openclaw": { "emoji": "🐝", "requires": { "anyBins": ["claude", "codex", "tmux"] } }
  }
---

# Agent Swarm

Coordinate multiple coding agents on one machine. You are the orchestrator: break work into atomic tasks, dispatch them to tmux sessions, verify scope, trigger cross-review, and keep the swarm moving.

## Use This Skill When

- A coding request should be split into parallel backend/frontend tasks
- The user wants agent delegation, swarm mode, or cross-review
- You need status tracking, token accounting, or event-driven follow-up after agent commits

Do not use this skill for one-line edits, read-only analysis, or quick answers that are faster to handle directly.

## Core Model

Typical fixed sessions:

- `cc-plan` for task decomposition
- `cc-review` for reviewing Codex output
- `codex-review` for reviewing Claude Code output
- `codex-*` for backend / general coding
- `cc-frontend-*` for frontend work

Dynamic coding sessions can be added when task volume exceeds idle capacity.

## Workflow

1. Send the requirement to `cc-plan` using [references/prompt-cc-plan.md](references/prompt-cc-plan.md).
2. Register tasks in `~/.openclaw/workspace/swarm/active-tasks.json`. Schema: [docs/task-schema.md](docs/task-schema.md).
3. Install the git hook once per project:

```bash
~/.openclaw/workspace/skills/agent-swarm/scripts/install-hooks.sh /path/to/project
```

4. Dispatch ready tasks with [scripts/dispatch.sh](scripts/dispatch.sh):

```bash
scripts/dispatch.sh <session> <task_id> "<agent command>"
```

5. Let the event loop handle completion:
- agent finishes
- `on-complete.sh` parses tokens and updates task state
- webhook wakes an isolated OpenClaw turn
- next ready task or cross-review is dispatched

6. Use `review_level` to decide post-completion handling:
- `full`: cross-review required
- `scan`: orchestrator inspects diff
- `skip`: scope verification only

## Non-Negotiable Rules

1. Use `dispatch.sh`, not ad-hoc tmux commands, so completion hooks and status updates always fire.
2. Each task should map to one atomic commit with explicit file scope.
3. Keep concurrent tasks file-isolated.
4. Backend/general code goes to Codex unless there is a stronger reason to choose Claude Code.
5. Frontend implementation goes to Claude Code.
6. Cross-review Codex output with Claude Code, and Claude Code output with Codex.

## Command Patterns

Claude Code with structured token output:

```bash
scripts/dispatch.sh cc-plan T000 "claude --model claude-opus-4-5 --permission-mode bypassPermissions --no-session-persistence --print --output-format json 'PROMPT_HERE'"
scripts/dispatch.sh cc-review T010 "claude --model claude-sonnet-4-5 --permission-mode bypassPermissions --no-session-persistence --print --output-format json 'PROMPT_HERE'"
scripts/dispatch.sh cc-frontend-1 T020 "claude --model claude-sonnet-4-5 --permission-mode bypassPermissions --no-session-persistence --print --output-format json 'PROMPT_HERE'"
```

Codex with configurable reasoning effort:

```bash
scripts/dispatch.sh codex-1 T001 "codex exec -c model_reasoning_effort=high --dangerously-bypass-approvals-and-sandbox 'PROMPT_HERE'"
scripts/dispatch.sh codex-1 T001 "codex exec -c model_reasoning_effort=extra-high --dangerously-bypass-approvals-and-sandbox 'PROMPT_HERE'"
scripts/dispatch.sh codex-1 T001 "codex exec -c model_reasoning_effort=medium --dangerously-bypass-approvals-and-sandbox 'PROMPT_HERE'"
```

Read recent agent output:

```bash
tmux capture-pane -t <session> -p | tail -40
```

Send a follow-up message into an interactive session:

```bash
tmux send-keys -t <session> -l -- "follow-up message"
tmux send-keys -t <session> Enter
```

## Escalate to the Human When

- Requirements or architecture choices are ambiguous
- Secrets, credentials, or production-only values are required
- A task is still stuck after retries and agent switching
- The requested change could delete important data or widen scope unexpectedly

## Key Files

- [references/prompt-codex.md](references/prompt-codex.md): backend/general coding prompt
- [references/prompt-cc-plan.md](references/prompt-cc-plan.md): planning prompt
- [references/prompt-cc-frontend.md](references/prompt-cc-frontend.md): frontend prompt
- [references/prompt-cc-review.md](references/prompt-cc-review.md): cross-review prompt
- [references/prompt-codex-test.md](references/prompt-codex-test.md): milestone testing prompt
- [references/prompt-codex-deploy.md](references/prompt-codex-deploy.md): deployment prompt
- [scripts/dispatch.sh](scripts/dispatch.sh): wraps agent execution in bash for reliable completion handling
- [scripts/on-complete.sh](scripts/on-complete.sh): parses tokens, updates status, triggers webhook, sends notifications
- [scripts/update-task-status.sh](scripts/update-task-status.sh): atomic task-state updates with `flock`
- [scripts/agent-manager.sh](scripts/agent-manager.sh): dynamic pool scaling and cleanup
- [scripts/install-hooks.sh](scripts/install-hooks.sh): installs the event-driven git hook

## Additional Documentation

- [docs/architecture.md](docs/architecture.md): end-to-end architecture and sequence flow
- [docs/task-schema.md](docs/task-schema.md): complete `active-tasks.json` schema and examples
- [docs/troubleshooting.md](docs/troubleshooting.md): common failure modes and fixes

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

agent-swarm-skill

Directory Structure

SKILL.md

Report

Notice