Skip to content

USAGE.md

Latest commit

 

History

History
330 lines (247 loc) · 8.07 KB

USAGE.md

File metadata and controls

330 lines (247 loc) · 8.07 KB
Raw

🎼 Code Conductor Usage Guide

This guide shows you two ways to use Code Conductor: with the Conductor desktop app (macOS only) or manually with multiple terminals (all platforms).

🖥️ Recommended Terminals

Primary: Warp - AI-centered, tabbed, cross-platform terminal (2025)

  • macOS: brew install --cask warp
  • Ubuntu/Debian: sudo apt install warp or download .deb from warp.dev
  • Fedora/RHEL: sudo rpm -i warp-*.rpm
  • Arch: pacman -U warp-*.pkg.tar.zst
  • Windows: winget install Warp.Warp

Fallback Options:

  • macOS: iTerm2 (brew install --cask iterm2), Terminal.app
  • Linux: Kitty (apt install kitty), Alacritty (cargo install alacritty), GNOME Terminal
  • Windows: Windows Terminal with PowerShell + WSL
  • Session Management: tmux (all platforms), screen for headless/SSH scenarios

🖥️ Option A: Conductor Desktop App (Recommended)

The Conductor app provides a streamlined experience with integrated AI sessions and workspace management.

Prerequisites

Step-by-Step Workflow

1. Initialize Your Workspace

# From your project root
./conductor start dev

The conductor command will:

  • ✅ Check dependencies
  • 🎯 Claim an available task
  • 🌳 Create an isolated git worktree
  • 📂 Print the workspace path

2. Open in Conductor App

To open your workspace in Conductor:

macOS Only:

  1. Open Conductor app: open -a Conductor
  2. In Conductor: File → Add Workspace
  3. Navigate to and select your worktree directory
  4. Start coding with Claude Code

Note: Conductor desktop app is currently macOS-only. Linux/Windows users should use the terminal workflow below.

3. Start Your AI Session

In Conductor:

  1. The workspace opens with your task's isolated git branch
  2. All task details are available in the worktree
  3. Start coding with your Claude session
  4. Commit and push when ready

4. Complete the Task

# In your worktree (or via Conductor terminal)
git add .
git commit -m "Implement: [task title]"
git push origin agent-dev-task_001

# Create PR when ready
gh pr create --title "Complete: [task title]"

🖥️ Option B: Multi-Terminal Workflow (All Platforms)

For Linux/Windows users or those who prefer manual control. Conductor app is macOS-only.

Prerequisites

  • Git with worktree support
  • Python 3.8+
  • GitHub CLI (optional but recommended)

Step-by-Step Workflow

1. Claim a Task

# Terminal 1: Start conductor
./conductor start dev

This creates an isolated worktree like:

worktrees/agent-dev-task_001/

2. Work in the Isolated Environment

Option 2A: Using tmux (Recommended for Linux/Unix)

# Create a new tmux session
tmux new-session -d -s conductor-task
tmux send-keys "cd worktrees/agent-dev-task_001" Enter
tmux split-window -h
tmux send-keys "cd worktrees/agent-dev-task_001" Enter
tmux attach -t conductor-task
# Now you have two panes in the worktree directory

Option 2B: Using screen

# Create a new screen session
screen -S conductor-task
# In screen: cd worktrees/agent-dev-task_001
# Ctrl+A, c to create new window
# Ctrl+A, " to split horizontally

Option 2C: Multiple terminal windows

# Terminal 2: Development
cd worktrees/agent-dev-task_001

# Your task details are here:
gh issue view $(basename $PWD | grep -o '[0-9]*$')  # View your assigned issue
ls -la                                               # See the isolated branch

# Start your development session
# (Open your preferred editor, IDE, or Claude session here)

3. Monitor System Status (Optional)

# Terminal 3: Monitoring
python .conductor/scripts/update-status.py
python .conductor/scripts/health-check.py

4. Complete and Submit

# In Terminal 2 (worktree)
git add .
git commit -m "feat: implement user authentication system

- Add JWT token handling
- Implement login/logout endpoints
- Add password hashing
- Include comprehensive tests

Closes: task_001"

git push origin agent-dev-task_001

# Create pull request
gh pr create \
  --title "feat: implement user authentication system" \
  --body "Implements task_001: Add user authentication

## Changes
- JWT token handling
- Login/logout endpoints
- Password hashing with bcrypt
- 100% test coverage

## Testing
- All tests pass
- Manual testing completed
- Security review ready"

🔧 Advanced Usage

Managing Multiple Agents

You can run multiple agents simultaneously:

# Terminal 1: Dev agent
./conductor start dev

# Terminal 2: DevOps agent
./conductor start devops

# Terminal 3: Security review
./conductor start security

Each gets an isolated worktree:

worktrees/
├── agent-dev-task_001/
├── agent-devops-task_002/
└── agent-security-task_003/

Checking System Health

# Quick status check
python .conductor/scripts/health-check.py

# Detailed system metrics
python .conductor/scripts/update-status.py

# Clean up stale work
python .conductor/scripts/cleanup-stale.py

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

Creating Tasks

Via GitHub Issues (Recommended)

  1. Create a GitHub Issue
  2. Add the conductor:task label
  3. Use the issue template for structured task data
  4. The system automatically converts it to a task

Via GitHub CLI

# Create a task using GitHub CLI
gh issue create \
  --title "Your task title" \
  --body "## Description
Detailed description

## Success Criteria
- List success criteria here" \
  --label "conductor:task" \
  --label "effort:medium"

Worktree Management

# List all worktrees
git worktree list

# Remove completed worktree manually
git worktree remove worktrees/agent-dev-task_001

# Clean up all stale worktrees
python .conductor/scripts/cleanup-worktrees.py

# Force cleanup (removes uncommitted changes)
python .conductor/scripts/cleanup-worktrees.py --force

🚀 Pro Tips

Conductor App Users

  • Workspace persistence: Conductor remembers your workspaces
  • Session history: Previous conversations are saved per workspace
  • File watching: Auto-detects file changes for context
  • Terminal integration: Built-in terminal for git commands

Multi-Terminal Users

  • Use tmux/screen: Manage multiple sessions easily
  • Shell aliases: Create shortcuts for common commands
  • Git hooks: Automate task status updates
  • IDE integration: Many IDEs support worktree workflows

Universal Tips

  • Commit often: Small, atomic commits are easier to review
  • Clear messages: Use conventional commit format
  • Test locally: Run tests before pushing
  • Update progress: Add comments to your assigned issue to track progress

🔍 Troubleshooting

Common Issues

"No tasks available"

# Check if tasks exist
gh issue list -l 'conductor:task' --assignee '!*' --state open

# Create a test task via GitHub issue
gh issue create --title "Test task" --label "conductor:task"

"Worktree creation failed"

# Check git status
git status

# Ensure clean working directory
git stash

# Try again
./conductor start dev

"Permission denied" on scripts

# Make scripts executable
chmod +x .conductor/scripts/*.py
chmod +x .conductor/scripts/*.sh

Conductor app won't open workspace

# Check if path exists
ls -la /path/to/worktree

# Open Conductor app (macOS only)
open -a Conductor

# Then use File → Add Workspace to select the directory

Getting Help

  • Validate setup: python .conductor/scripts/validate-config.py
  • Check dependencies: python .conductor/scripts/dependency-check.py
  • System health: python .conductor/scripts/health-check.py
  • GitHub issues: Report bugs
  • Discussions: Ask questions

Ready to orchestrate your development workflow? Pick your preferred approach and start building! 🎼