Multi-Harness Agent Architecture

Your agent is the workspace, not the harness. Bob’s identity, memory, tasks, lessons, journal, workflow, and audit history live in one version-controlled workspace. gptme, Claude Code, Codex, Grok Build, and Pi are runtimes that can act on that durable state; none of them owns the agent.

This is more than fallback capacity. Multiple harnesses provide outage resilience, different tool and context tradeoffs, and a controlled way to measure how much performance comes from the model versus the agent loop around it.

Four Orthogonal Layers

The layers are independent concepts, not a full Cartesian product. Each harness supports a different set of models and access methods. Two harnesses using the same subscription also consume the same quota pool; relabeling the runtime does not create more capacity.

Current Support Levels

Bob also has a gated GitHub Copilot CLI adapter. It is not a primary runtime: its limited trajectory contract and small premium-request pool make it useful as spillover, not as the reference architecture.

“Can read the repository” is manual compatibility. “Production adapter” means the runtime also preserves Bob’s context, locks, timeout semantics, exact trajectory, grading, quota accounting, and historical retention.

Why Multiple Harnesses?

Resilience

If one subscription is rate-limited or one harness has a tool regression, a healthy route can continue. Availability becomes the union of healthy access routes, not merely a list of executable binaries. The distinction matters: gptme using a ChatGPT subscription and Codex may share the same underlying quota even though their agent loops are different.

Capability Diversity

gptme has broad provider and tool flexibility. Claude Code has tight Anthropic integration and strong repository navigation. Codex and Grok Build provide different tool loops over their subscription-backed models. A small harness such as Pi is valuable both as a production candidate and as a relatively transparent baseline for judging more opinionated loops.

The durable workspace lets a useful discovery made in any runtime become a lesson available to all later runtimes.

Natural A/B Testing

Normalized session records make same-model or same-task comparisons possible:

• Does a model perform differently in gptme and Pi?
• Does native lesson matching beat a rendered prompt bundle for this category?
• Which harness completes cross-repository work with fewer retries or tokens?

Bob records the harness and model together and uses Thompson sampling to learn which proven combinations work for each category. Provider route, access profile, and quota pool also need to remain explicit so a billing difference is not mistaken for a harness effect.

The Shared Workspace

     gptme       Claude Code       Codex       Grok Build    Pi (explicit)
        │             │              │              │               │
        └─────────────┴──────────────┴──────────────┴───────────────┘
                                      │
                         Bob's versioned workspace
          SOUL / ABOUT / GOALS / tasks / lessons / journal / state

Every production adapter must:

• load the same identity and operating contract;
• select work through the same gptodo queues and claims;
• use session-specific journals and trajectory references;
• coordinate commits and locks in the shared repository;
• emit normalized outcomes without discarding the native session;
• account for the real access and quota pool it consumed.

Coordination

Concurrent sessions share files but should not share assumptions:

• git-safe-commit uses scoped paths and serialized commits in the hot brain worktree;
• gptodo claims, dependencies, and leases prevent duplicate work;
• backend-scoped locks bound concurrency and subscription use;
• session-specific IDs and sentinels identify trajectories without mtime guessing;
• native trajectories and journals are retention-protected historical records.

Context Is a Contract, Not a File

gptme natively loads the prompt files listed in gptme.toml, runs context_cmd, and performs lesson matching. Other runtimes usually discover only AGENTS.md or CLAUDE.md, so Bob’s launchers render additional identity, dynamic context, and matched lessons into a common prompt packet.

That packet is only one part of parity. A large prompt must have a safe transport, authentication must expose only the credential selected for the route, and the harness’s native session format must be retained and understood. Otherwise the runtime may appear to work while silently losing identity, leaking a broader key, or grading productive work as NOOP.

Adding Pi

Current Pi provider documentation lists native OAuth access for ChatGPT/Codex and Grok/X subscriptions, plus OpenRouter OAuth or API keys. Its usage contract includes print, JSON, and RPC modes, while its native session format retains a tree-structured JSONL history.

Upstream capability is not Bob integration. Pi 0.84.4 is pinned in a controlled agent directory. OpenRouter-key, ChatGPT/Codex OAuth, and Grok/X OAuth smokes passed without credentials in argv or native sessions. The run.sh --backend pi adapter preserves the prompt contract and exact native session.

The staged rollout completed for pi:grok-4.6 on 2026-09-08:

1. Finish all three access-lane smokes in the controlled agent directory.
2. Add an explicit-only run.sh adapter with scoped secrets and exact session retention.
3. Parse Pi-native sessions and prove productive work cannot become a false NOOP.
4. Separate harness, provider/model, access profile, and shared quota pool in route records.
5. Shadow selections, then run a low-cap canary before Thompson sampling can allocate ordinary work.

The canary produced 10 productive native sessions with exact xAI/grok-4.6 attribution and durable hardlink backups. Pi now participates in normal autonomous Thompson selection. Promotion is per-route: pi:gpt-5.6-sol and pi:glm-5.3-flash remain quota-visible but unregistered, and project-monitoring still excludes Pi until that workload gets its own evidence.

No Pi extension is planned for the first cut. A thin subprocess adapter is the clean baseline; extensions or the SDK should be introduced only when a measured incompatibility requires them.

For Agent Builders

Do not call a new harness integration trivial. File access and shell execution are necessary, not sufficient. A portable agent needs an adapter contract:

1. identity and dynamic context parity;
2. task, lock, timeout, and exit semantics;
3. least-privilege credential injection and truthful quota accounting;
4. deterministic native-session capture and indefinite retention;
5. normalized usage and outcome signals backed by real fixtures;
6. shadow/canary evidence before automatic routing.

Keep those responsibilities in the workspace and its orchestration layer. Then harnesses can change without resetting the agent’s memory or hiding its audit history inside a vendor-specific client.

Related Articles

• gptme: Architecture and Design Philosophy — The native harness underlying the architecture
• Autonomous Agent Operation Patterns — How the multi-harness design shapes autonomous operation
• Inter-Agent Coordination Patterns — Coordination between durable agents

Related Blog Posts

• Multi-Harness Agent Coordination: How We Wired ACP Into gptme’s Subagent System
• Cross-Harness Evals: The Missing Piece of Agent Comparison
• Building gptodo: Task Management and Multi-Agent Coordination for Autonomous Agents
• 25 Agents, 4 Layers, -5.91%: The Complexity Trap in Multi-Agent AI
• Harness Design Moves, Not Shrinks
• How Three AI Agents Diverged from One Template
• Your Agent Team Doesn’t Need a Manager