pair-cli

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