pair-cli

Turn-based pair programming CLI with AI. Stay sharp while coding with AI assistance.

Why?

Traditional AI coding tools create a passive loop: prompt → wait → review → fix → repeat. You become a code reviewer, not a programmer.

pair makes AI coding interactive:

• Tasks split into turns alternating between you and AI
• You write tests, AI writes implementation
• You handle edge cases, AI handles happy paths
• XP, streaks, and levels keep you engaged

Install

# Clone and build
git clone https://github.com/gaupoit/pair-cli.git
cd pair-cli
pnpm install
pnpm build

# Link globally
pnpm link --global

Setup

# Copy env template
cp .env.example .env

# Add your API key (Gemini is default)
# Get one at https://aistudio.google.com/apikey
echo "GEMINI_API_KEY=your-key-here" >> .env

# Or use Claude instead
# echo "AI_PROVIDER=claude" >> .env
# echo "ANTHROPIC_API_KEY=your-key-here" >> .env

Usage

Start a session

pair start "add user authentication with JWT"

AI breaks down the task into turns:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 Task: add user authentication with JWT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  1. ► CURRENT [YOU] Write unit tests for login endpoint
  2. ○ PENDING [AI] Implement login endpoint with JWT generation
  3. ○ PENDING [YOU] Define TypeScript interfaces for User and Token
  4. ○ PENDING [AI] Add token validation middleware
  ...

Complete your turn

# After you've written your code
pair done

Get a hint (costs 50% XP)

pair hint

Skip your turn (0 XP, resets streak)

pair skip

Check progress

pair status   # Current session
pair stats    # Your overall stats

Abandon session

pair abandon

Scoring

| Action | XP | |--------|-----| | Complete your turn | +10 | | Complete with hint | +5 | | Skip turn | 0 | | 3+ turn streak | 1.5x multiplier |

Commands

| Command | Description | |---------|-------------| | pair start <task> | Start a new session | | pair done | Complete current turn | | pair skip | Skip your turn | | pair hint | Get a hint | | pair status | Show session progress | | pair stats | Show your statistics | | pair abandon | Abandon current session |

How turns are assigned

| You | AI | |-----|-----| | Tests | Implementation | | Interfaces/Types | Logic | | Edge cases | Happy path | | Documentation | Refactoring |

Configuration

Environment variables in .env:

| Variable | Default | Description | |----------|---------|-------------| | AI_PROVIDER | gemini | AI provider (gemini or claude) | | GEMINI_API_KEY | - | Google AI API key | | ANTHROPIC_API_KEY | - | Anthropic API key |

License

MIT