Skip to content
/
Tier A A6 Multi-agent orchestrator

Code Conductor (ryanmac)

code-conductor · ryanmac/code-conductor · ★ 101 · last commit 2026-03-30

Decentralized swarm orchestration for parallel Claude Code agents using GitHub Issues as the atomic task queue and git worktrees for zero-conflict isolation.

Best whenGitHub's issue-assignment API is sufficient for multi-agent coordination — no custom lock files, databases, or central coordinators needed.
Skip ifSequential single-agent development (wastes backlog velocity), Custom task locking mechanisms (GitHub atomic API is sufficient)
vs seeds
claude-flowuses an MCP toolserver with hive-mind consensus; code-conductor u…
Primitive shape 10 total
Subagents 10
00

Summary

Code Conductor (ryanmac) — Summary

Code Conductor by Ryan Mac is a Python-based GitHub-native multi-agent orchestration system that enables multiple Claude Code agents to work on parallel tasks simultaneously without conflicts, using GitHub Issues as the task queue and git worktrees for isolation. Unlike the CDD conductor variants (which prescribe a development methodology), Code Conductor is a coordination infrastructure: it provides a conductor bash script, 15+ Python scripts, 10 role markdown files, GitHub Actions workflows, and a .conductor/ configuration system that enables autonomous agent task claiming, isolated worktree execution, heartbeat monitoring, and stale work cleanup. The key innovation is using GitHub's atomic issue-assignment API as a task coordination primitive — no central coordinator, no race conditions, no custom locking mechanism. At 101 stars with MIT license, it is more mature than the CDD variants (active development until 2026-03-30), has a proper uninstaller, and targets teams wanting to "ship 10x faster by running multiple Claude Code sub-agents in parallel." Compared to Conductor.build (which provides similar parallel-worktree functionality via a macOS UI), Code Conductor is the open-source CLI alternative that works across platforms and requires no subscription.

01

Overview

Code Conductor (ryanmac) — Overview

Origin

  • Author: Ryan Mac (@ryanmac on X)
  • Repo: https://github.com/ryanmac/code-conductor
  • License: MIT
  • Stars: 101 | Forks: 9 | Contributors: unknown | Last commit: 2026-03-30
  • Description: "Ship 10x faster by running multiple Claude Code sub agents in parallel. GitHub-native orchestration for AI coding agents—no conflicts, no complexity, just pure parallelized productivity."

Philosophy

"Transform your workflow: Hours, not weeks — Multiple agents tackle your backlog in parallel"

"The secret: Each agent works in its own git worktree—like having multiple copies of your repo. Agent A refactors authentication while Agent B adds dark mode. Zero conflicts."

Core principles:

  1. GitHub-native: GitHub Issues with conductor:task label are the task queue
  2. Atomic coordination: GitHub's issue-assignment API ensures atomic task claiming (no custom locking)
  3. Worktree isolation: each agent gets worktrees/agent-{role}-{task_id} — zero file conflicts
  4. Self-healing: GitHub Actions monitor heartbeats, clean stale work every 15 minutes
  5. Role system: 10 specialized agent roles (dev, frontend, security, devops, mobile, ml-engineer, data, ui-designer, code-reviewer, + _core)
  6. Auto-detect stack: setup wizard detects React, Python, Go, etc. and configures roles automatically

Quick start (verbatim)

bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh)

Then:

gh issue create --label "conductor:task" --title "Add dark mode toggle"
./conductor start frontend
02

Architecture

Code Conductor (ryanmac) — Architecture

Distribution

  • Type: bash script bundle + Python scripts + GitHub Actions
  • Install:
    bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh)
# OR non-interactive:
curl ... | bash -s -- --auto --create-pr --auto-merge
  • Required runtime: Python, GitHub CLI (gh), Claude Code, bash
  • Language: Python (scripts), Bash (conductor wrapper + init)

Directory structure

code-conductor/
├── conductor-init.sh           # Main install script (stack auto-detection + setup)
├── setup.py                    # Python setup wizard
├── uninstall.py                # Safe uninstaller
├── conductor                   # Universal agent command bash script
├── CLAUDE.md                   # Claude Code context file
├── CLAUDE_CODE_PROMPT.md       # Power user prompts
├── .conductor/                 # Config directory
│   ├── .initialized            # Install flag
│   ├── config.yaml             # Project config
│   ├── contracts.md            # Agent behavioral contracts
│   ├── roles/                  # 10 agent role definitions
│   │   ├── _core.md            # Core agentic charter (all roles inherit)
│   │   ├── CLAUDE.md           # Role-specific Claude context
│   │   ├── dev.md              # Generalist development role
│   │   ├── frontend.md         # Frontend specialist
│   │   ├── security.md         # Security specialist
│   │   ├── devops.md           # DevOps specialist
│   │   ├── mobile.md           # Mobile specialist
│   │   ├── ml-engineer.md      # ML specialist
│   │   ├── data.md             # Data specialist
│   │   ├── ui-designer.md      # UI/Design specialist
│   │   └── code-reviewer.md    # Code review (always included)
│   ├── scripts/                # 15+ Python automation scripts
│   │   ├── conductor            # Main bash interface
│   │   ├── task-claim.py       # Atomic task claiming via GitHub Issues
│   │   ├── health-check.py     # Agent heartbeat monitoring
│   │   ├── cleanup-stale.py    # Stale work removal
│   │   ├── cleanup-worktrees.py # Worktree cleanup
│   │   ├── create-review-task.py
│   │   ├── dependency-check.py
│   │   ├── generate-summary.py
│   │   ├── generate-tasks-from-map.py
│   │   ├── update-status.py
│   │   ├── validate-config.py
│   │   ├── archive-completed.py
│   │   ├── check-duplicate-issues.py
│   │   ├── issue-to-task.py
│   │   └── test-workflow-fix.sh
│   └── templates/              # Template files
├── docs/                       # Documentation
│   ├── ARCHITECTURE.md
│   ├── INSTALLATION.md
│   ├── STACK_SUPPORT.md
│   ├── AI_CODE_REVIEW.md
│   └── FAQ.md
└── tests/                      # Test suite

Target AI tools

  • Primary: Claude Code
  • Mentioned: Warp, other AI coding agents
  • Coordination is tool-agnostic (GitHub Issues + worktrees); the role files are Claude-specific
03

Components

Code Conductor (ryanmac) — Components

CLI interface

Command Purpose
./conductor start [role] Start an agent with given role in the next available task's worktree
./conductor status Show active agents, claimed tasks, worktrees

Agent roles (10 markdown files)

Role Purpose
_core.md Core Agentic Charter — inherited by all roles; defines ReAct loop, TDD methodology, delegation rules
dev.md Generalist (80% of tasks); TDD + ReAct pattern; handles most common development tasks
frontend.md Frontend specialist (React/Vue/etc.)
security.md Security audit and fix specialist
devops.md CI/CD, Docker, k8s
mobile.md Mobile platform features
ml-engineer.md ML model integration, data pipelines
data.md Database optimization, complex queries
ui-designer.md Complex UI/animations, pixel-perfect design
code-reviewer.md Always included; AI-powered PR reviews

Python scripts (15+)

Script Purpose
task-claim.py Atomic task claiming via GitHub Issues API
health-check.py Monitor agent heartbeats (every 10 min)
cleanup-stale.py Remove abandoned work (idle_timeout: 30 min)
cleanup-worktrees.py Remove old worktrees
create-review-task.py Auto-create code review tasks
dependency-check.py Check required dependencies
generate-summary.py Generate project status summary
generate-tasks-from-map.py Convert documentation map to tasks
update-status.py Update GitHub Issue status
validate-config.py Validate .conductor/config.yaml
archive-completed.py Archive finished tasks
check-duplicate-issues.py Detect duplicate GitHub Issues
issue-to-task.py Convert GitHub Issues to conductor tasks

GitHub Actions workflows

  • Health check every 15 minutes
  • AI code reviews on all PRs (using repo's built-in auth — no token required)
  • Language-agnostic (no Python CI added to non-Python projects)

Config (.conductor/config.yaml)

version: "1.0.0"
task_management: "hybrid"  # GitHub Issues + worktrees
conflict_prevention:
  use_worktrees: true
  file_locking: true
github:
  use_issues: true
  use_actions: true
agent_settings:
  heartbeat_interval: 600   # 10 minutes
  idle_timeout: 1800        # 30 minutes
  max_concurrent: 20

Contracts

.conductor/contracts.md — behavioral contracts for agents (what they must and must not do).

05

Prompts

Code Conductor (ryanmac) — Prompts

Excerpt 1: .conductor/roles/dev.md — ReAct + TDD + delegation heuristics

# Development Agent Role

## Core Principles
*Follow the [Core Agentic Charter](./_core.md) for standard workflow patterns.*

## Responsibilities
- **Feature Development**: Implement new features using TDD approach
- **Delegation Heuristics**: escalate specialized tasks

## Delegation Heuristics

| Condition | Escalate To | Example |
|-----------|-------------|---------|
| Auth, crypto, secrets, permissions | `@security` | JWT implementation, OAuth flow |
| CI/CD, Dockerfile, k8s manifests | `@devops` | GitHub Actions, deployment configs |
| Complex UI animations, pixel-perfect | `@ui-designer` | Figma implementation, CSS animations |
| Mobile platform-specific features | `@mobile` | Push notifications, biometrics |
| ML model integration, data pipelines | `@ml-engineer` or `@data` | TensorFlow serving, ETL jobs |

## Working Methodology (TDD + ReAct)

### 1. Context Loading
```bash
# Start every task with context
if [ -f ".conductor/documentation-map.yaml" ]; then
    cat .conductor/documentation-map.yaml | head -50
fi
gh pr checks       # Current CI status
git log --oneline -10  # Recent changes
cat .conductor/workflow-state.json | jq '.active_work'

2. Test-First Development

...


**Technique**: Role as a behavioral specification with delegation heuristics table. Context-loading protocol using bash commands. ReAct pattern (Reasoning and Acting) with explicit steps. TDD enforcement via role instruction. Inherits from `_core.md` — role hierarchy via document inclusion.

---

## Excerpt 2: `CLAUDE.md` — Documentation map protocol

```markdown
## Documentation Map

**CRITICAL**: When starting work on any task, check if `.conductor/documentation-map.yaml` exists. This file contains:
- Comprehensive project analysis and structure
- Technology stack details and dependencies
- List of completed vs. pending features
- Implementation status and critical paths
- Architectural decisions and constraints

If this file exists, load it to understand the project context before beginning work.

Technique: Gate-on-file-existence pattern — documentation map drives all agent behavior if present. Critical annotations (**CRITICAL**) for high-priority instructions. Explicit context-loading priority order.

Prompting techniques observed

  1. Role hierarchy — _core.md defines base behavior; role files extend it via *Follow the Core Agentic Charter*
  2. Delegation heuristics table — structured table specifying when to escalate to which specialized role
  3. Bash-first context loading — agents start by running specific bash commands to load CI status, git log, and workflow state
  4. ReAct pattern explicit — Reasoning and Acting (think → act → observe) named and described in role files
  5. Documentation map gate — if .conductor/documentation-map.yaml exists, load it first; entire agent behavior adapts to project
  6. CRITICAL annotations — used for must-follow instructions (not just suggestions)
09

Uniqueness

Code Conductor (ryanmac) — Uniqueness

differs_from_seeds

No seed matches this architecture. The closest is claude-flow (multi-agent orchestration), but claude-flow is an MCP-anchored hive-mind with SQLite state and consensus protocols. Code Conductor uses GitHub's atomic issue-assignment API as its coordination primitive — a completely different approach requiring no custom infrastructure. Among seeds, superpowers is the only other framework that heavily uses git worktrees, but for individual feature isolation rather than parallel agent coordination. Code Conductor is the only framework in this batch and the seed corpus that achieves multi-agent parallelism without any central coordinator or lock mechanism — pure decentralized swarm coordination via GitHub primitives.

What makes Code Conductor unique

  1. GitHub Issues as atomic task queue — no custom lock file, no database coordinator; GitHub's assignment API is the coordination primitive
  2. Swarm orchestration — true peer-to-peer decentralized; up to 20 concurrent autonomous agents with no supervisor
  3. Heartbeat + auto-cleanup — agents report health; stale work (>30 min idle) auto-cleaned by GitHub Actions every 15 minutes
  4. Stack auto-detection at install — conductor-init.sh detects React/Python/Go/etc. and configures roles appropriately
  5. Safe uninstaller — uninstall.py with --dry-run flag; preserves user files and other workflows
  6. Role hierarchy with _core.md — base agentic charter inherited by all roles; consistent behavior floor
  7. Delegation heuristics table — structured table in dev.md specifying when to escalate to specialized roles

Observable failure modes

  1. GitHub-only: requires GitHub repo + GitHub CLI; doesn't work with GitLab, Bitbucket, or local repos
  2. AI review quality: auto-PR reviews via GitHub Actions — quality depends on model configuration
  3. Heartbeat reliability: 30-minute stale timeout may be too aggressive for long-running tasks
  4. No methodology enforcement: agents work on whatever GitHub Issues say; no CDD/TDD enforcement beyond role instructions
  5. 101 stars: relatively low adoption; maintenance uncertain beyond 2026-03

Positioning

Code Conductor is the open-source CLI answer to Conductor.build: same worktree isolation, same parallel agent model, but GitHub-hosted task management instead of a macOS UI. It targets developer teams who already use GitHub Issues for project management and want to add parallel AI agents without purchasing additional tooling.

04

Workflow

Code Conductor (ryanmac) — Workflow

Setup (one-time)

bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh)

The init script:

  1. Auto-detects technology stack (React, Python, Go, etc.)
  2. Creates .conductor/ directory with config.yaml
  3. Sets up agent roles for detected stack
  4. Creates GitHub Actions workflows
  5. Creates initial GitHub Labels (conductor:task, conductor:claimed, etc.)

Task creation (ongoing)

gh issue create --label "conductor:task" --title "Add dark mode toggle"

Any GitHub Issue with conductor:task label becomes available for agents to claim.

Agent launch

./conductor start [role]   # defaults to "dev" role
./conductor start frontend  # specialized role
./conductor start security

Per-agent execution loop

1. Agent reads .conductor/roles/<role>.md for behavior guidelines
2. Agent calls task-claim.py → atomically claims next available GitHub Issue
3. Agent creates worktree: worktrees/agent-{role}-{task_id}
4. Agent reads .conductor/documentation-map.yaml if exists (project context)
5. Agent implements task using ReAct pattern + TDD
6. Agent opens PR with changes
7. Agent moves to next available task
8. Heartbeat updates every 10 minutes

Coordination

  • Task claiming: atomic via GitHub issue assignment (no race conditions)
  • Heartbeat: agents update timestamps every 10 min; stale after 30 min
  • Cleanup: GitHub Actions clean stale work every 15 minutes
  • Status dashboard: /conductor:status GitHub Issue updated automatically

Approval gates

  1. Code review: GitHub Actions + AI code review on all PRs
  2. PR approval: standard GitHub PR approval before merge
  3. Auto-merge option: --auto-merge flag in init enables automatic merging of approved PRs

Uninstall

python uninstall.py              # interactive
python uninstall.py --force      # skip confirmation
python uninstall.py --dry-run    # preview what would be removed
06

Memory Context

Code Conductor (ryanmac) — Memory & Context

Project context via documentation map

The key memory mechanism is .conductor/documentation-map.yaml:

.conductor/documentation-map.yaml   # Written by [INIT] discovery task
                                     # Contains: project analysis, tech stack,
                                     # completed vs. pending features,
                                     # architectural decisions

This is optionally generated by a special [INIT] discovery task and loaded at the start of every agent session. It provides rich cross-session project context without requiring agents to re-analyze the codebase.

Per-agent state

.conductor/workflow-state.json   # Active work tracking per agent

Agents read workflow-state.json to understand what other agents are currently working on (coordination awareness).

GitHub Issues as persistent task state

GitHub Issues with conductor:task label serve as the persistent task queue:

  • Issue number = task ID
  • Issue assignment = claimed by agent
  • Issue labels = status (conductor:in-progress, conductor:completed)
  • This state is externally visible, shareable, and GitHub-native

Git worktrees as isolation

Each agent's work lives in worktrees/agent-{role}-{task_id} — a separate filesystem tree. State is isolated until PR merge.

Cross-session handoff

Yes — GitHub Issues persist between sessions. New agents can pick up abandoned tasks after stale cleanup.

Memory persistence scope

  • Project-scoped (.conductor/ in repo) + GitHub-hosted (Issues)

CLAUDE.md context injection

CLAUDE.md in the root provides project-level Claude Code context. .conductor/roles/CLAUDE.md provides role-specific context. Both are read at session start.

07

Orchestration

Code Conductor (ryanmac) — Orchestration

Multi-agent

Yes — the primary feature. max_concurrent: 20 agents supported per config.

Orchestration pattern

Swarm (peer-to-peer, decentralized). Unlike hierarchical patterns (lackeyjb, rbarcante), there is no orchestrator agent. Each agent independently:

  1. Claims a task from the GitHub Issues queue
  2. Creates its own worktree
  3. Implements the task
  4. Opens a PR
  5. Claims the next task

No agent coordinates another. GitHub's atomic issue API prevents conflicts without a coordinator.

Isolation mechanism

git-worktree — strongest isolation in this batch (alongside Conductor.build). Each agent gets worktrees/agent-{role}-{task_id} — a complete separate filesystem view of the repo.

Multi-model

No — all agents use Claude Code (the user's authenticated instance). No per-role model assignment.

Execution mode

Continuous — agents run until all conductor:task issues are claimed and completed. Each agent loops: claim → implement → PR → claim next.

Heartbeat / health system

  • Agents update heartbeat timestamps every 10 minutes
  • GitHub Actions runs health-check.py every 15 minutes
  • Stale agents (idle >30 min) auto-cleaned by cleanup-stale.py
  • This is the closest thing to a "daemon" in this batch

Role specialization

The dev role is generalist; specialized roles (security, devops, frontend, etc.) are invoked by ./conductor start <role>. Delegation is by the user at task creation, not by a supervisor agent.

Coordination primitive

GitHub Issues API: gh issue assign <number> --assignee @me is atomic. No custom lock files, no database, no central coordinator needed.

Max concurrent

Config: max_concurrent: 20. Practical limit is GitHub API rate limits and available machine resources.

08

Ui Cli Surface

Code Conductor (ryanmac) — UI & CLI Surface

CLI interface

The conductor bash script is the primary interface:

./conductor start [role]    # Launch an agent
./conductor status          # Show active agents

Not installed globally — local to each project directory.

GitHub as the UI

GitHub provides most observability:

  • Issues list: task queue (filtered by conductor:task label)
  • PR list: completed work awaiting review
  • GitHub Actions: automated health checks and AI code reviews
  • Status issue: auto-updated /conductor:status GitHub Issue as a dashboard

GitHub Projects

Optionally integrated with GitHub Projects for kanban-style tracking.

Web interface

None — no local web dashboard. GitHub provides the web UI.

Observability features

  • ./conductor status — terminal status of active agents
  • GitHub Issues with conductor labels — persistent task queue visibility
  • GitHub Actions logs — health check and cleanup run history
  • Auto-generated status issue — updated by update-status.py

Install/uninstall UX

# One-line install
bash <(curl -fsSL https://raw.githubusercontent.com/ryanmac/code-conductor/main/conductor-init.sh)

# Interactive uninstall with safety preview
python uninstall.py --dry-run   # Preview what would be removed
python uninstall.py             # Interactive confirmation
python uninstall.py --force     # Skip confirmation

The uninstaller preserves user's existing GitHub workflows, code, and data.

Stack detection (install time)

The init script auto-detects: React, Vue, Python, Go, Java, etc. — and configures agent roles accordingly (e.g., no Python CI added to a Go project).

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k
A6 Multi-agent orchestrator

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k
A6 Multi-agent orchestrator

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k
A6 Multi-agent orchestrator

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k
A6 Multi-agent orchestrator

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k
A6 Multi-agent orchestrator

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k
A6 Multi-agent orchestrator

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…