Pair Programming for Claude Code

A pair programming framework where Claude acts as navigator and the developer is the driver. ADHD-aware practices throughout. Everything managed from inside claude-code via the /pair slash command.

Quick Start

# Install (creates symlinks, prints hooks config to merge)
./install.sh

# In any claude-code session:
/pair on implement sliding window rate limiter

# End of session:
/pair off

How It Works

Three interlocking parts:

1. SKILL.md — governs Claude's behaviour: navigator role, hint escalation ladder, ADHD-aware practices, inline comment protocol
2. Inline comment protocol — CLAUDE: / CLAUDE> / CLAUDE! tags in source files as a low-friction communication channel
3. Slash command + hooks — /pair handles all session management; hooks inject session context automatically

Commands

Command	Description
/pair on [goal]	Activate navigator mode with optional goal
/pair off	Deactivate pair mode
/pair status	Show current session state
/pair goal [text]	Update the session goal
/pair sessions	List recent sessions
/pair resume	Show resume command for most recent session
/pair clean [file...]	Strip solved CLAUDE comment blocks
/pair clean-sessions [days]	Clean up old session files

Installation

Prerequisites

• jq
• python3
• Claude Code CLI

Install

git clone git@github.com:agustinvalencia/pair-programming.git ~/repositories/personal/pair-programming
cd ~/repositories/personal/pair-programming
./install.sh

Then merge the printed hooks block into ~/.claude/settings.json.

Uninstall

./uninstall.sh

Then remove the hooks entries from ~/.claude/settings.json.

File Structure

skill/
  SKILL.md              # Full skill definition (navigator behaviour)
  SKILL-compact.md      # Compact version kept in context during sessions
commands/
  pair.md               # Slash command definition
hooks/
  pair-prompt-inject.sh # UserPromptSubmit hook (session_id + navigator reminder)
  pair-session-end.sh   # SessionEnd hook (timestamps state file)
scripts/
  pair-clean-comments.py # CLAUDE comment block cleanup utility

Session State

Session state is stored at ~/.claude/pair-sessions/<session_id>.json and tracks:

• Goal, decisions made, open questions, parked tangents
• Stopping point for easy resume
• Timestamps for session management