https://github.com/timwuhaotian/the-pair
The Pair - Automated pair programming โ grab a coffee while two AI agents cross-check each other's work
https://github.com/timwuhaotian/the-pair
agent ai ai-agents claude-code codex codex-cli coding gemini glm gpt kimi minimax opencode pair-programming qwen vibe-coding
Last synced: 16 days ago
JSON representation
The Pair - Automated pair programming โ grab a coffee while two AI agents cross-check each other's work
- Host: GitHub
- URL: https://github.com/timwuhaotian/the-pair
- Owner: timwuhaotian
- License: apache-2.0
- Created: 2026-03-22T18:38:00.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-22T19:56:50.000Z (20 days ago)
- Last Synced: 2026-04-22T21:27:27.173Z (20 days ago)
- Topics: agent, ai, ai-agents, claude-code, codex, codex-cli, coding, gemini, glm, gpt, kimi, minimax, opencode, pair-programming, qwen, vibe-coding
- Language: TypeScript
- Homepage:
- Size: 97 MB
- Stars: 327
- Watchers: 1
- Forks: 22
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# The Pair
**Automated pair programming โ grab a coffee while two AI agents cross-check each other's work, built by itself**
[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://github.com/timwuhaotian/the-pair/releases)
[](https://github.com/timwuhaotian/the-pair/actions)
[](https://www.typescriptlang.org/)
[](https://tauri.app/)
[](https://react.dev/)
[](CONTRIBUTING.md)
[](CHANGELOG.md)
๐ **English** โข [็ฎไฝไธญๆ](README.zh.md) โข [ํ๊ตญ์ด](README.ko.md) โข [ๆฅๆฌ่ช](README.ja.md)
**macOS** โข **Windows** โข **Linux**
_Watch Mentor and Executor agents collaborate in real-time_
---
## Overview
**Worried about AI code hallucinations?** The Pair solves this by running two AI agents that cross-check each other:
- **Mentor Agent** โ Plans, reviews, and validates (read-only)
- **Executor Agent** โ Writes code and runs commands
While they work, go grab a coffee. Come back to reviewed, cross-validated code.
### Key Benefits
- **Dual-Model Cross-Validation** โ Two models check each other's work, dramatically reducing code hallucinations
- **Automated Collaboration** โ Agents work together without constant human intervention
- **Real-Time Monitoring** โ Watch CPU/memory usage per agent with live activity tracking
- **Git Integration** โ Automatic tracking of all file changes made during a session
- **Human Oversight** โ Step in at any time to pause, adjust, or reassign tasks
- **Session Recovery** โ Resume interrupted sessions with full conversation history restoration
- **Onboarding Wizard** โ Guided first-time setup with model configuration and directory selection
- **Dark/Light Themes** โ Automatic system theme detection with manual toggle
### Use Cases
- Autonomous coding sessions โ Let AI agents iterate on features while you focus on review
- Code refactoring โ Automated analysis and implementation of improvements
- Bug fixing โ Agents collaborate to diagnose and resolve issues
- Learning tool โ Observe how AI agents break down and solve problems
- Interrupted work recovery โ Restore session state after app restart or crash
---
## Features
- **Dual-Agent Architecture** โ Separation of planning (Mentor) and execution (Executor)
- **Full Automation Mode** โ Agents work autonomously with workspace-scoped permissions
- **Real-Time Activity Tracking** โ Live status showing agent activity (thinking, doing, waiting)
- **Resource Monitoring** โ CPU and memory usage per agent, updated every second
- **Git Change Tracking** โ Automatic detection of modified, added, or deleted files
- **Conversation History** โ Full transcript of all agent interactions
- **Local Orchestration** โ Runs the app and agent coordination locally; model calls depend on your selected provider or local model
- **Multi-Provider** โ Works with opencode, Claude Code, Codex, and Gemini CLI
- **Reasoning Controls** โ Adjust thinking effort per agent role (low/medium/high)
- **Token Tracking** โ Real-time per-turn token usage displayed inline
- **Skill System** โ Attach project-specific skill files to guide agent behavior
- **Auto-Update** โ In-app update checking with one-click install
---
## Screenshots
Review Result - Fail With Evidence
Review Result - Pass With Evidence
---
## Installation
Download the latest release from [GitHub Releases](https://github.com/timwuhaotian/the-pair/releases):
| Platform | File |
| ----------- | ------------------------------ |
| **macOS** | `the-pair-{version}.zip` |
| **Windows** | `the-pair-{version}-setup.exe` |
| **Linux** | `the-pair-{version}.AppImage` |
### From Source
```bash
git clone https://github.com/timwuhaotian/the-pair.git
cd the-pair
npm install
npm run build:mac # or build:win / build:linux
```
On macOS, `build:mac` produces a local DMG, while `build:mac:release` produces the ZIP-style release bundle used in GitHub Releases. The build script will ensure the required Rust targets are installed before invoking Tauri. If you prefer to set them up manually, run:
```bash
rustup target add aarch64-apple-darwin x86_64-apple-darwin
```
---
## Quick Start
> [!NOTE]
> The Pair requires at least one AI provider CLI: [opencode](https://opencode.ai), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or [Gemini CLI](https://github.com/google-gemini/gemini-cli).
### 1. Install an AI Provider
Install one or more of the supported CLIs:
- **opencode** โ `curl -fsSL https://opencode.ai/install | bash` or `npm install -g opencode-ai`
- **Claude Code** โ see [Claude Code setup](https://docs.anthropic.com/en/docs/claude-code/getting-started), or use `npm install -g @anthropic-ai/claude-code`
- **Codex** โ `npm install -g @openai/codex`
- **Gemini CLI** โ `npm install -g @google/gemini-cli` or `npx @google/gemini-cli`
### 2. Configure AI Models (Optional)
For opencode-backed models, set up your AI providers in `~/.config/opencode/opencode.json`:
```json
{
"provider": {
"openai": { "options": { "apiKey": "your-api-key" } },
"anthropic": { "options": { "apiKey": "your-api-key" } }
}
}
```
> [!TIP]
> Codex, Claude Code, and Gemini CLI are detected from their installed CLIs and sign-in state. You can also use local models with [Ollama](https://ollama.com) for offline development.
### 3. Launch The Pair
Open from Applications folder or start menu.
### 4. Create Your First Pair
1. Click **New Pair** button
2. Configure: name, directory, task description, and AI models
3. Watch the agents work โ Mentor plans, Executor implements, Mentor reviews
4. Monitor progress with real-time activity tracking and file changes
---
## Configuration
### Provider Configuration
OpenCode-backed models use your existing opencode configuration:
- **macOS/Linux**: `~/.config/opencode/opencode.json`
- **Windows**: `%APPDATA%/opencode/opencode.json`
Codex, Claude Code, and Gemini CLI are detected from their local CLI install and account state.
### Pair Runtime
Each pair maintains its own runtime configuration in `.pair/runtime//` within your project directory, including session files, runtime permissions, and conversation history.
> [!NOTE]
> The Pair does not modify your global opencode permissions. All permissions are session-specific.
---
## Architecture
### Tech Stack
| Layer | Technology |
| -------------- | --------------------- |
| **Framework** | Tauri 2.x |
| **Backend** | Rust |
| **Frontend** | React 19 + TypeScript |
| **Styling** | Tailwind CSS v4 |
| **State** | Zustand |
| **Animations** | Framer Motion |
| **Icons** | Lucide React |
### System Architecture
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ The Pair App โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Frontend (React UI) โ
โ โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ โ
โ โ Dashboard โ Pair Detail โ Settings โ โ
โ โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโ โ
โ โ Tauri IPC โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Backend (Rust) โ
โ โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ โ
โ โ PairManager โMessageBroker โ ProcessSpawner โ โ
โ โ (Lifecycle) โ(State Machine)โ(Multi-Provider) โ โ
โ โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโ โ
โ โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ โ
โ โ Git Tracker โ Worktrees โ Session Snapshot โ โ
โ โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโ โ
โ โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ โ
โ โResource Mon. โ Acceptance โ Report Generator โ โ
โ โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโดโโโโโโโโโโโโโโ
โ โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ AI Provider CLIsโ โ Git Repo โ
โ opencode/Claude/ โ โ (Workspace) โ
โ Codex/Gemini โ โโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโโโโโโโโ
```
### Agent Workflow
```
Start โ Initialize & Baseline โ Mentoring Phase โ Executing Phase โ Reviewing Phase
โ
Done? โโYesโ Finished
โ
No
โ
(loop back to Mentoring)
```
---
## Development
### Prerequisites
- **Node.js** 22.22+
- **npm** or **pnpm**
- **Git**
- **Rustup** for desktop builds
> [!NOTE]
> Release builds require the updater signing secret to be configured in GitHub Actions.
Run a quick environment check before building:
```bash
npm run preflight
```
### Setup
```bash
git clone https://github.com/timwuhaotian/the-pair.git
cd the-pair
npm install
npm run dev
```
### Project Structure
```
the-pair/
โโโ src/
โ โโโ renderer/ # React frontend
โ โโโ src/
โ โโโ App.tsx
โ โโโ components/
โ โโโ store/
โโโ src-tauri/ # Rust backend
โ โโโ src/
โ โ โโโ lib.rs
โ โ โโโ pair_manager.rs
โ โ โโโ message_broker.rs
โ โ โโโ ...
โ โโโ Cargo.toml
โโโ build/ # Build resources
โโโ package.json
```
### Scripts
| Command | Description |
| --------------------------- | ----------------------------------- |
| `npm run dev` | Start hot-reload development server |
| `npm run preflight` | Check local build prerequisites |
| `npm run preflight:mac` | Check macOS build prerequisites |
| `npm run preflight:win` | Check Windows build prerequisites |
| `npm run preflight:linux` | Check Linux build prerequisites |
| `npm test` | Run JavaScript and Rust unit tests |
| `npm run test:js` | Run Node/TypeScript unit tests |
| `npm run test:rust` | Run Rust unit tests |
| `npm run typecheck` | Check TypeScript types |
| `npm run lint` | Run ESLint |
| `npm run format` | Format with Prettier |
| `npm run e2e:setup` | Install the Appium macOS driver |
| `npm run e2e` | Run mocked end-to-end tests |
| `npm run dev:mock` | Start the app with mocked agents |
| `npm run dev:smoke` | Start the app in smoke-test mode |
| `npm run clean` | Remove generated build artifacts |
| `npm run build:mac` | Build local macOS DMG |
| `npm run build:mac:release` | Build macOS release ZIP bundle |
| `npm run build:win` | Build for Windows |
| `npm run build:linux` | Build for Linux |
---
## FAQ
**Q: How does The Pair differ from single-agent AI coding tools?**
A: Single-agent tools rely on one model to write and self-review code, which can miss its own mistakes. The Pair uses two separate agents where the Mentor reviews the Executor's work, catching errors before they land.
**Q: Does The Pair require internet connectivity?**
A: The Pair runs entirely locally. Only the AI model API calls require internet (or local model setup via Ollama).
**Q: Which AI providers are supported?**
A: The Pair supports four providers out of the box: **opencode** (any compatible model), **Claude Code CLI**, **OpenAI Codex CLI**, and **Gemini CLI**. Codex, Claude, and Gemini are detected automatically from their installed CLIs. You can mix providers โ e.g., Claude as Mentor and Codex as Executor.
**Q: Can I use my own AI models?**
A: Yes, The Pair is model-agnostic. Opencode-backed models work with any compatible provider (OpenAI, Anthropic, Ollama, etc.). For Claude, Codex, and Gemini, simply install their CLI and sign in.
**Q: Can I control how much the agents "think"?**
A: Yes. The Pair supports **reasoning effort controls** for models that offer it (Claude, Codex o-series, Gemini 2.5). You can set low/medium/high effort per role โ Mentor and Executor independently โ from pair creation or settings.
**Q: How do I track token usage and costs?**
A: Token usage is tracked in real-time per agent turn. Live output token counts appear inline in the agent console so you can monitor spend as agents work.
**Q: What happens if an agent gets stuck in a loop?**
A: The Pair implements iteration limits. After a configured number of iterations, agents pause for human intervention.
**Q: What if the app crashes or I close it mid-session?**
A: Session snapshots are saved automatically. On relaunch, The Pair detects interrupted sessions and offers to restore them with full conversation history, so agents can continue from where they left off.
**Q: Does The Pair auto-update?**
A: Yes. The Pair checks for new versions on launch and notifies you with a one-click update flow. No manual download needed.
---
Built with โค๏ธ by [timwuhaotian](https://github.com/timwuhaotian)
**โญ Star this repo if you find it helpful!**