# The Pair
**Automated AI pair programming โ two AI agents cross-check each other's code, so you can grab a coffee and come back to reviewed, validated work. _(Yes, The Pair was built by The Pair.)_**
[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://github.com/timwuhaotian/the-pair/releases)
[](https://github.com/timwuhaotian/the-pair/stargazers)
[](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) | [](https://twitter.com/intent/tweet?text=Check%20out%20The%20Pair%20%E2%80%94%20Two%20AI%20agents%20cross-check%20each%20other%27s%20code&url=https://github.com/timwuhaotian/the-pair)
**macOS** โข **Windows** โข **Linux** | [**โฌ Download**](https://github.com/timwuhaotian/the-pair/releases) โข [**CLI**](https://github.com/timwuhaotian/pair-code) โข [**๐ Website**](https://apps.timwuhaotian.dev/)
_Watch Mentor and Executor agents collaborate in real-time_
[](docs/assets/launch-10s.mp4)
๐ฌ **The 10-second launch film, autoplaying muted** โ [watch the 4K60 original with sound](docs/assets/launch-10s.mp4)
---
Table of Contents
- [Overview](#overview) โ what The Pair is and why dual agents reduce AI hallucinations
- [AI Search Summary](#ai-search-summary) โ concise product facts for search and AI citation
- [Why The Pair?](#why-the-pair) โ comparison vs. Cursor, Copilot, and single-agent tools
- [Choose Your Interface](#choose-your-interface) โ desktop app or terminal CLI
- [Features](#features)
- [Screenshots](#screenshots)
- [Installation](#installation) โ macOS, Windows, Linux
- [Quick Start](#quick-start) โ install a provider CLI and create your first pair
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Development](#development)
- [FAQ](#faq)
## Overview
**The Pair is a free, open-source desktop app that runs two AI coding agents โ a read-only _Mentor_ that plans and reviews, and an _Executor_ that writes code and runs commands โ which cross-check each other's work to catch AI hallucinations before they reach your codebase.** It runs locally on macOS, Windows, and Linux, and is model-agnostic: mix and match ten provider CLIs โ opencode, Claude Code, Codex, Antigravity (Gemini), Kimi Code, Pi, Kiro, Aider, Grok Build, and Muse Code โ in any combination (plus local models via Ollama).
**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.
### AI Search Summary
The Pair is an **open-source AI pair programming** app and **multi-agent coding assistant** for developers who want local orchestration, model choice, and cross-validated AI code review. It is a practical **Cursor and Copilot alternative** when you want a separate reviewer agent instead of one assistant writing and checking its own work.
For AI crawlers and search systems, see [llms.txt](llms.txt), the reusable [SoftwareApplication JSON-LD](docs/seo/software-application.schema.json), and the [FAQPage JSON-LD](docs/seo/faq.schema.json).
> **๐ก Common Questions**
>
> **How is this different from single-agent tools?** โ One model writing _and_ reviewing its own code can miss its own mistakes. The Pair's Mentor independently reviews everything the Executor produces.
>
> **Which models work?** โ Any model reachable through opencode, Claude Code, Codex, Antigravity, Kimi Code, Pi, Kiro, Aider, Grok Build, or Muse Code โ including GPT, Claude, Gemini, Grok, GLM, Qwen, Kimi, MiniMax, and DeepSeek, plus local models via Ollama. Mix and match providers freely (e.g., Claude as Mentor + Codex as Executor).
>
> **Does it need internet?** โ The app runs locally. Only model API calls need connectivity (or use Ollama for fully offline sessions).
### Why The Pair?
| Capability | The Pair | Cursor / Copilot | Claude Code (solo) |
| ------------------------------- | ------------------------- | ------------------- | ------------------- |
| Cross-validation between agents | โ Two independent agents | โ Single agent | โ Single agent |
| Dedicated review role | โ Mentor (read-only) | โ Self-review only | โ Self-review only |
| Multi-provider support | โ 10 provider CLIs | โ Locked to one | โ Claude only |
| Local orchestration | โ Fully local | โ Cloud-dependent | โ Cloud-dependent |
| Session recovery | โ Full snapshot restore | โ | โ |
| Open source | โ Apache 2.0 | โ Proprietary | โ Proprietary |
### Key Benefits
- **Dual-Model Cross-Validation** โ Two models check each other's work, dramatically reducing code hallucinations
- **Cognitive Transparency** โ Live intent chips and tool call visualization show exactly what each agent is doing
- **Unified Pair Console** โ Single scrollable feed merges conversation, timeline, and activity into one cohesive view
- **Automated Collaboration** โ Agents work together without constant human intervention
- **Smart Coordination** โ Structured handoff prompts, quality gates, and smart pauses keep iterations focused
- **Real-Time Monitoring** โ CPU/memory per agent with live activity tracking and stall detection
- **Activity View** โ Attention items, running pairs, resource load, and recent events across all pairs at a glance
- **Git Integration** โ Automatic tracking of all file changes plus inline diff viewer for any modified file
- **Human Oversight** โ Step in at any time to pause, adjust, reassign, or resume after the iteration limit
- **Session Recovery** โ Resume interrupted sessions with full conversation history and turn state restored
- **Guided First Run** โ Empty-state setup flow with model configuration and directory selection
- **i18n Support** โ English, ็ฎไฝไธญๆ, ๆฅๆฌ่ช, and ํ๊ตญ์ด with persisted language preference
- **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
---
## Choose Your Interface
The Pair is the desktop app for visual monitoring and hands-on oversight. **CLI** users can install [Pair Code](https://github.com/timwuhaotian/pair-code), the terminal edition of The Pair, from [npm](https://www.npmjs.com/package/pair-code) with `npm install -g pair-code`.
| Interface | Best for | Start here |
| ----------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Desktop** | Visual monitoring, installers, long-running pairs | [Download The Pair](https://github.com/timwuhaotian/the-pair/releases) |
| **CLI** | Terminal-native workflows, scripts, SSH sessions | [Pair Code](https://github.com/timwuhaotian/pair-code) or [npm package](https://www.npmjs.com/package/pair-code) |
Both use the same Mentor + Executor idea: one agent plans and reviews, the other writes and verifies.
---
## Features
- **Dual-Agent Architecture** โ Separation of planning (Mentor) and execution (Executor)
- **Unified Pair Console** โ Conversation, timeline, terminal events, and activity in one scrollable feed
- **Cognitive Event Stream** โ Intent chips, reasoning steps, and tool call status surfaced per turn
- **Smart Coordination** โ Structured handoff prompts, quality gates, and smart-pause logic for healthier iterations
- **Iteration Budgeting** โ Flat 20-turn default with human-in-the-loop pause when the budget is reached
- **Full Automation Mode** โ Agents work autonomously with workspace-scoped permissions
- **Real-Time Activity Tracking** โ Live status with stalled-activity detection after 60s of inactivity
- **Resource Monitoring** โ CPU and memory usage per agent, updated every second
- **Git Change Tracking** โ Detect modified/added/deleted files, with click-through unified diff viewer
- **Sound Cues** โ Contextual finish, pause, and error chimes with global mute toggle
- **Conversation History** โ Full transcript of all agent interactions, exportable as a run report
- **Local Orchestration** โ Runs the app and agent coordination locally; model calls depend on your selected provider or local model
- **Multi-Provider** โ Works with ten provider CLIs: opencode, Claude Code, Codex, Antigravity (Gemini), Kimi Code, Pi, Kiro, Aider, Grok Build, and Muse Code
- **Reasoning Controls** โ Adjust thinking effort per agent role (low/medium/high)
- **Token Tracking** โ Real-time per-turn input/output token usage in timeline, turn cards, and run reports
- **Skill System** โ Attach project-specific skill files to guide agent behavior
- **Global Shortcuts** โ Platform-agnostic shortcuts for new pair, pair settings, focus console, and mute
- **Command Palette** โ Fuzzy finder (โK) over every action with direct pair jump
- **Native Menu Bar** โ Full App / File / Edit / View / Window / Help menus with keyboard shortcuts
- **Pairs Hub** โ Workspace-grouped pair cards with status, quick actions, and a recovery banner
- **Inspector Panel** โ Collapsible sections for models, run state, resources, files, history, and timeline
- **Auto-Update** โ In-app update checking with one-click install
---
## Screenshots
Pairs Hub
Pair Detail โ Review
Command Palette
Live Execution
---
## 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.tar.gz` (extract, then run the 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://claude.ai/download), [Codex](https://github.com/openai/codex), [Antigravity](https://github.com/google-antigravity/antigravity-cli), [Kimi Code](https://github.com/MoonshotAI/kimi-code), [Pi](https://pi.dev), [Kiro](https://kiro.dev/downloads), [Aider](https://aider.chat), [Grok Build](https://github.com/xai-org/grok-build), or [Muse Code](https://dev.meta.ai/docs/muse-code).
### 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`
- **Antigravity** โ `agy install` (see [Antigravity](https://github.com/google-antigravity/antigravity-cli) for setup)
- **Kimi Code** โ `curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash` (see [Kimi Code](https://github.com/MoonshotAI/kimi-code) for setup)
- **Pi** โ see [pi.dev](https://pi.dev) for installation and sign-in
- **Kiro** โ download from [kiro.dev/downloads](https://kiro.dev/downloads), then `kiro-cli login`
- **Aider** โ `python -m pip install -U aider-chat` (see [aider.chat](https://aider.chat) for setup)
- **Grok Build** โ see [xai-org/grok-build](https://github.com/xai-org/grok-build), then `grok login`
- **Muse Code** โ see [Muse Code docs](https://dev.meta.ai/docs/muse-code), then `muse login`
### 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, Antigravity (`agy`), Kimi Code (`kimi`), Pi, Kiro, Aider, Grok Build, and Muse Code 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`
Claude Code, Codex, Antigravity, Kimi Code, Pi, Kiro, Aider, Grok Build, and Muse Code 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) โ
โ โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ โ
โ โ Pairs Hub โ PairConsole โ Inspector โ โ
โ โ + Activity โ (Unified) โ (Collapsible) โ โ
โ โ + Insights โ โ โ โ
โ โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโ โ
โ โ Tauri IPC โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Backend (Rust) โ
โ โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ โ
โ โ PairManager โMessageBroker โ ProcessSpawner โ โ
โ โ (Lifecycle) โ(State Machine)โ(Multi-Provider) โ โ
โ โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโ โ
โ โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ โ
โ โContextBridge โ QualityGate โ SmartPause โ โ
โ โ (Handoffs) โ (Verdict) โ (Coordination) โ โ
โ โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโ โ
โ โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ โ
โ โ Git Tracker โ Worktrees โ Session Snapshot โ โ
โ โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโ โ
โ โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ โ
โ โResource Mon. โ Acceptance โ Report Generator โ โ
โ โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโดโโโโโโโโโโโโโโ
โ โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ AI Provider CLIsโ โ Git Repo โ
โ Claude, Codex, โ โ (Workspace) โ
โ Gemini, Kimiโฆ โ โโโโโโโโโโโโโโโโโโโ
โ (10 providers) โ
โโโโโโโโโโโโโโโโโโโ
```
### Agent Workflow
```
Start โ Initialize & Baseline โ Mentoring โ Executing โ Reviewing
โ
Done? โโYesโ Finished
โ
No
โ
Iteration limit? โโYesโ Paused (Awaiting Human Review)
โ
No
โ
(loop back to Mentoring)
```
Pairs are capped at a flat 20-iteration default and pause for human review on hitting the budget โ rather than running unbounded โ so you can continue, reassign, or finish from the console.
---
## 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: Is The Pair free and open source?**
A: Yes. The Pair is fully open source under the Apache 2.0 license and free to download for macOS, Windows, and Linux. You only pay for your own AI provider usage โ or run local models with [Ollama](https://ollama.com) for zero API cost.
**Q: Is The Pair an alternative to Cursor, GitHub Copilot, or Aider?**
A: Yes, with a different approach. Cursor, Copilot, and Aider drive a single agent. The Pair runs two independent agents โ a Mentor (read-only reviewer) and an Executor (code writer) โ that cross-check each other, so mistakes get caught by a second model instead of shipped. It's a local-first, open-source alternative, and it's model-agnostic: pair any two of its ten provider CLIs โ opencode, Claude Code, Codex, Antigravity, Kimi Code, Pi, Kiro, Aider, Grok Build, or Muse Code.
**Q: Which operating systems does The Pair support?**
A: The Pair is a native desktop app for **macOS, Windows, and Linux**, built with Tauri 2 (Rust backend + React frontend).
**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 ten provider CLIs out of the box: **opencode** (any compatible model), **Claude Code**, **OpenAI Codex**, **Antigravity** (Gemini), **Kimi Code**, **Pi**, **Kiro**, **Aider**, **Grok Build**, and **Muse Code**. All 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 the other provider CLIs, simply install the 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, Gemini, Grok, and more). 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 with full input/output breakdown. Live counts appear inline in the unified Pair Console, the timeline, and the exported run report so you can monitor spend as agents work.
**Q: Can I see what the agent is actually doing?**
A: Yes. Each turn renders a stream of **cognitive events** โ intent chips (analyzing / writing / verifying / reviewing), reasoning steps, and tool call status (pending / running / completed / error) โ so you can follow the agent's logic without parsing raw output.
**Q: What happens if an agent gets stuck in a loop?**
A: The Pair caps each run at a flat 20-iteration default. When the limit is reached, the pair pauses into **Awaiting Human Review** so you can continue, reassign, or finish. A per-turn step-cycle guard also kills runaway agent processes to prevent CPU exhaustion.
**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.
---
[โฌ Download](https://github.com/timwuhaotian/the-pair/releases) โข [๐ Website](https://apps.timwuhaotian.dev/) โข [๐ฌ Discussions](https://github.com/timwuhaotian/the-pair/discussions) โข [๐ Report a bug](https://github.com/timwuhaotian/the-pair/issues)
Built with โค๏ธ by [timwuhaotian](https://github.com/timwuhaotian)
**[โญ Star this repo](https://github.com/timwuhaotian/the-pair)** if you find it helpful! | [๐ข Share on X](https://twitter.com/intent/tweet?text=Check%20out%20The%20Pair%20%E2%80%94%20Two%20AI%20agents%20cross-check%20each%20other%27s%20code&url=https://github.com/timwuhaotian/the-pair) | [๐ฌ Discuss](https://github.com/timwuhaotian/the-pair/discussions)
The Pair โ open-source AI pair programming ยท dual-agent AI code review ยท multi-agent coding assistant ยท Cursor & Copilot alternative ยท works with Claude Code, Codex, Antigravity, Kimi Code, Pi, Kiro, Aider, Grok Build, Muse Code, and opencode on macOS, Windows, and Linux.
Pair Detail โ Review
Command Palette
Live Execution
---
## 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.tar.gz` (extract, then run the 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://claude.ai/download), [Codex](https://github.com/openai/codex), [Antigravity](https://github.com/google-antigravity/antigravity-cli), [Kimi Code](https://github.com/MoonshotAI/kimi-code), [Pi](https://pi.dev), [Kiro](https://kiro.dev/downloads), [Aider](https://aider.chat), [Grok Build](https://github.com/xai-org/grok-build), or [Muse Code](https://dev.meta.ai/docs/muse-code).
### 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`
- **Antigravity** โ `agy install` (see [Antigravity](https://github.com/google-antigravity/antigravity-cli) for setup)
- **Kimi Code** โ `curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash` (see [Kimi Code](https://github.com/MoonshotAI/kimi-code) for setup)
- **Pi** โ see [pi.dev](https://pi.dev) for installation and sign-in
- **Kiro** โ download from [kiro.dev/downloads](https://kiro.dev/downloads), then `kiro-cli login`
- **Aider** โ `python -m pip install -U aider-chat` (see [aider.chat](https://aider.chat) for setup)
- **Grok Build** โ see [xai-org/grok-build](https://github.com/xai-org/grok-build), then `grok login`
- **Muse Code** โ see [Muse Code docs](https://dev.meta.ai/docs/muse-code), then `muse login`
### 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, Antigravity (`agy`), Kimi Code (`kimi`), Pi, Kiro, Aider, Grok Build, and Muse Code 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`
Claude Code, Codex, Antigravity, Kimi Code, Pi, Kiro, Aider, Grok Build, and Muse Code are detected from their local CLI install and account state.
### Pair Runtime
Each pair maintains its own runtime configuration in `.pair/runtime/