Skip to content

rekpero/claude-code-swarm

BranchesTags

Repository files navigation

SwarmOps

A 24/7 autonomous orchestrator that watches a GitHub repository for open issues, dispatches parallel Claude Code agents to implement fixes and features, creates PRs, handles CI review feedback in a loop, and iterates until all issues are resolved.

How It Works

Issue created (labeled "agent")
    │
    ▼
Write the plan directly in the issue body,
or use the built-in AI Issue Planner in the dashboard
    │
    ▼
Comment "@swarmops start" when ready
    │
    ▼
Orchestrator polls GitHub ──▶ Dispatches Claude Code agent
    │                              │
    │                              ▼
    │                         Agent reads issue body (the implementation plan),
    │                         implements changes in an isolated git worktree,
    │                         runs tests, pushes branch, creates PR
    │                              │
    │                              ▼
    │                         CI / bugbot reviews the PR diff,
    │                         posts comments on issues found
    │                              │
    │                              ▼
    │                         Orchestrator detects comments ──▶ Dispatches fix agent
    │                              │
    │                              ▼
    │                         Fix agent addresses every comment, pushes again
    │                              │
    │                              ▼
    │                         (loop until 0 comments or max retries hit)
    │
    ▼
Dashboard shows live progress at http://localhost:8420

Each issue must contain a full implementation plan in the body. Use the built-in AI Planner to generate one from a plain-language description, or write it manually. Agents read this as their spec — no guesswork needed.

Prerequisites

  • Python 3.10+
  • Node.js 20+ — for building the React dashboard
  • Claude Code CLI (claude) — authenticated via claude setup-token with a Max subscription
  • GitHub CLI (gh) — installed (cli.github.com)
  • Git 2.20+
  • A GitHub fine-grained PAT with permissions: Contents, Issues, Pull Requests, Metadata

Quick Start

# 1. Clone and install Python dependencies
git clone <this-repo> && cd claude-code-swarm
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 2. Build the React dashboard
./run.sh build-ui

# 3. Configure
cp .env.example .env
# Edit .env — at minimum set:
#   CLAUDE_CODE_OAUTH_TOKEN  (from: claude setup-token)
#   GH_TOKEN                 (GitHub fine-grained PAT)
#   ADMIN_USERNAME / ADMIN_PASSWORD  (dashboard login)
#   GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL

# 4. Install skills (optional but recommended)
./run.sh install-skills

# 5. Run
python -m orchestrator.main

The dashboard will be available at http://localhost:8420. Log in with the credentials you set in .env.

Note: On Ubuntu servers, sudo ./run.sh install handles Node.js installation, the UI build, and systemd service setup in one step — see Production Deployment.

Configuration

All settings live in .env (or as environment variables):

Variable Default Description
CLAUDE_CODE_OAUTH_TOKEN (required) From claude setup-token (Max plan)
GH_TOKEN (required) GitHub PAT for private repo access
ADMIN_USERNAME admin Dashboard login username
ADMIN_PASSWORD (required) Dashboard login password
GIT_AUTHOR_NAME (required) Git commit author name for agent commits
GIT_AUTHOR_EMAIL (required) Git commit author email for agent commits
MAX_CONCURRENT_AGENTS 3 Max parallel agents
AGENT_MAX_TURNS_IMPLEMENT 30 Max Claude turns for new issues
AGENT_MAX_TURNS_FIX 20 Max Claude turns for fixing review comments
AGENT_TIMEOUT_SECONDS 1800 Hard timeout per agent (30 min)
POLL_INTERVAL_SECONDS 300 How often to check for new issues (5 min)
PR_POLL_INTERVAL_SECONDS 120 How often to check PRs for comments (2 min)
ISSUE_LABEL agent Only issues with this label are picked up
TRIGGER_MENTION @swarmops Comment trigger to start an agent (set empty to auto-start on label)
MAX_ISSUE_RETRIES 3 Retry limit per issue before escalation
MAX_PR_FIX_RETRIES 5 Max review-fix cycles per PR
SKILLS_ENABLED true Enable Claude Code skills for agents
DASHBOARD_PORT 8420 Dashboard web UI port

Dashboard

The React dashboard at http://localhost:8420 is the control centre for SwarmOps.

Live Progress

  • Metrics bar — resolved, pending, in-progress, open PRs, needs-human, avg turns per issue
  • Active agents — live log stream with tool calls, issue/PR assignment, turn count, elapsed time
  • Issue queue — all tracked issues with status, retry count, and assigned agent
  • PR tracker — open PRs with review iteration count and comment totals

The dashboard polls the API every few seconds and updates in real time.

AI Issue Planner

Generate production-ready implementation plans without leaving the dashboard:

  1. Click + Plan Issue in the header
  2. Describe the feature or bug in plain language
  3. SwarmOps runs a planning agent that reads your codebase and produces a detailed, file-by-file implementation plan
  4. Review and edit the plan inline
  5. Click Create GitHub Issue — the issue is created with the plan as the body and the agent label applied automatically
  6. Comment @swarmops start on the issue to dispatch the agent

Previous planning sessions are saved in a sidebar so you can resume, reference, or re-use them at any time.

What a generated plan includes:

  • File-by-file breakdown of changes and rationale
  • Function signatures, data structures, and API contracts to implement
  • Test cases and validation steps
  • Edge cases and error-handling requirements
  • References to existing code patterns in the repo

Environment File Manager

Manage .env files for your target repo directly from the dashboard, without needing shell access:

  • Upload and edit multiple env files in a tabbed editor
  • Changes sync automatically to disk with modification-time tracking (no stale-read issues)
  • Delete tabs to remove env files from disk
  • Monorepo-aware: detects and manages sub-package env files independently

Authentication

The dashboard requires login. Credentials are set via ADMIN_USERNAME and ADMIN_PASSWORD in .env. Sessions persist for 30 days via a secure cookie.

Skills

Agents can use Claude Code skills — reusable capabilities that give agents domain expertise for frontend design, testing, security, API design, and more.

Installing Skills

# Install all skills from default repos (anthropics/skills + vercel-labs/agent-skills)
./run.sh install-skills

# Install from a specific repo
./run.sh install-skills --repo anthropics/skills

# Install a single skill
./run.sh install-skills --skill frontend-design

# Install globally instead of into target repo
./run.sh install-skills --global

# List available skills in default repos
./run.sh install-skills --list

# Show currently installed skills
./run.sh list-skills

# Remove all installed skills
./run.sh uninstall-skills

By default, skills are installed into the target repo's .claude/skills/ directory using --copy mode (not symlinks), so they are available in every agent worktree. You can also install globally to ~/.claude/skills/ with --global.

How Skills Work with Agents

When SKILLS_ENABLED=true (the default) and skills are installed:

  1. The orchestrator discovers installed skills at startup by scanning .claude/skills/ in the target repo and ~/.claude/skills/ globally.
  2. Agent prompts automatically include a hint listing available skills.
  3. The Skill tool is added to each agent's allowed tools.
  4. If an issue body or PR review comment references a skill (e.g. "use the frontend-design skill"), the agent will invoke it.
  5. Agents can also use skills proactively when the task matches a skill's domain.

Default Skill Repos

Repo Notable Skills
anthropics/skills frontend-design, pdf, docx, xlsx, pptx, mcp-builder, webapp-testing, skill-creator
vercel-labs/agent-skills web-design-guidelines, vercel-react-best-practices, vercel-composition-patterns

Browse all available skills at skills.sh. You can install from any GitHub repo that follows the skills format:

./run.sh install-skills --repo remotion-dev/skills
./run.sh install-skills --repo supabase/agent-skills
./run.sh install-skills --repo microsoft/github-copilot-for-azure

Set SKILLS_ENABLED=false in .env to disable skill support entirely.

Production Deployment (Ubuntu)

The run.sh script manages the orchestrator as a systemd service. The install command handles everything — Node.js, UI build, Python deps, and service registration:

# Install as a systemd service (auto-start on boot, auto-restart on crash)
sudo ./run.sh install

# Install agent skills
./run.sh install-skills

# Day-to-day management
./run.sh status      # Check if running
./run.sh logs        # Tail live logs (journalctl)
./run.sh restart     # After config changes, it also build the UI everytime you restart
./run.sh stop        # Graceful shutdown

# Rebuild the dashboard UI after frontend changes
./run.sh build-ui

# Remove the service
sudo ./run.sh uninstall

Without systemd (local dev), start/stop fall back to nohup with a PID file.

Target Repository Setup

1. AGENT.md at the repo root — coding guidelines for agents (style, conventions, test commands).

2. CLAUDE.md at the repo root — auto-loaded by Claude Code on every session:

# CLAUDE.md

## CRITICAL: Read AGENT.md First
Before making ANY changes, read and follow all guidelines in @AGENT.md.

## Workflow Rules for Automated Agents
1. ALWAYS read AGENT.md before starting work.
2. ALWAYS run tests before creating a PR or pushing fixes.
3. NEVER modify files unrelated to your assigned issue.
4. NEVER push directly to main. Always use feature branches.
5. Reference the issue number in every commit message.

3. Issues must be labeled with the configured label (default: agent) and contain a detailed implementation plan in the body. Use the AI Planner in the dashboard to generate plans automatically, or write them manually. When ready, comment @swarmops start on the issue to trigger the agent. Issues without this comment are ignored until activated.

4. CI reviewer — optionally set up a PR review action (e.g. rekpero/claude-bugbot-github-action) to post review comments that the orchestrator will detect and dispatch fix agents for.

Architecture

claude-code-swarm/              ← This project (orchestrator)
├── orchestrator/
│   ├── main.py                 # Entry point — starts all subsystems
│   ├── config.py               # Configuration + environment validation
│   ├── db.py                   # SQLite (issues, agents, events, PR reviews, planner sessions)
│   ├── issue_poller.py         # Polls GitHub for labeled issues
│   ├── agent_pool.py           # Manages claude -p subprocess lifecycle
│   ├── pr_monitor.py           # Watches PRs for review comments / CI status
│   ├── worktree.py             # Git worktree create/cleanup
│   ├── stream_parser.py        # Parses claude stream-json output
│   ├── prompts.py              # Agent prompt templates (with skill discovery)
│   ├── planner.py              # AI planning agent — codebase analysis + plan generation
│   ├── dashboard.py            # FastAPI server + REST API
│   └── static/                 # Built React SPA (output of ./run.sh build-ui)
├── frontend/                   # React 18 + Vite dashboard source
│   ├── src/
│   │   ├── components/         # UI components (Header, Planner, AgentLogs, EnvManager…)
│   │   ├── hooks/              # Data fetching hooks (React Query)
│   │   └── context/            # Auth + workspace context
│   └── public/                 # Static assets (logo, favicon)
├── run.sh                      # Service management, build, skill installation
└── .env                        # Tokens and config (copy from .env.example)

~/my-project/                   ← Target repo (separate directory)
├── .claude/skills/             ← Installed skills (via ./run.sh install-skills)
│   ├── frontend-design/
│   └── ...
~/my-project-worktrees/         ← Auto-created isolated worktrees for each agent

Agents run in isolated git worktrees as siblings of the target repo. The orchestrator never touches the target repo's working directory — each agent gets its own copy.

API Endpoints

Endpoint Description
GET /api/metrics Aggregate stats
GET /api/agents All agents with status
GET /api/agents/{id}/logs?since=N Stream-json events for an agent
GET /api/issues All tracked issues
GET /api/prs PR review loop status
GET /api/workspaces All workspaces
GET /api/workspaces/{workspace_id}/planning-sessions Planning sessions for a workspace
POST /api/planning Start a new planning session
GET /api/planning/{id} Get session status, messages, and plan
POST /api/planning/{id}/messages Refine the plan (continue conversation)
POST /api/planning/{id}/create-issue Create a GitHub issue from the plan
POST /api/planning/{id}/cancel Cancel in-progress generation
DELETE /api/planning/{id} Delete a planning session

Agent Planning API

External agents (other AI systems, CI bots, automations) can drive the full plan → issue workflow over HTTP using a static API key — no browser login needed.

Set API_KEYS=your-key in .env, then pass it as Authorization: Bearer <key> on any request.

Full API reference → docs/agent-planning-api.md

Covers: authentication setup, all planning endpoints, exact request/response shapes, session status values, where the plan lives in the response, and a complete agent workflow example.

Safety Guardrails

  • Concurrency cap — max 3 parallel agents (configurable)
  • Turn limits — 30 turns for implementation, 20 for fixes
  • Hard timeout — agents killed after 30 minutes
  • Retry limits — 3 attempts per issue, 5 review-fix cycles per PR
  • Escalation — exhausted issues labeled needs-human on GitHub
  • Crash recovery — stale agents from previous runs are cleaned up on restart
  • Error backoff — repeated poll failures trigger exponential backoff
  • Graceful shutdown — SIGTERM/SIGINT waits for running agents, cleans up worktrees

About

A 24/7 claude code swarm orchestrator that watches a GitHub repository for open issues and implement them

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages