⚠️ Repository Renamed
This project was previously named Conductor's Score (conductor-score).
It has been renamed to Code Conductor (code-conductor) as of July 23, 2025.
GitHub redirects all URLs, but please update any bookmarks or references.

Transform your development workflow in 60 seconds. From tweet discovery to AI agents shipping code—the GitHub-native coordination system that changes how you build.

"Stop juggling tasks. Start orchestrating agents."

• ⚡ Focus on architecture, let agents handle implementation - Spend time on what matters most
• 🎯 Zero config for 90% of projects - Auto-detects your stack and configures optimal roles
• 🔒 AI code reviews on every PR - Built-in CodeRabbit-style reviews catch bugs before merge
• 🤖 Smart agent roles - Generalist "dev" handles most tasks, specialists for complex work
• 📊 Native GitHub integration - Issues become tasks, Actions monitor health
• 🔄 Self-healing coordination - Automatic cleanup, heartbeat monitoring, stale work recovery

"From weekend side project to shipping product in weeks, not months."

Code Conductor automatically detects and configures for the most popular technology stacks:

• React/Next.js - Auto-configures frontend & UI roles
• Vue/Nuxt - Component-based development ready
• Angular - Enterprise app support
• Svelte/SvelteKit - Modern reactive apps

• Node.js (Express, NestJS) - Microservices ready
• Python (Django, Flask, FastAPI) - Web & ML support
• Go (Gin, Echo, Fiber) - High-performance services
• Java/Kotlin (Spring) - Enterprise backends
• PHP (Laravel, Symfony) - Rapid development
• .NET Core (ASP.NET) - Microsoft stack

• React Native - Cross-platform mobile
• Flutter - Native performance
• Tauri - Lightweight desktop apps
• Electron - Web-powered desktop

Based on your stack, we automatically add:

• 🤖 code-reviewer - AI reviews on every PR (always included)
• 🎨 frontend - UI/UX implementation
• 📱 mobile - Platform-specific features
• 🔧 devops - CI/CD & infrastructure
• 🔒 security - Vulnerability scanning
• 🧮 ml-engineer - ML model deployment
• 📊 data - ETL & analytics

One command. Instant AI coordination.

Prerequisites for all options: Git, Python 3.9-3.12, curl (for one-liner), and tar. Run from the root of an existing Git repository. If using pyenv, ensure your active Python version (e.g., via pyenv shell 3.12.x) has Poetry installed if you prefer it; otherwise, the script falls back to pip.

Run this in your existing project's root directory to download and install Code Conductor directly:

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

• This method avoids cloning the full Code Conductor repo and is ideal for integrating into existing projects without repository pollution.
• The script will prompt before overwriting any existing installation.
• Security best practice: Review the script at the raw URL before running.
• Pyenv users: If Poetry install fails, switch to the Python version that has Poetry installed (e.g., pyenv shell 3.10.13) and re-run.

# Clone the repository
git clone https://github.com/ryanmac/code-conductor.git
cd code-conductor

# Install with Poetry (auto-creates virtual environment)
poetry install
poetry run python setup.py

# Clone the repository
git clone https://github.com/ryanmac/code-conductor.git
cd code-conductor

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run setup
python setup.py

# From the repository directory:
./install.sh

# Or with custom setup options:
./install.sh --auto

That's it. Now create a GitHub Issue with conductor:task label, launch an agent via Conductor.build (macOS only as of 2024-07-22) or terminal workflow (all platforms), and watch it work.

1. Setup Phase: Use the universal installer (Option 1) or other setup methods to configure your project. The setup script detects your project type and configures roles.
2. Task Creation: Create tasks via GitHub Issues or directly in the state file
3. Agent Initialization: Agents use the universal bootstrap to claim work
4. Isolated Development: Each agent works in a git worktree to prevent conflicts
5. Automated Coordination: GitHub Actions manage health, cleanup, and task flow

The system uses a hybrid approach optimized for efficiency:

• Default Role: dev - A generalist that can handle any task without specific requirements
• Specialized Roles: Optional roles like devops, security for complex domains

This reduces the complexity of managing many agent types while maintaining quality for specialized work.

.conductor/
├── config.yaml           # Project configuration with auto-detected stack
├── workflow-state.json   # Central coordination state
├── roles/               # Role definitions
│   ├── dev.md          # Default generalist
│   ├── code-reviewer.md # AI-powered PR reviewer
│   ├── frontend.md     # UI/UX specialist
│   ├── mobile.md       # Mobile app developer
│   ├── devops.md       # CI/CD specialist
│   ├── security.md     # Security specialist
│   ├── ml-engineer.md  # ML/AI specialist
│   └── data.md         # Data engineer
├── scripts/            # Automation scripts
│   ├── bootstrap.sh    # Universal agent init
│   ├── task-claim.py   # Atomic task assignment
│   ├── code-reviewer.py # AI code review engine
│   └── health-check.py # System monitoring
└── examples/           # Stack-specific task templates
    ├── nextjs-webapp/
    ├── python-webapp/
    ├── mobile-app/
    └── ...

Run python setup.py to configure:

• Project name and documentation location
• Technology stack detection
• Role selection (hybrid model)
• Task management approach
• GitHub integration settings

Each role has a Markdown file in .conductor/roles/ defining:

• Responsibilities
• Task selection criteria
• Required skills
• Success metrics

Tasks include complete specifications:

{
  "id": "task_001",
  "title": "Implement authentication",
  "specs": "docs/auth-spec.md",
  "best_practices": ["Use JWT", "Implement refresh tokens"],
  "success_criteria": {
    "tests": "100% coverage",
    "security": "Pass security scan"
  },
  "required_skills": [],  // Empty = any dev can take it
  "estimated_effort": "medium"
}

Every pull request automatically gets AI-powered code reviews that:

• 🔒 Security scanning - Catches hardcoded secrets, SQL injection risks, unsafe operations
• 🐛 Bug detection - Identifies logic errors, null pointer risks, race conditions
• 💡 Improvement suggestions - Performance optimizations, better patterns, refactoring opportunities
• 🎨 Style consistency - Ensures coding standards across the team
• 🧪 Test coverage - Suggests missing tests and edge cases

1. Automatic trigger - Reviews start instantly on PR creation/update
2. Contextual analysis - Understands your codebase patterns
3. Actionable feedback - Clear, specific suggestions with examples
4. Zero configuration - Works out of the box with your existing GitHub workflow

# .github/workflows/code-review.yml (auto-created)
name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize, reopened]

Option A: Conductor Desktop App (macOS only)

export AGENT_ROLE=dev  # or devops, security, etc.
bash .conductor/scripts/bootstrap.sh
# Follow the printed instructions to open in Conductor app

Option B: Multiple Terminals (All Platforms)

bash .conductor/scripts/bootstrap.sh dev
cd worktrees/agent-dev-[task_id]
# Use tmux or screen for session management on Linux/Windows
# Start your Claude Code session in the worktree

📚 See complete usage guide →

1. Initialize: Load role definition and check dependencies
2. Claim Task: Atomically claim an available task
3. Create Worktree: Isolated git workspace for conflict-free work
4. Execute Task: Follow specifications and success criteria
5. Report Status: Update heartbeat and progress
6. Complete/Idle: Mark complete or report idle for cleanup

The system provides a single prompt that works for any agent:

You are a Claude Code agent in a Code Conductor coordinated project.
ROLE: {role}
PROJECT: {project_name}

1. Read your role definition: .conductor/roles/{role}.md
2. Check system state: .conductor/workflow-state.json
3. Claim a task: python .conductor/scripts/task-claim.py --role {role}
4. Work in your isolated worktree
5. Commit and push changes when complete

Note: Heartbeats are automatically managed by GitHub Actions.

Create issues with the conductor:task label to automatically convert them to tasks.

• Health Monitoring: Every 15 minutes
• Stale Cleanup: Removes abandoned work
• Task Scheduling: Processes dependencies
• Status Reports: Updates dashboard issue

# Check local status
python .conductor/scripts/health-check.py

# View GitHub dashboard
# Check issue with 'conductor:status' label

• Active agents and their tasks
• Available task queue depth
• Completion rate and velocity
• System health indicators

project_name: harmony-webapp
roles:
  default: dev
  specialized: [devops, ui-designer]
build_validation:
  - npm test -- --coverage
  - npm run lint
  - npm run build

project_name: symphony-extension
roles:
  default: dev
  specialized: [devops]
protected_files:
  - packages/extension/manifest.json

project_name: api-platform
roles:
  default: dev
  specialized: [devops, security]
quality_checks:
  - pytest --cov=services
  - bandit -r services/

project_name: desktop-app
roles:
  default: dev
  specialized: [devops, security, rust-dev]
matrix_builds: [ubuntu, macos, windows]

Don't see your stack? Contribute an example and help other developers!

No tasks available

• Check .conductor/workflow-state.json has tasks
• Verify no file conflicts blocking tasks
• Create new tasks via GitHub issues

Agent can't claim tasks

• Run python .conductor/scripts/dependency-check.py
• Ensure GitHub CLI is authenticated: gh auth status
• Check git repository is clean: git status

File conflicts

• System prevents these automatically
• If occurs, check worktree isolation
• Run cleanup: python .conductor/scripts/cleanup-stale.py

# Check dependencies
python .conductor/scripts/dependency-check.py

# View system state
cat .conductor/workflow-state.json | jq

# Force cleanup
python .conductor/scripts/cleanup-stale.py --timeout 0

# Validate configuration
python .conductor/scripts/validate-config.py

Disk Usage: Each agent creates a Git worktree (~50-200MB depending on project size)

• Cleanup: Run gtclean weekly to remove abandoned worktrees
• Monitor: Use gtw to list active worktrees
• Automatic: Stale worktrees (>7 days inactive) are auto-archived via GitHub Actions

Pro tip: Large projects should set worktree_retention_days: 3 in config.yaml

1. Task Design: Make tasks self-contained with clear specs
2. Role Selection: Start with dev-only, add specializations as needed
3. Regular Cleanup: Let automation handle stale work
4. Monitor Health: Check status issue regularly
5. Incremental Adoption: Start small, expand as comfortable

• Python 3.9-3.12
• Git
• GitHub CLI (optional, for issue integration)

# Clone and setup
git clone https://github.com/ryanmac/code-conductor.git
cd code-conductor

# Install with Poetry (recommended)
poetry install

# Or with pip
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Run tests
poetry run pytest tests/ -v
# or
python -m pytest tests/ -v

# Run linting
poetry run flake8 .conductor/scripts/ setup.py
poetry run black --check .conductor/scripts/ setup.py

The project uses GitHub Actions for continuous integration:

• Linting: flake8 and black formatting checks
• Testing: pytest on multiple Python versions (3.9, 3.10, 3.11, 3.12)
• Security: safety vulnerability scanning
• Platforms: Ubuntu and macOS

This is a template repository. To contribute:

1. Fork and improve
2. Test with your project type
3. Submit PRs with examples
4. Share your adaptations

• Follow PEP 8 style guidelines
• Add tests for new functionality
• Update documentation for changes
• Ensure CI passes before submitting PRs

MIT - See LICENSE file

• 🐛 Issue Tracker
• 💬 Discussions

• 🐛 Found a bug? Report it
• 💡 Have an idea? Start a discussion
• 🛠️ Want to contribute? See our guide
• 𝕏 Share your success Mention @ryanmac with #CodeConductor

Built for Conductor.build and Warp users who refuse to juggle tasks manually.

Transform your development workflow. One command. Infinite possibilities. 🎼