AGPair 1.0

中文说明 | Getting Started | Command Reference

AGPair 1.0 is a local task lifecycle and evidence layer that lets Codex or Claude Code delegate bounded work to external CLI agents, then wait, verify, adopt, retry, or fall back with structured evidence.

Controllers plan and verify. AGPair dispatches external CLI executors, persists task state, waits cheaply, validates structured receipts, and supports state-aware retry when an executor blocks.

AGPair 1.0 Model

• Common first external executors: grok-cli and antigravity-cli; multiple external lanes may run when their prompts, scopes, or acceptance criteria are distinct
• Quality escalation: claude-code
• Fallback external Codex CLI worker: codex
• Native Codex / Claude Code subagents: review/helper/fallback lanes when they materially improve verification or recovery

Controller-aware routing suppresses self-executors by default: Codex controllers do not choose AGPair-managed external codex, and Claude Code controllers do not choose AGPair-managed external claude-code, unless --allow-self-executor is explicitly used.

Operationally, codex is the external Codex CLI worker for Claude Code controllers. Codex controllers should use native Codex subagents as their fallback/review lane. claude-code is the external Claude Code worker for Codex controllers. Claude Code controllers should use native Claude Code subagents as their fallback/review lane.

Historical executor records remain inspectable for compatibility. New dispatch uses the active executor ids above.

For non-trivial work, the controller should prefer useful breadth over a single default lane: use grok-cli and antigravity-cli as peer first lanes, add a second grok-cli or claude-code when their output can improve confidence, and use native subagents as narrow reviewers/helpers when they add controller-side value. Mutating parallel lanes must use isolated worktrees or disjoint scopes.

Default executor environments are managed-natural for every active external CLI executor: AGPair manages task boundaries, receipts, logs, status, retry, and verification evidence, while the external CLI keeps its normal skills, MCP, memory, plugins, and provider config. Controller suppression handles self-executor avoidance; executor launch configuration is not special-cased.

AGPair-started executor, probe, smoke, and retry processes are marked internal, so installed Codex/Claude hooks no-op for those processes. Normal controller sessions still receive external-first guidance.

Quick Start

git clone https://github.com/logicrw/agpair.git
cd agpair
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e '.[dev]'

Make the CLI available to your controller:

ln -sf "$PWD/.venv/bin/agpair" ~/.local/bin/agpair
agpair doctor
agpair doctor --fresh --repo-path /path/to/repo

If Antigravity CLI print mode times out with the current default model, select a known-good Antigravity model for AGPair-launched workers. The value below is an Antigravity model label, not the retired Gemini CLI executor:

export AGPAIR_ANTIGRAVITY_MODEL="Gemini 3.1 Pro (Low)"

Start a task. task start waits by default: