pair-programming

$2a

Required:

• Claude Flow CLI installed (npm install -g claude-flow@alpha)

• Git repository (optional but recommended)

Recommended:

• Testing framework (Jest, pytest, etc.)

• Linter configured (ESLint, pylint, etc.)

• Code formatter (Prettier, Black, etc.)

Quick Start

Basic Session

# Start simple pair programming

claude-flow pair --start

TDD Session

# Test-driven development

claude-flow pair --start \

  --mode tdd \

  --test-first \

  --coverage 90

Complete Guide

Session Control Commands

#### Starting Sessions

# Basic start

claude-flow pair --start

# Expert refactoring session

claude-flow pair --start \

  --agent senior-dev \

  --focus refactor \

  --verify \

  --threshold 0.98

# Debugging session

claude-flow pair --start \

  --agent debugger-expert \

  --focus debug \

  --review

# Learning session

claude-flow pair --start \

  --mode mentor \

  --pace slow \

  --examples

#### Session Management

# Check status

claude-flow pair --status

# View history

claude-flow pair --history

# Pause session

$pause [--reason <reason>]

# Resume session

$resume

# End session

claude-flow pair --end [--save] [--report]

Available Modes

#### Driver Mode

You write code while AI provides guidance.

claude-flow pair --start --mode driver

Your Responsibilities:

• Write actual code

• Implement solutions

• Make immediate decisions

• Handle syntax and structure

AI Navigator:

• Strategic guidance

• Spot potential issues

• Suggest improvements

• Real-time review

• Track overall direction

Best For:

• Learning new patterns

• Implementing familiar features

• Quick iterations

• Hands-on debugging

Commands:

$suggest     - Get implementation suggestions

$review      - Request code review

$explain     - Ask for explanations

$optimize    - Request optimization ideas

$patterns    - Get pattern recommendations

#### Navigator Mode

AI writes code while you provide direction.

claude-flow pair --start --mode navigator

Your Responsibilities:

• Provide high-level direction

• Review generated code

• Make architectural decisions

• Ensure business requirements

AI Driver:

• Write implementation code

• Handle syntax details

• Implement your guidance

• Manage boilerplate

• Execute refactoring

Best For:

• Rapid prototyping

• Boilerplate generation

• Learning from AI patterns

• Exploring solutions

Commands:

$implement   - Direct implementation

$refactor    - Request refactoring

$test        - Generate tests

$document    - Add documentation

$alternate   - See alternative approaches

#### Switch Mode

Automatically alternates roles at intervals.

# Default 10-minute intervals

claude-flow pair --start --mode switch

# 5-minute intervals (rapid)

claude-flow pair --start --mode switch --interval 5m

# 15-minute intervals (deep focus)

claude-flow pair --start --mode switch --interval 15m

Handoff Process:

• 30-second warning before switch

• Current driver completes thought

• Context summary generated

• Roles swap smoothly

• New driver continues

Best For:

• Balanced collaboration

• Knowledge sharing

• Complex features

• Extended sessions

#### Specialized Modes

TDD Mode - Test-Driven Development:

claude-flow pair --start \

  --mode tdd \

  --test-first \

  --coverage 100

Workflow: Write failing test → Implement → Refactor → Repeat

Review Mode - Continuous code review:

claude-flow pair --start \

  --mode review \

  --strict \

  --security

Features: Real-time feedback, security scanning, performance analysis

Mentor Mode - Learning-focused:

claude-flow pair --start \

  --mode mentor \

  --explain-all \

  --pace slow

Features: Detailed explanations, step-by-step guidance, pattern teaching

Debug Mode - Problem-solving:

claude-flow pair --start \

  --mode debug \

  --verbose \

  --trace

Features: Issue identification, root cause analysis, fix suggestions

In-Session Commands

#### Code Commands

$explain [--level basic|detailed|expert]

  Explain the current code or selection

$suggest [--type refactor|optimize|security|style]

  Get improvement suggestions

$implement <description>

  Request implementation (navigator mode)

$refactor [--pattern <pattern>] [--scope function|file|module]

  Refactor selected code

$optimize [--target speed|memory|both]

  Optimize code for performance

$document [--format jsdoc|markdown|inline]

  Add documentation to code

$comment [--verbose]

  Add inline comments

$pattern <pattern-name> [--example]

  Apply a design pattern

#### Testing Commands

$test [--watch] [--coverage] [--only <pattern>]

  Run test suite

$test-gen [--type unit|integration|e2e]

  Generate tests for current code

$coverage [--report html|json|terminal]

  Check test coverage

$mock <target> [--realistic]

  Generate mock data or functions

$test-watch [--on-save]

  Enable test watching

$snapshot [--update]

  Create test snapshots

#### Review Commands

$review [--scope current|file|changes] [--strict]

  Perform code review

$security [--deep] [--fix]

  Security analysis

$perf [--profile] [--suggestions]

  Performance analysis

$quality [--detailed]

  Check code quality metrics

$lint [--fix] [--config <config>]

  Run linters

$complexity [--threshold <value>]

  Analyze code complexity

#### Navigation Commands

$goto <file>[:line[:column]]

  Navigate to file or location

$find <pattern> [--regex] [--case-sensitive]

  Search in project

$recent [--limit <n>]

  Show recent files

$bookmark [add|list|goto|remove] [<name>]

  Manage bookmarks

$history [--limit <n>] [--filter <pattern>]

  Show command history

$tree [--depth <n>] [--filter <pattern>]

  Show project structure

#### Git Commands

$diff [--staged] [--file <file>]

  Show git diff

$commit [--message <msg>] [--amend]

  Commit with verification

$branch [create|switch|delete|list] [<name>]

  Branch operations

$stash [save|pop|list|apply] [<message>]

  Stash operations

$log [--oneline] [--limit <n>]

  View git log

$blame [<file>]

  Show git blame

#### AI Partner Commands

$agent [switch|info|config] [<agent-name>]

  Manage AI agent

$teach <preference>

  Teach the AI your preferences

$feedback [positive|negative] <message>

  Provide feedback to AI

$personality [professional|friendly|concise|verbose]

  Adjust AI personality

$expertise [add|remove|list] [<domain>]

  Set AI expertise focus

#### Metrics Commands

$metrics [--period today|session|week|all]

  Show session metrics

$score [--breakdown]

  Show quality scores

$productivity [--chart]

  Show productivity metrics

$leaderboard [--personal|team]

  Show improvement leaderboard

#### Role & Mode Commands

$switch [--immediate]

  Switch driver$navigator roles

$mode <type>

  Change mode (driver|navigator|switch|tdd|review|mentor|debug)

$role

  Show current role

$handoff

  Prepare role handoff

Command Shortcuts

Alias

Full Command

$s

$suggest

$e

$explain

$t

$test

$r

$review

$c

$commit

$g

$goto

$f

$find

$h

$help

$sw

$switch

$st

$status

Configuration

#### Basic Configuration

Create .claude-flow$pair-config.json:

{

  "pair": {

    "enabled": true,

    "defaultMode": "switch",

    "defaultAgent": "auto",

    "autoStart": false,

    "theme": "professional"

  }

}

#### Complete Configuration

{

  "pair": {

    "general": {

      "enabled": true,

      "defaultMode": "switch",

      "defaultAgent": "senior-dev",

      "language": "javascript",

      "timezone": "UTC"

    },

    "modes": {

      "driver": {

        "enabled": true,

        "suggestions": true,

        "realTimeReview": true,

        "autoComplete": false

      },

      "navigator": {

        "enabled": true,

        "codeGeneration": true,

        "explanations": true,

        "alternatives": true

      },

      "switch": {

        "enabled": true,

        "interval": "10m",

        "warning": "30s",

        "autoSwitch": true,

        "pauseOnIdle": true

      }

    },

    "verification": {

      "enabled": true,

      "threshold": 0.95,

      "autoRollback": true,

      "preCommitCheck": true,

      "continuousMonitoring": true,

      "blockOnFailure": true

    },

    "testing": {

      "enabled": true,

      "autoRun": true,

      "framework": "jest",

      "onSave": true,

      "coverage": {

        "enabled": true,

        "minimum": 80,

        "enforce": true,

        "reportFormat": "html"

      }

    },

    "review": {

      "enabled": true,

      "continuous": true,

      "preCommit": true,

      "security": true,

      "performance": true,

      "style": true,

      "complexity": {

        "maxComplexity": 10,

        "maxDepth": 4,

        "maxLines": 100

      }

    },

    "git": {

      "enabled": true,

      "autoCommit": false,

      "commitTemplate": "feat: {message}",

      "signCommits": false,

      "pushOnEnd": false,

      "branchProtection": true

    },

    "session": {

      "autoSave": true,

      "saveInterval": "5m",

      "maxDuration": "4h",

      "idleTimeout": "15m",

      "breakReminder": "45m",

      "metricsInterval": "1m"

    },

    "ai": {

      "model": "advanced",

      "temperature": 0.7,

      "maxTokens": 4000,

      "personality": "professional",

      "expertise": ["backend", "testing", "security"],

      "learningEnabled": true

    }

  }

}

#### Built-in Agents

{

  "agents": {

    "senior-dev": {

      "expertise": ["architecture", "patterns", "optimization"],

      "style": "thorough",

      "reviewLevel": "strict"

    },

    "tdd-specialist": {

      "expertise": ["testing", "mocks", "coverage"],

      "style": "test-first",

      "reviewLevel": "comprehensive"

    },

    "debugger-expert": {

      "expertise": ["debugging", "profiling", "tracing"],

      "style": "analytical",

      "reviewLevel": "focused"

    },

    "junior-dev": {

      "expertise": ["learning", "basics", "documentation"],

      "style": "questioning",

      "reviewLevel": "educational"

    }

  }

}

#### CLI Configuration

# Set configuration

claude-flow pair config set defaultMode switch

claude-flow pair config set verification.threshold 0.98

# Get configuration

claude-flow pair config get

claude-flow pair config get defaultMode

# Export/Import

claude-flow pair config export > config.json

claude-flow pair config import config.json

# Reset

claude-flow pair config reset

#### Profile Management

Create reusable profiles:

# Create profile

claude-flow pair profile create refactoring \

  --mode driver \

  --verify true \

  --threshold 0.98 \

  --focus refactor

# Use profile

claude-flow pair --start --profile refactoring

# List profiles

claude-flow pair profile list

Profile configuration:

{

  "profiles": {

    "refactoring": {

      "mode": "driver",

      "verification": {

        "enabled": true,

        "threshold": 0.98

      },

      "focus": "refactor"

    },

    "debugging": {

      "mode": "navigator",

      "agent": "debugger-expert",

      "trace": true,

      "verbose": true

    },

    "learning": {

      "mode": "mentor",

      "pace": "slow",

      "explanations": "detailed",

      "examples": true

    }

  }

}

Real-World Examples

#### Example 1: Feature Implementation

Implementing user authentication with JWT tokens:

# Session setup

claude-flow pair --start \

  --mode switch \

  --agent senior-dev \

  --focus implement \

  --verify \

  --test

Session Flow:

👥 Starting pair programming for authentication feature...

[DRIVER: You - 10 minutes]

$explain JWT authentication flow

> AI explains JWT concepts and best practices

$suggest implementation approach

> AI suggests using middleware pattern with refresh tokens

# You write the basic auth middleware structure

[SWITCH TO NAVIGATOR]

[NAVIGATOR: AI - 10 minutes]

$implement JWT token generation with refresh tokens

> AI generates secure token implementation

$test-gen

> AI creates comprehensive test suite

[SWITCH TO DRIVER]

[DRIVER: You - 10 minutes]

# You refine the implementation

$review --security

> AI performs security review, suggests improvements

$commit --message "feat: JWT authentication with refresh tokens"

✅ Truth Score: 0.98 - Committed successfully

#### Example 2: Bug Fixing

Debugging a memory leak in Node.js:

# Session setup

claude-flow pair --start \

  --mode navigator \

  --agent debugger-expert \

  --focus debug \

  --trace

Session Flow:

👥 Starting debugging session...

$status

> Analyzing application for memory issues...

$perf --profile

> Memory usage growing: 150MB → 450MB over 10 minutes

$find "new EventEmitter" --regex

> Found 3 instances of EventEmitter creation

$inspect eventEmitters --deep

> Discovering listeners not being removed

$suggest fix for memory leak

> AI suggests: "Add removeListener in cleanup functions"

$implement cleanup functions for all event emitters

> AI generates proper cleanup code

$test

> Memory stable at 150MB ✅

$commit --message "fix: memory leak in event emitters"

#### Example 3: TDD Session

Building shopping cart with test-driven development:

# Session setup

claude-flow pair --start \

  --mode tdd \

  --agent tdd-specialist \

  --test-first

Session Flow:

👥 TDD Session: Shopping Cart Feature

[RED PHASE]

$test-gen "add item to cart"

> AI writes failing test:

  ✗ should add item to cart

  ✗ should update quantity for existing item

  ✗ should calculate total price

[GREEN PHASE]

$implement minimal cart functionality

> You write just enough code to pass tests

$test

> Tests passing: 3/3 ✅

[REFACTOR PHASE]

$refactor --pattern repository

> AI refactors to repository pattern

$test

> Tests still passing: 3/3 ✅

[NEXT CYCLE]

$test-gen "remove item from cart"

> AI writes new failing tests...

#### Example 4: Code Refactoring

Modernizing legacy code:

# Session setup

claude-flow pair --start \

  --mode driver \

  --focus refactor \

  --verify \

  --threshold 0.98

Session Flow:

👥 Refactoring Session: Modernizing UserService

$analyze UserService.js

> AI identifies:

  - Callback hell (5 levels deep)

  - No error handling

  - Tight coupling

  - No tests

$suggest refactoring plan

> AI suggests:

  1. Convert callbacks to async$await

  2. Add error boundaries

  3. Extract dependencies

  4. Add unit tests

$test-gen --before-refactor

> AI generates tests for current behavior

$refactor callbacks to async$await

# You refactor with AI guidance

$test

> All tests passing ✅

$review --compare

> AI shows before$after comparison

> Code complexity: 35 → 12

> Truth score: 0.99 ✅

$commit --message "refactor: modernize UserService with async$await"

#### Example 5: Performance Optimization

Optimizing slow React application:

# Session setup

claude-flow pair --start \

  --mode switch \

  --agent performance-expert \

  --focus optimize \

  --profile

Session Flow:

👥 Performance Optimization Session

$perf --profile

> React DevTools Profiler Results:

  - ProductList: 450ms render

  - CartSummary: 200ms render

  - Unnecessary re-renders: 15

$suggest optimizations for ProductList

> AI suggests:

  1. Add React.memo

  2. Use useMemo for expensive calculations

  3. Implement virtualization for long lists

$implement React.memo and useMemo

# You implement with AI guidance

$perf --profile

> ProductList: 45ms render (90% improvement!) ✅

$implement virtualization with react-window

> AI implements virtual scrolling

$perf --profile

> ProductList: 12ms render (97% improvement!) ✅

> FPS: 60 stable ✅

$commit --message "perf: optimize ProductList with memoization and virtualization"

#### Example 6: API Development

Building RESTful API with Express:

# Session setup

claude-flow pair --start \

  --mode navigator \

  --agent backend-expert \

  --focus implement \

  --test

Session Flow:

👥 API Development Session

$design REST API for blog platform

> AI designs endpoints:

  POST   $api$posts

  GET    $api$posts

  GET    $api$posts/:id

  PUT    $api$posts/:id

  DELETE $api$posts/:id

$implement CRUD endpoints with validation

> AI implements with Express + Joi validation

$test-gen --integration

> AI generates integration tests

$security --api

> AI adds:

  - Rate limiting

  - Input sanitization

  - JWT authentication

  - CORS configuration

$document --openapi

> AI generates OpenAPI documentation

$test --integration

> All endpoints tested: 15/15 ✅

Session Templates

#### Quick Start Templates

# Refactoring template

claude-flow pair --template refactor

# Focus: Code improvement

# Verification: High (0.98)

# Testing: After each change

# Review: Continuous

# Feature template

claude-flow pair --template feature

# Focus: Implementation

# Verification: Standard (0.95)

# Testing: On completion

# Review: Pre-commit

# Debug template

claude-flow pair --template debug

# Focus: Problem solving

# Verification: Moderate (0.90)

# Testing: Regression tests

# Review: Root cause

# Learning template

claude-flow pair --template learn

# Mode: Mentor

# Pace: Slow

# Explanations: Detailed

# Examples: Many

Session Management

#### Session Status

claude-flow pair --status

Output:

👥 Pair Programming Session

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Session ID: pair_1755021234567

Duration: 45 minutes

Status: Active

Partner: senior-dev

Current Role: DRIVER (you)

Mode: Switch (10m intervals)

Next Switch: in 3 minutes

📊 Metrics:

├── Truth Score: 0.982 ✅

├── Lines Changed: 234

├── Files Modified: 5

├── Tests Added: 12

├── Coverage: 87% ↑3%

└── Commits: 3

🎯 Focus: Implementation

📝 Current File: src$auth$login.js

#### Session History

claude-flow pair --history

Output:

📚 Session History

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. 2024-01-15 14:30 - 16:45 (2h 15m)

   Partner: expert-coder

   Focus: Refactoring

   Truth Score: 0.975

   Changes: +340 -125 lines

2. 2024-01-14 10:00 - 11:30 (1h 30m)

   Partner: tdd-specialist

   Focus: Testing

   Truth Score: 0.991

   Tests Added: 24

3. 2024-01-13 15:00 - 17:00 (2h)

   Partner: debugger-expert

   Focus: Bug Fixing

   Truth Score: 0.968

   Issues Fixed: 5

#### Session Persistence

# Save session

claude-flow pair --save [--name <name>]

# Load session

claude-flow pair --load <session-id>

# Export session

claude-flow pair --export <session-id> [--format json|md]

# Generate report

claude-flow pair --report <session-id>

#### Background Sessions

# Start in background

claude-flow pair --start --background

# Monitor background session

claude-flow pair --monitor

# Attach to background session

claude-flow pair --attach <session-id>

# End background session

claude-flow pair --end <session-id>

Advanced Features

#### Custom Commands

Define in configuration:

{

  "customCommands": {

    "tdd": "$test-gen && $test --watch",

    "full-review": "$lint --fix && $test && $review --strict",

    "quick-fix": "$suggest --type fix && $implement && $test"

  }

}

Use custom commands:

$custom tdd

$custom full-review

#### Command Chaining

$test && $commit && $push

$lint --fix && $test && $review --strict

#### Session Recording

# Start with recording

claude-flow pair --start --record

# Replay session

claude-flow pair --replay <session-id>

# Session analytics

claude-flow pair --analytics <session-id>

#### Integration Options

With Git:

claude-flow pair --start --git --auto-commit

With CI/CD:

claude-flow pair --start --ci --non-interactive

With IDE:

claude-flow pair --start --ide vscode

Best Practices

#### Session Practices

• Clear Goals - Define session objectives upfront

• Appropriate Mode - Choose based on task type

• Enable Verification - For critical code paths

• Regular Testing - Maintain quality continuously

• Session Notes - Document important decisions

• Regular Breaks - Take breaks every 45-60 minutes

#### Code Practices

• Test Early - Run tests after each change

• Verify Before Commit - Check truth scores

• Review Security - Always for sensitive code

• Profile Performance - Use $perf for optimization

• Save Sessions - For complex work

• Learn from AI - Ask questions frequently

#### Mode Selection

• Driver Mode: When learning, controlling implementation

• Navigator Mode: For rapid prototyping, generation

• Switch Mode: Long sessions, balanced collaboration

• TDD Mode: Building with tests

• Review Mode: Quality focus

• Mentor Mode: Learning priority

• Debug Mode: Fixing issues

Troubleshooting

#### Session Won't Start

• Check agent availability

• Verify configuration file syntax

• Ensure clean workspace

• Review log files

#### Session Disconnected

• Use --recover to restore

• Check network connection

• Verify background processes

• Review auto-save files

#### Poor Performance

• Reduce verification threshold

• Disable continuous testing

• Check system resources

• Use lighter AI model

#### Configuration Issues

• Validate JSON syntax

• Check file permissions

• Review priority order (CLI > env > project > user > global)

• Run claude-flow pair config validate

Quality Metrics

#### Truth Score Thresholds

Error:   < 0.90 ❌

Warning: 0.90 - 0.95 ⚠️

Good:    0.95 - 0.98 ✅

Excellent: > 0.98 🌟

#### Coverage Thresholds

Error:   < 70% ❌

Warning: 70% - 80% ⚠️

Good:    80% - 90% ✅

Excellent: > 90% 🌟

#### Complexity Thresholds

Error:   > 15 ❌

Warning: 10 - 15 ⚠️

Good:    5 - 10 ✅

Excellent: < 5 🌟

Environment Variables

Override configuration via environment:

export CLAUDE_PAIR_MODE=driver

export CLAUDE_PAIR_VERIFY=true

export CLAUDE_PAIR_THRESHOLD=0.98

export CLAUDE_PAIR_AGENT=senior-dev

export CLAUDE_PAIR_AUTO_TEST=true

Command History

Navigate history:

• ↑/↓ - Navigate through command history

• Ctrl+R - Search command history

• !! - Repeat last command

• !<n> - Run command n from history

Keyboard Shortcuts (Configurable)

Default shortcuts:

{

  "shortcuts": {

    "switch": "ctrl+shift+s",

    "suggest": "ctrl+space",

    "review": "ctrl+r",

    "test": "ctrl+t"

  }

}

Related Commands

• claude-flow pair --help - Show help

• claude-flow pair config - Manage configuration

• claude-flow pair profile - Manage profiles

• claude-flow pair templates - List templates

• claude-flow pair agents - List available agents