Codex Swarm

OpenAI Codex-native multi-agent swarm orchestration for parallel coding. Use when spawning multiple Codex CLI agents to work in parallel with git worktrees,...

Security Scan

The skill largely does what it claims (orchestrates Codex CLI agents), but its manifest underdeclares required tools/credentials and the scripts include automatic endorsement, auto-merge, force-push, and optional webhook notifications — behaviors that give it broad ability to modify and exfiltrate repository content without clear safeguards.

Purpose & Capability

The name/description (Codex multi-agent orchestration) matches the included scripts: spawning tmux sessions, worktrees, codex exec runs, reviews, merges and notifications. However the registry metadata claims no required binaries/env vars while SKILL.md and the scripts explicitly require bash 4+, tmux, git, gh, jq, and the codex CLI — an incoherence between declared requirements and actual needs.

Instruction Scope

Runtime instructions and scripts read/write local files (prompts, logs, /tmp worklogs), create and remove git worktrees/branches, run codex exec (which executes model-driven changes), and can auto-commit, auto-resolve conflicts, and push to origin/main. They also support sending messages to arbitrary webhook URLs or Telegram tokens if configured. spawn-batch auto-calls endorse-task (so the endorsement gate is effectively automatic), and notify-on-complete does force pushes. These actions go beyond passive orchestration and can modify remote repositories and transmit messages externally.

Install Mechanism

No install spec is provided (instruction-only with bundled scripts). That lowers the risk of arbitrary remote code downloads. The presence of multiple executable scripts means code will run on the host, but nothing is being fetched from unknown URLs during install.

Credentials

The manifest declares no required environment variables, but scripts read many configuration variables (SWARM_NOTIFY, SWARM_WEBHOOK_URL, SWARM_TELEGRAM_BOT_TOKEN, SWARM_TELEGRAM_CHAT_ID, SWARM_AUTO_MERGE, SWARM_ENDORSEMENT_COOLDOWN, SWARM_MAX_REVIEW_ROUNDS) via config/swarm.conf or env. The scripts implicitly rely on git/GH credentials already present on the machine to push/delete branches. Requiring or using webhook/telegram tokens and having the ability to push/force-push/delete remote branches is a high-privilege operation that is not called out in the metadata.

Persistence & Privilege

always:false (good), but autonomous invocation is allowed (normal). Combined with default behavior in scripts (automatic endorsement via spawn-batch, SWARM_AUTO_MERGE default=true, force-with-lease/force pushes, branch deletion in cleanup.sh when called with --all), the skill can autonomously modify remote repositories and remove branches. It also writes persistent logs and prompt files containing prompt contents, which may include sensitive data.

What to consider before installing

This skill appears to implement the advertised swarm orchestration, but it underdeclares its requirements and includes powerful actions (auto-commit, conflict auto-resolution via codex exec, force-push, branch deletion, and optional webhook/Telegram notifications). Before installing or running it: - Treat it as code that will run with your user credentials: test it in a disposable/forked repository (not your production repo or main branch). - Inspect or create config/swarm.conf yourself; do not set SWARM_WEBHOOK_URL or Telegram tokens until you trust the workflow. Webhooks will transmit the message text off-host. - Disable automatic merges by setting SWARM_AUTO_MERGE=false and review the integration-watcher logic. - Prevent automatic endorsement if you want manual gating: modify spawn-batch so it doesn't auto-run endorse-task, or require a different endorsement workflow. - Ensure your git/GH credentials are limited (use a machine/service account with minimal permissions) or remove push rights when testing. - Check logs and prompt files (SWARM_DIR/logs and /tmp worklogs) for sensitive content and delete them if necessary. If you want to proceed, update the skill metadata to list required binaries and the environment variables it uses, and consider hardening the scripts (explicit manual approval steps, remove force-push/delete actions, and avoid sending prompt contents to external endpoints).

Codex Swarm — Multi-Agent Orchestration

Parallel Codex agents: plan → endorse → spawn → monitor → review → integrate → ship.

Quick Start

# 1. Write task prompts
cat > /tmp/prompt-task1.md << 'EOF'
Implement feature X...
EOF

# 2. Create tasks JSON
cat > /tmp/tasks.json << 'EOF'
[
  {"id": "feat-x", "description": "/tmp/prompt-task1.md", "role": "builder"},
  {"id": "feat-y", "description": "/tmp/prompt-task2.md", "role": "builder"}
]
EOF

# 3. Spawn batch
bash scripts/spawn-batch.sh "/path/to/project" "batch-1" "Description" /tmp/tasks.json

Roles & Models

Role	Model	Reasoning	Use
architect	o3	high	Design, planning, complex decisions
builder	codex-mini	medium	Feature implementation (parallel)
reviewer	o3	medium	Auto-review via codex exec review
integrator	o3	high	Cross-branch merge + conflict resolution

Key Codex Features Used

• codex exec --full-auto — non-interactive sandboxed execution
• codex exec review — native code review (replaces custom reviewer)
• -c model=o3 — deep reasoning model for complex tasks
• -c model_reasoning_effort=high — maximum reasoning depth

Scripts

Script	Purpose
spawn-batch.sh	Spawn N parallel agents + integration watcher
spawn-agent.sh	Spawn single agent (manual worktree + tmux + codex exec)
endorse-task.sh	Endorse task before spawn
check-agents.sh	Show running agent status
cleanup.sh	Remove worktrees, branches, sessions
notify.sh	Webhook/Telegram notification
notify-on-complete.sh	Auto-watcher with native codex exec review
integration-watcher.sh	Auto-merge when batch completes

Setup

1. Copy scripts/ and config/ to your workspace
2. Configure config/swarm.conf (copy from .example)
3. Required: bash 4+, tmux, git, gh, jq, codex (Codex CLI)