# One Agent Harness (`harness`)

**Universal Cross-Agent Context Bridge for Claude Code, Antigravity, OpenAI Codex, and Grok Build CLI.**

[![CI (Linux · macOS · Windows)](https://github.com/ajmainapon/one-agent-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/ajmainapon/one-agent-harness/actions/workflows/ci.yml)
[![Platform: Linux | macOS | Windows](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-blue)](#installation-linux--macos--windows)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-3776ab)](#installation-linux--macos--windows)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20(stdlib%20only)-success)](#architecture)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

Never re-explain your problem or manually copy-paste context when switching AI coding tools. **One Agent Harness** extracts your exact verbatim conversation turns, active implementation plans, task lists, modified files, terminal errors, and uncommitted git state from any agent and injects or hands them off to any other agent in one command.

---

## Supported Platforms & Operating Systems

| AI Coding Agent | Session & Artifact Storage | Native Session Injection | MCP & `/handoff` / `$handoff` |
| :--- | :--- | :---: | :---: |
| **Claude Code** | `~/.claude/projects/` & `~/.claude/plans/` | ✅ `claude --resume <id>` | ✅ `/handoff` |
| **Antigravity** | `~/.gemini/antigravity/brain/` & `conversation_summaries.db` | ✅ `agy <workspace>` | ✅ `/handoff` |
| **OpenAI Codex** | `~/.codex/sessions/`, `session_index.jsonl`, & `state_5.sqlite` | ✅ `codex resume <id>` | ✅ `$handoff` |
| **Grok Build CLI** | `~/.grok/sessions/` | ✅ `grok ...` | ✅ `/handoff` |

Works out of the box on **Linux** (X11, Wayland, WSL2, SSH/OSC 52), **macOS**, and **Windows** (PowerShell, CMD, Windows Terminal, Git Bash) with **zero external runtime dependencies** (100% Python 3.9+ standard library).

---

## Installation (Linux · macOS · Windows)

### Option 1: One-Line Bootstrap Installer (Recommended)

**Linux & macOS (bash / zsh / sh):**
```bash
git clone https://github.com/ajmainapon/one-agent-harness.git
cd one-agent-harness
chmod +x install.sh && ./install.sh
```

**Windows (PowerShell):**
```powershell
git clone https://github.com/ajmainapon/one-agent-harness.git
cd one-agent-harness
.\install.ps1
```

### Option 2: Standard Python Package (`pipx`, `uv`, or `pip`)

```bash
# Install globally with pipx or uv (Linux, macOS, Windows)
pipx install .
# or: uv tool install .
# or: pip install -e .

# Register MCP server + /handoff & $handoff skills across all 4 agents
harness install

# Start background Auto-Sync Watcher daemon
harness watch --daemon
```

---

## Usage Guide

### 1. Inside Any Agent Chat (`/handoff` & `$handoff`)

No need to remember session UUIDs! Pass a **session number (`1`, `2`, `3`)**, **project name**, **keyword**, or **agent name**:

- **In Claude Code, Antigravity, or Grok Build CLI**:
  - `/handoff` *(loads the latest active session)*
  - `/handoff my-project` *(fuzzy-matches your project or session title)*
  - `/handoff 2` *(loads session `#2` from the recent sessions list)*
  - `/handoff claude` *(loads your latest Claude Code session)*
- **In OpenAI Codex (`v0.162.1+`)**:
  - `$handoff`, `$handoff my-project`, or `$handoff 2` *(Codex reserves `/` for built-in TUI commands and uses `$` for skills)*.

---

### 2. Zero-Flag Terminal Shorthands

Run `harness` (with no arguments) to see the colorized dashboard with numbered sessions (`#1`, `#2`, `#3`, ...):

```bash
# View colorized dashboard of all recent sessions across all 4 platforms
harness

# Interactive menu — pick a session & action by number
harness pick

# 1-command switch into an agent (accepts session number, project keyword, or agent alias)
harness codex                 # Inject latest session into Codex & launch
harness codex 3               # Inject session #3 into Codex & launch
harness codex "auth refactor" # Inject session matching "auth refactor" into Codex & launch
harness claude 2              # Inject session #2 into Claude Code & launch
harness agy 1                 # Inject session #1 into Antigravity

# Copy any session's full handoff bundle to system clipboard
harness copy                  # Copy #1 latest session
harness copy 2                # Copy session #2
harness copy "auth"           # Copy session matching "auth"

# Read context without writing files or changing your clipboard
harness handoff "auth refactor" --read-only

# Preview a switch without changing files or clipboard
harness codex "auth refactor" --dry-run

# Search across all 4 platforms' transcripts & touched files
harness search "keyword"
```

---

### 3. Selecting the Right Session

Use the same filters when listing and selecting sessions:

```bash
harness status --agent claude --cwd /path/to/project
harness handoff 1 --from claude --cwd /path/to/project
```

Numbers refer to the filtered list and may change when new sessions become active. Use `--session <session-id>` for a stable selection. A query or workspace with no match reports an error instead of loading an unrelated project. With no filters, the latest substantive session is selected.

### 4. Saving and Recovery

- Handoffs save to `.harness/LIVE_CONTEXT.md` and `.harness/bundle.json` in the workspace. If the workspace cannot be written, Harness reports the fallback location under `~/.harness`.
- If neither location is writable, CLI and MCP still return the extracted context with a warning. `--read-only` prints context without attempting a save or clipboard change.
- Use `--no-update-agent-md` to save a handoff without updating existing `AGENTS.md` or `CLAUDE.md` pointers. Use `--no-copy` to leave your clipboard unchanged.
- The watcher syncs the latest session in each workspace and retries failed saves. One unavailable workspace does not block the others.
- User prompts are preserved in full within the selected turns. Long assistant responses and artifacts may still be shortened. Claude plans are included only when the session explicitly read or modified them.
- Installation validates existing JSON settings before making changes and backs up every existing MCP JSON config, including Grok. If a config is malformed, repair the indicated file and rerun `harness install`; the original is left unchanged.

### 5. Environment Variable Overrides

All storage paths default to standard user home directories on Linux, macOS, and Windows (`~` / `%USERPROFILE%`), and can be customized via environment variables:

| Environment Variable | Default Path | Description |
| :--- | :--- | :--- |
| `HARNESS_CLAUDE_HOME` / `CLAUDE_CONFIG_DIR` | `~/.claude` | Claude Code data directory |
| `HARNESS_AGY_HOME` / `ANTIGRAVITY_HOME` | `~/.gemini/antigravity` | Antigravity data directory |
| `HARNESS_CODEX_HOME` / `CODEX_HOME` | `~/.codex` | OpenAI Codex data directory |
| `HARNESS_GROK_HOME` / `GROK_HOME` | `~/.grok` | Grok Build CLI data directory |
| `HARNESS_HOME` | `~/.harness` | One Agent Harness state, logs, and checkpoints |

---

## Running the Test Suite

```bash
python3 -m unittest discover -s tests -v
```

## License

MIT License — see [LICENSE](LICENSE).