agent-companion

Agent Companion

Agent Companion is a delegation plugin for coding agents built around one public contract:

Come with any harness and attach any companion of your choice to it.

A harness is the parent coding-agent surface you already work in. Supported now: Claude Code and Codex CLI.

A companion is the downstream agent runtime that receives delegated work. Supported now: OpenCode and GitHub Copilot CLI.

Today, each delegated send runs on one explicitly selected or configured companion. The roadmap is one-to-many: connect multiple companion profiles at once, assign each profile strengths, and let the harness ask for the strength instead of a concrete runtime.

The product posture is deliberately companion-neutral:

• Bring your harness. Install the Claude Code surface, the Codex CLI surface, or both.
• Attach your companion. Choose opencode or copilot on each send, or persist one bridge default.
• Keep the parent clean. Main Claude and main Codex never see the bridge MCP server directly.
• Use one public surface. The subagent owns the generic agent_* tools: agent_send, agent_wait, agent_status, agent_reply, and agent_cancel.
• Avoid silent behavior. If no target is passed or configured, agent_send returns TARGET_UNCONFIGURED with onboarding guidance.
• Route by strengths next. Future companion profiles can advertise strengths such as reviewer or web_researcher; harnesses should consume those strengths without hard-coding a vendor/runtime choice.

Implementation note: today the CLI and MCP schema still use host for harness selection and target for companion selection. Those names are stable public flags for the MVP.

Current implementation status lives in docs/MVP_TRACKER.md. Architecture details live in docs/ARCHITECTURE.md. Public release gates live in docs/RELEASE_READINESS.md. The delivered onboarding design record lives in docs/ONBOARDING_HANDOFF.md.

What It Does

Agent Companion turns a natural-language delegation request into a background job owned by an isolated subagent:

1. The parent harness decides to spawn the agent-companion subagent.
2. The subagent calls its private agent-bridge MCP server.
3. The bridge resolves the selected companion, creates a job, and returns quickly.
4. The companion runtime runs the work in the requested cwd.
5. The bridge writes progress digests and emits one terminal completion event.
6. The subagent reports the result back to the harness.

That means token-heavy work can happen outside the parent's main context while still giving the parent a structured result, status checks, cancellation, and digest links.

Supported Harnesses

Harness	Install selector	Status
Claude Code	--host claude	implemented
Codex CLI	--host codex	implemented

Future harnesses should add a host install surface, subagent template, hook or completion delivery path, and session-routing adapter without changing the companion runtime boundary.

Supported Companions

Companion	Runtime	Send	Wait	Status	Cancel	Reply	Restart resume
OpenCode (cli, default)	opencode run --format json --dir <cwd>	yes	yes	yes	yes	no	no
OpenCode (server)	opencode serve over HTTP	yes	yes	yes	yes	yes	yes
GitHub Copilot CLI	ACP daemon path	yes	yes	yes	yes	yes	yes, with ACP

Notes:

• OpenCode ships two adapters, selected by OPENCODE_RUNTIME_ADAPTER:
  • cli (default) is the single-shot opencode run adapter.
  • server drives a long-lived opencode serve HTTP server and adds in-flight reply/re-steer, restart resume, and streamed event digests. One shared server roots each job at its own cwd via the ?directory= query param. The server is detached and survives bridge restarts (like the Copilot daemon) so a respawned bridge reattaches instead of re-spawning; set AGENT_COMPANION_OPENCODE_MODEL=provider/model to pin a model, otherwise the server's configured default is used.
  • Server-mode binds 127.0.0.1 and is unsecured; permission handling follows OpenCode's own config (the AGENT_COMPANION_OPENCODE_PERMISSION_MODE=skip flag applies to the cli adapter only).
• Copilot keeps /fleet parallel orchestration. parallel: "auto" can prepend /fleet for broad Copilot tasks; OpenCode remains single-job.
• Goose and Aider are tracked as future companion adapter candidates.

Strength Routing Roadmap

The MVP has a one-to-one routing contract: one agent_send resolves to one companion target, either from the target argument or the configured default-target.