๐ญ Conductor
Orchestrating Claude Code sessions with elegance and intelligence
Conductor is a sophisticated Terminal User Interface (TUI) application that orchestrates automated task execution through Claude Code. It transforms repetitive AI-assisted development into a beautiful, efficient, and intelligent workflow.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โญโโฎ โญโฎ โญโฎ โญโฎ โ
โ โฑ โฐโโฎโญโโฎโโฐโฎโญโฏโโญโฎ โญโฏโโญโโฎโญโโฎโญโโฎ โ
โ โ โโ โโ โฐโฏ โโโฐโโฏ โโ โฐโฏ โฐโโฏโ โ
โ โฐโโโโโโฏโฐโโฏโฐโโโโโฏโฐโโโโโฏโฐโโโโโโโโฏ โ
โ O R C H E S T R A T O R โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โจ Features
๐ Automated Task Orchestration
- Batch Processing: Queue multiple Claude Code tasks for sequential execution
- YAML Configuration: Define tasks with structured, version-controlled files
- Smart Scheduling: Dependencies, priorities, and intelligent ordering
๐จ Beautiful Terminal Experience
- Modern TUI: Built with Textual for a reactive, beautiful interface
- Multiple Themes: Cyberpunk, minimal, and custom themes
- Live Visualization: Real-time progress, metrics, and session monitoring
- ASCII Browser Preview: See what's happening without leaving the terminal
๐ค Intelligent Automation
- Exponential Backoff: Smart retry logic with configurable parameters
- Jitter Algorithm: Avoid thundering herd with randomized delays
- HITL Integration: Human-in-the-loop for teaching element discovery
- Session Persistence: Resume interrupted work seamlessly
๐ Security First
- Manual Authentication: You control the login process
- No Credential Storage: Your secrets stay yours
- MCP Protocol: Secure communication with browser
๐ธ Screenshots
Main Interface
โโ Conductor v1.0.0 โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ [Theme: Cyberpunk] โโ
โโโ Task Queue โโโโโโโฌโ Current Execution โโโโโโฌโ Metrics โโโโโโโโโโโโโโ
โโ โถ AUTH-001 [Add.. ]โ Task: AUTH-001 โ Success: 42/45 โโ
โโ โท DOCS-002 [Doc.. ]โ Status: Running โ Failed: 3 โโ
โโ โท TEST-003 [Ref.. ]โ Progress: โโโโโโ 67% โ Avg Time: 3m 24s โโ
โโ โ FEAT-004 [New.. ]โ Elapsed: 02:15 โ Total: 2h 31m โโ
โโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโ
โโโ Browser Preview โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โโ ๐ claude.ai/code/session_011CV3PaU84XPmkgM5ssTJm3 โโ
โโ Branch: claude/auth-tests-011CV3PaU84 โโ
โโ [ASCII art preview of current browser state] โโ
โโ Actions: [P]eek [C]reate PR [S]kip [R]etry [A]bort โโ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ [1-9] Select [โโ] Navigate [Enter] Details [Q] Quit [?] Help โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
๐ Quick Start
Prerequisites
- Python 3.11 or higher
- pip package manager
- Modern terminal with Unicode support
Installation
# Clone the repository
git clone https://github.com/karolswdev/Conductor.git
cd Conductor
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -e ".[dev]"
# Run tests to verify installation
pytest
Basic Usage
Initialize Conductor
conductor init
This launches an interactive configuration wizard.
Verify your setup (optional but recommended)
conductor doctor
This runs diagnostic checks to verify:
- MCP server connectivity
- Browser launch capability
- Navigation works properly
- You can see the browser window
Create your task file (tasks.yaml):
tasks:
- id: "TEST-001"
name: "Add Unit Tests"
prompt: "Create comprehensive unit tests for the auth module"
expected_deliverable: "test_auth.py with >90% coverage"
repository: "karolswdev/my-project"
- id: "DOC-001"
name: "API Documentation"
prompt: "Document all REST endpoints in OpenAPI format"
expected_deliverable: "openapi.yaml with all endpoints"
dependencies: ["TEST-001"]
Run Conductor
conductor run tasks.yaml --theme cyberpunk
Authenticate: Browser opens โ Log into Claude Code โ Press Enter in terminal
Watch the magic happen! ๐ญ
๐ Documentation
Task Definition Schema
Tasks are defined in YAML with the following structure:
tasks:
- id: string # Unique identifier
name: string # Short display name (max 20 chars)
prompt: string # Full prompt for Claude
expected_deliverable: string # What you expect as output
priority: high|medium|low # Task priority (optional)
timeout: integer # Seconds before timeout (optional)
retry_policy: # Optional retry configuration
max_attempts: integer
backoff_factor: float
dependencies: [string] # List of task IDs (optional)
repository: string # Target repository (optional)
Command Line Interface
# Initialize configuration
conductor init
# Run diagnostics (verify everything works)
conductor doctor [options]
# Options:
--headless # Run in headless mode (skips visibility check)
--debug # Enable debug logging
# Run tasks
conductor run <task-file> [options]
# Options:
--theme <name> # Select theme (default, cyberpunk, minimal)
--repo <name> # Override default repository
--dry-run # Simulate without executing
--resume <session> # Resume from previous session
--debug # Enable debug logging
# Utilities:
conductor validate <file> # Validate task YAML
conductor version # Show version information
Keyboard Shortcuts
| Key |
Action |
โ/โ or j/k |
Navigate task list |
1-9 |
Quick select task |
Enter |
View task details |
p |
Peek at browser |
c |
Create PR |
s |
Skip current task |
r |
Retry failed task |
a |
Abort execution |
t |
Toggle theme |
? |
Show help |
q |
Quit |
๐๏ธ Architecture
graph TB
A[TUI Interface] --> B[Task Manager]
B --> C[MCP Client]
C --> D[Playwright Server]
D --> E[Browser]
E --> F[Claude Code]
B --> G[Retry Logic]
G --> H[Backoff Algorithm]
H --> I[Jitter]
A --> J[Metrics Collector]
J --> K[SQLite Store]
๐งช Development
Project Structure
conductor/
โโโ src/
โ โโโ conductor/
โ โ โโโ __init__.py
โ โ โโโ main.py # Entry point
โ โ โโโ tui/ # Terminal interface
โ โ โโโ mcp/ # MCP integration
โ โ โโโ tasks/ # Task management
โ โ โโโ browser/ # Browser control
โ โ โโโ themes/ # Visual themes
โ โโโ tests/
โโโ examples/
โ โโโ tasks.yaml # Example task definitions
โโโ docs/
โโโ pyproject.toml
โโโ README.md
Running Tests
# Run all tests
pytest
# Run with coverage
pytest --cov=conductor
# Run specific test file
pytest tests/test_task_loader.py
# Run tests in watch mode (requires pytest-watch)
ptw
Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
๐บ๏ธ Roadmap
v0.1.0 - Sprint 1 Foundation (Current)
- Project structure and tooling
- YAML task loading with validation
- MCP client integration layer
- Manual authentication flow
- Splash screen with ASCII art
- CLI entry point
- Basic retry logic with exponential backoff
- Session tracking and branch logging
- Unit tests for core functionality
- Full TUI implementation (Sprint 2)
v1.1.0 - Intelligence
- HITL element discovery
- PR automation
- Advanced metrics
- Session persistence
v1.2.0 - Polish
- Multiple themes
- Plugin system
- Cloud sync
- Team features
v2.0.0 - Scale
- Parallel execution
- Distributed tasks
- Web dashboard
- API endpoints
๐ Troubleshooting
Quick Diagnostics
If you're experiencing issues, run the doctor command first:
conductor doctor
This will check:
- โ MCP server connectivity
- โ Browser launch capability
- โ Navigation functionality
- โ Visual confirmation that browser appears
Browser doesn't open
Ensure Playwright is installed:
playwright install chromium
MCP connection fails
Check MCP server is running:
npx @anthropic/playwright-mcp
Remote browser setup (Mac + Windows PC)
See the comprehensive Remote Browser Setup Guide for configuring Conductor to control a browser on a different machine.
Quick setup:
Windows PC:
npx @playwright/mcp@latest --port 8931 --host 0.0.0.0 --allowed-hosts * --browser msedge
Mac config (~/.conductor/config.yaml):
mcp:
server_url: "http://192.168.1.100:8931/sse" # Must end with /sse!
Unicode characters not displaying
Ensure your terminal supports UTF-8:
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
๐ Performance
| Metric |
Value |
| Startup Time |
<2s |
| Memory Usage |
<100MB |
| Task Processing |
50+ tasks/session |
| Success Rate |
>95% with retries |
๐ Acknowledgments
- Anthropic for Claude and MCP
- Textual for the amazing TUI framework
- Rich for beautiful terminal rendering
- The open-source community for inspiration
๐ License
This project is licensed under the MIT License - see LICENSE file for details.
๐ค Support
๐ Star History
If you find Conductor useful, please consider giving it a star! โญ
Built with โค๏ธ by developers, for developers
Conductor - Orchestrating intelligence, one task at a time