agpair is a lightweight CLI that connects any AI coding agent to an Antigravity executor — so you can dispatch coding tasks, track their progress, and review results without leaving the conversation.
Works with Codex (CLI & Desktop), Claude Code, and any tool that can run shell commands.
When you use an AI coding agent + Antigravity together, there is a mechanical gap between "I told my agent what to do" and "Antigravity finished executing it." That gap includes:
- dispatching the task over
agent-bus - tracking which task maps to which executor session
- collecting receipts (
ACK,EVIDENCE_PACK,BLOCKED,COMMITTED) - detecting stuck tasks
- providing a clean continue / approve / reject / retry flow
agpair fills that gap. It is a tool belt for your AI agent — and a manual fallback for you when you need direct control.
- Not a semantic controller — your AI agent stays in charge of decisions.
- Not a fully autonomous reviewer — you (or your AI agent) choose the next action.
- Not a zero-dependency runtime — it still depends on
agent-bus, Antigravity itself, and the bundled companion extension.
| Requirement | Notes |
|---|---|
| macOS | Primary tested platform. Linux is untested but may work. |
| Python 3.12+ | For the agpair CLI |
| Node.js 18+ | For building the companion extension |
agent-bus |
Shared message bus CLI — see below |
| Antigravity IDE | The companion extension runs inside it |
agent-bus is the shared local message bus that agpair uses to dispatch tasks and receive receipts between your AI agent (desktop side) and Antigravity (code executor). It must be available on your PATH.
Note:
agent-busis a local CLI tool distributed as part of the Antigravity tooling environment. If you are using an Antigravity-managed setup, it should already be available. If not, install theagent-busbinary provided by your Antigravity distribution and ensure it is on yourPATH. There is currently no standalone public package foragent-bus— it is expected to be present in environments where Antigravity is installed.
The companion extension (companion-extension/) is a VS Code-compatible extension that runs inside the Antigravity IDE. The antigravity --install-extension command used below is the Antigravity IDE's CLI for sideloading .vsix extensions, analogous to code --install-extension in VS Code.
git clone https://github.com/logicrw/agpair.git && cd agpair
python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install -e '.[dev]'
# Build and install the companion extension
cd companion-extension && npm install && npm run package
antigravity --install-extension agpair-companion-extension-*.vsix
cd ..agpair doctor --repo-path /path/to/your/projectYou want agent_bus_available=true, desktop_reader_conflict=false, and repo_bridge_session_ready=true. See the Getting Started guide for details and troubleshooting.
agpair daemon start
agpair task start --repo-path /path/to/your/project \
--body "Goal: fix the failing smoke test and return EVIDENCE_PACK."By default, task start waits until the task reaches a terminal phase. Add --no-wait for fire-and-forget.
For the full step-by-step walkthrough, see the detailed guides below.
┌───────────────┐ agpair CLI ┌─────────────┐ agent-bus ┌──────────────────┐
│ │ ─────────────────▶ │ │ ───────────────▶ │ Antigravity │
│ AI Agent │ task start/wait │ agpair │ dispatch/recv │ (executor) │
│ (chat UI) │ ◀───────────────── │ daemon │ ◀─────────────── │ │
│ │ status/receipts │ │ receipts/ack │ companion ext │
└───────────────┘ └──────┬──────┘ └──────────────────┘
│
SQLite DB
(tasks, receipts,
journals)
Data flow: AI Agent → agpair task start → daemon dispatches via agent-bus → Antigravity executes → companion extension writes receipts → daemon ingests receipts → AI Agent reads status.
In normal use, you do not need to manually type every agpair command.
The intended workflow is:
- You tell your AI agent what you want in natural language
- Your AI agent calls
agpaircommands behind the scenes - Antigravity executes the task
agpairkeeps the mechanical path stable
The CLI is still valuable for manual inspection, debugging, retry, and recovery when your AI agent is not available.
This repo ships a reusable skill at skills/agpair/SKILL.md that teaches your AI tool how to use agpair correctly — preflight checks, blocking wait discipline, and semantic action flow.
Install for your tool of choice:
# Codex
mkdir -p ~/.codex/skills
ln -sfn "$PWD/skills/agpair" ~/.codex/skills/agpair
# Claude Code
mkdir -p ~/.claude/skills
ln -sfn "$PWD/skills/agpair" ~/.claude/skills/agpairAfter installing, restart or open a new window. Say use agpair in your prompt to trigger it explicitly.
Other tools (Cursor, Aider, OpenCode, etc.): copy the content of
skills/agpair/SKILL.mdinto your tool's instruction file (e.g..cursorrules,AGENTS.md).
agpair v1.0 bridges AI coding agents to Antigravity executors.
What already works:
agent-bus-based task dispatch with auto-wait- Local SQLite-backed task / receipt / journal state
- Continuation flow:
continue,approve,reject,retry,abandon - Standalone
task waitwith configurable timeout/interval - Daemon with receipt ingestion, session continuity, and stuck detection
doctorpreflight checks (local health, desktop conflicts, bridge health)
What is explicitly not in scope:
- Replacing your AI agent as the semantic controller
- Hiding all operational boundaries
| Document | Description |
|---|---|
| Getting Started | Step-by-step beginner guide |
| Command Reference | Full CLI reference |
agpair/
├── agpair/ # Python CLI package
├── companion-extension/ # Bundled Antigravity companion (TypeScript)
│ ├── src/ # Extension source
│ ├── package.json
│ └── esbuild.js
├── skills/
│ └── agpair/ # Optional agent skill package
├── tests/ # Python integration tests
├── docs/ # Documentation
└── pyproject.toml
This is a single self-contained repo. No external checkout is needed.
agpair consumes code -> desktop receipts. If another desktop-side watcher is already claiming the same receipts, agpair doctor will report desktop_reader_conflict=true and the daemon will refuse to start. Stop the other watcher first.
You can open multiple agent windows, but avoid having two windows send continue / approve / reject / retry for the same TASK_ID. Rule: one active task → one main agent window.
The daemon only handles mechanical work (receipts, continuity, stuck detection). It does not review code or make semantic decisions.
Run agpair doctor when starting a new task, switching repos, restarting the daemon, or investigating a stuck task. You do not need it before every status or logs check.
The companion extension's HTTP bridge listens on 127.0.0.1 only. By default, the bridge is secured with an auto-generated bearer token stored in VS Code's SecretStorage. Mutating endpoints (/run_task, /continue_task, /write_receipt, etc.) require a valid Authorization: Bearer <token> header; read-only endpoints (/health, /task_status) remain accessible without authentication so that agpair doctor works out of the box.
The token is generated automatically on first activation and persisted securely — no manual configuration is needed for normal use. You can override the token via the antigravityCompanion.bridgeToken IDE setting. For local debugging only, you can disable auth entirely by setting antigravityCompanion.bridgeInsecure = true — this is not recommended for normal use as it allows any local process to call mutating bridge endpoints. Request bodies are limited to 1 MiB.
# Install
python3 -m agpair.tools.install_agpair_daemon_launchd install \
--agpair-home ~/.agpair
# Check
python3 -m agpair.tools.install_agpair_daemon_launchd status
# Uninstall
python3 -m agpair.tools.install_agpair_daemon_launchd uninstallAnother desktop watcher is consuming the same receipts. Stop it, then start agpair daemon.
The Antigravity window for this repo is not ready. Confirm the correct repo is open in Antigravity, reload/restart the window, then re-run agpair doctor --repo-path ....
The current attempt did not complete. Run agpair task logs <TASK_ID> to inspect, then decide whether to continue the same session or retry with a fresh one.
MIT