Open Harness

Inspiration

Agent coding tools are becoming powerful enough to run several specialists in parallel, but the surrounding control plane is still fragmented. Model selection, permissions, worktree isolation, resumability, auditability, and safe installation are often left to prompt conventions or one-off scripts.

Open Harness explores a more transparent answer: an open-source, local-first orchestration and governance layer for OpenCode that makes the GPT-5.6 model family usable as a coherent engineering team.

What it does

Open Harness discovers the actual OpenAI model catalog available through OpenCode at runtime and routes work among logical model classes:

• Sol for architecture, ambiguous judgment, escalation, and adversarial review
• Terra for bounded implementation and repository exploration
• Luna for inexpensive utility and read-only verification work
• Optional Kimi K3 support through OpenCode Go, governed separately and used only when explicitly requested

The current release includes:

• Transactional install, upgrade, migration, and ownership-aware uninstall
• Conservative OpenCode permission policies
• Typed child-session controls for spawn, wait, inspect, steer, cancel, collect, fork, and revert
• Git-worktree-aware writer contracts
• Runtime model discovery instead of hard-coded account assumptions
• Local, content-free audit and usage records
• Bounded resumable checkpoints that store identifiers and lifecycle metadata rather than prompts, transcripts, tool arguments, credentials, paths, or verification commands
• Completion and error notifications
• A deterministic parallel-agent demonstration
• Quota-gated live verification paths that cannot spend model quota accidentally
• Cross-platform release targets, with Darwin arm64 verified locally

Open Harness does not read or import Codex credentials. OpenCode remains the execution engine and credential owner.

How we built it

Open Harness is a TypeScript/Bun monorepo built around three main packages:

1. harness-core contains routing, safe configuration lifecycle, runtime discovery, background-session controls, permissions, worktree coordination, checkpoints, and audit logic.
2. opencode-plugin connects lifecycle events, routing, telemetry, notifications, and compaction to OpenCode.
3. cli provides installation, diagnostics, model status, lifecycle operations, demonstrations, and explicitly gated live checks.

The release process compiles a standalone CLI plus the plugin and routing tool, generates integrity hashes, installs the artifacts into an unrelated temporary workspace, compares installed bytes, and exercises the installed behavior.

How Codex and GPT-5.6 accelerated the work

Codex was not just used to produce code. It was used as the project's orchestration and verification environment.

We assigned different GPT-5.6 model classes to work matching their strengths: Sol handled architecture and adversarial release gates, Terra handled bounded research and implementation passes, and Luna handled lower-cost deterministic checks. Codex tasks were split into read-only architecture, platform, live-session, and observability investigations before allowing a single isolated writer to modify the shared source.

That workflow repeatedly caught issues that a green happy-path suite missed, including manifest path traversal, symlink escapes, unsafe legacy-file adoption, rollback mode changes, sensitive checkpoint fields, duplicate concurrent audit writes, stale-session completion, and unbounded SSE timeouts. Each finding was converted into a focused regression test before the release was considered ready.

The resulting project demonstrates the thesis behind Open Harness: agents become more useful when routing, authority, verification, and recovery are treated as engineering mechanisms rather than only prompting advice.

Challenges we ran into

The hardest problem was safe lifecycle management. An installer that merges into existing OpenCode configuration must preserve unrelated plugins, MCP entries, skills, AGENTS.md files, permissions, and user-modified outputs. It also has to fail before mutation on unsafe collisions and remove only files it can prove it owns.

A second challenge was privacy-preserving resumability. Useful checkpoints need enough information to recover agent state, but storing prompts, commands, paths, or arbitrary error strings creates unnecessary risk. We replaced free-form persistence with bounded schemas, typed enums, counts, and SHA-256 identifiers.

The third challenge was testing asynchronous agent behavior deterministically without consuming model quota. The default suite uses fake SDK transports, temporary Git repositories, isolated worktrees, serialized integration checks, and event-driven lifecycle simulations.

Accomplishments that we're proud of

• 53 automated tests pass across routing, permissions, discovery, configuration, lifecycle migration, privacy, concurrency, background sessions, live-output verification, and release blockers.
• TypeScript and source-format checks pass.
• The security policy check passes.
• The current-platform compiled release installs and passes its smoke test in an unrelated temporary workspace.
• Live model tests are plan-only by default and require explicit quota consent plus exact model confirmation.
• Open Harness is MIT licensed and local first.

What we learned

The most important lesson was that orchestration quality is primarily about boundaries. A capable agent is not enough: writers need explicit ownership, external mutations need different authority from local edits, test success needs adversarial review, and durable state should be structurally unable to retain sensitive content.

We also learned to keep OpenCode authoritative for sessions and credentials. Open Harness focuses on governance and coordination instead of reimplementing authentication or inventing a competing execution engine.

What's next

The next milestone is a daily-driver integration that exposes the complete background controller as first-class OpenCode tools, automatically provisions isolated writer worktrees, and mechanically enforces the route → contract → worktree → verify → review → integrate lifecycle.

Longer term, Open Harness can add a polished UI shell and an intelligent approval-review service backed by real process isolation. The current release is the tested local control-plane foundation for that direction.

Try it

Prerequisites are Bun 1.3.14+, Git, Just, and OpenCode 1.18.4.

opencode auth login
just bootstrap
just doctor
just test
just smoke

The README also documents global installation, deterministic demos, contract checks, release verification, optional Kimi configuration, supported platforms, and the project's current limitations.

Built With

• bun
• codex
• git
• gpt-5.6-luna
• gpt-5.6-sol
• gpt-5.6-terra
• opencode
• typescript