The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
Harness portability
A harness provides workspace preparation, instructions, skills, toolchain commands, a viewer and verdicts. An engine provides file/shell tools and a documented way to load project instructions. The runtime binds those two contracts. Package names never occur in an adapter.
Session lifecycle
materializeWorkspace only prepares files and runs init. prepareHarnessLaunch then creates a
bundle under <workspace>/.harness/runtime/<sha256(session key)>/:
runtime.json: the selected harness and engine, instructions, expanded environment, legacy default-engine argv, and skill source paths. It contains no account credentials.CONTEXT.md: instructions and a discoverable skill index, usable with ordinary file/shell tools.skills/<name>: links to installed skill assets, without modifying native discovery directories.
The agent process receives HARNESS_CONTEXT_FILE and HARNESS_SKILLS_DIR through its own tmux
environment. A generic, idempotent bootstrap in its effective project instruction file loads that
context. It does nothing for Coding when that environment variable is absent. Claude and Pi also
receive their documented append-instruction flag. User project instructions remain in place.
Each launch clears inherited HARNESS_* session variables it does not explicitly supply,
including a previous account's private grid. Coding and Terminal therefore cannot inherit an
unrelated session's harness context. Runtime bundles and migration backups are ignored by Git.
Create stores dshRuntime beside engine and dsh. Resume and restart reuse the snapshot; fork
copies the source snapshot under a new key. Legacy rows use their stable agent id. A store update
cannot change a saved engine, argv or instructions. Installed tools and skill assets still follow
package updates. Runtime bundles stay with the workspace, so retained sessions can resume them;
deleting a workspace removes its runtime state. This isolates configuration, not project output:
two sessions pointed at the same project intentionally share its artifacts and verdict file.
Missing instructions, missing skills, duplicate skill names, occupied runtime paths, corrupt snapshots and engine/identity mismatches fail before the engine is spawned. Symlinked managed directories and instruction files are not overwritten. A missing installed package refuses resume instead of silently falling back to Coding.
Existing projects and packages
The spec-1 manifest is unchanged. engine is a default; agent.args is a legacy extension applied
only when the chosen engine is that default. The runtime converts old workspace-native skill paths
in environment values to HARNESS_SKILLS_DIR, rewrites workspace-relative instruction examples
with a quoted "$HARNESS_SKILLS_DIR", and neutralizes the introductory “You are Claude Code/Codex”
wording in legacy instruction text. It leaves upstream source paths intact.
Older materializers appended package instructions under <!-- harness:dsh owner/name --> with no
end marker. Migration removes an exact match to known installed package text, keeping all other
project bytes and a .harness/legacy-AGENTS.md backup. It removes only native skill links whose
targets exactly match that package. If the legacy text was edited or its package is missing, it
remains untouched and launch explains which section needs resolution. There is no safe general
way to infer where an edited legacy section ends.
dsh_list.engines reflects the daemon's adapters, for installed and uninstalled packages alike.
The desktop trusts the selected machine's answer; old daemons without the field offer the manifest
default. The same Harness → Agent → Model → Machine → Project form handles Coding and store packages.
Agent/Model and Machine/Project/Branch are adjacent groups. Advanced hides worktree, approvals and
profile (Codex subscription launches only); Machine stays visible and Start stays pinned below
the scrolling fields, reachable from any field with ⇧⏎. Preferences stay in the existing app data folder;
new_harness_preferences_v1 separates agent and harness recents and remembers the last engine for
each harness. Legacy preference keys are read without being deleted.
Model routing at creation
Harness compatibility and model routing are independent contracts. All integrated process engines
can load a harness; only engines whose existing grid adapter supports a model override offer local
and shared models. The selected machine advertises localModelEngines and supportsModelLaunch
in grid_models_list. The picker includes the matching engine subscription/default login and
running models, grouped by owned/shared grid, with each serving machine visible. Machine is where
the agent and project run; it does not constrain where inference runs.
agent_create accepts the semantic pair gridModel / gridName. Both are required together;
unsupported engines, malformed values, raw grid credentials or a simultaneous Codex subscription
profile are refused. The creation receipt fingerprints the semantic pair, not a rotating credential.
After reserving the receipt and before preparing a project, the daemon refreshes model availability
and resolves the target using the existing grid service. Missing targets return GRID_UNAVAILABLE
without launching or silently using an engine subscription. Repeating a receipt never resolves
or starts a second time. Clients predating receipts retain their existing response shape.
Drafts and pending receipts retain the exact model/grid. A machine or agent change preserves an explicit model and revalidates it; choosing Terminal clears model routing. A fresh session defaults to the engine login. Manage Models opens the existing lifecycle panel and preserves the draft. Old daemons keep ordinary launches working; an explicit model choice requires the capability and explains when an update is needed.
Adapter evidence
Contracts checked 2026-09-23. The portable baseline needs no private provider APIs or guessed flags.
| Engine | Project instructions / additional context | Primary contract |
|---|---|---|
| Claude Code | CLAUDE.md, --append-system-prompt |
Installed 2.1.281 --help; memory |
| Codex | AGENTS.override.md, AGENTS.md |
project instructions |
| Cursor | AGENTS.md |
CLI usage |
| OpenCode | AGENTS.md, existing CLAUDE.md fallback |
rules |
| Pi | AGENTS.md, existing CLAUDE.md; --append-system-prompt <file> |
Installed CLI --help; source |
| Hermes | .hermes.md, AGENTS.md, CLAUDE.md, .cursorrules |
Installed hermes_cli/_parser.py, hermes_cli/tips.py; source |
| Command Code | AGENTS.md |
project memory |
| Devin | AGENTS.md |
CLI |
| Muse | AGENTS.md, existing CLAUDE.md fallback |
Public release metadata, executable 1.3.0-R3401.1 /init and /rules contracts |
| Amp | AGENTS.md |
agent instructions |
| Kilo | AGENTS.md |
custom instructions |
| Grok | AGENTS.md |
skills and instruction compatibility |
| Antigravity | AGENTS.md, existing GEMINI.md |
rules |
| Copilot | AGENTS.md |
custom instructions |
The Muse artifact was checksum-verified (20c5eb32f6aea741adac032c14be2f1897432caaf35144c33279a4d2b0bd8840,
macOS ARM64) and inspected without installing it or using credentials. Vendor model execution is
separate from contract testing; passing fixture tests does not claim that every provider ran a model.
Validation
cd cli && npm run test:portability enforces 100% statements, branches, functions and lines per
file for the runtime, adapters, compatibility projection, launch environment and workspace
materialization, plus semantic model selection and resolution. It also runs DSH integration,
socket, registry and launch-override regression tests.
The broader CLI and desktop suites check affected entry points, persistence and existing app flows.
The matrix covers all 72 store agent manifests on all 14 engines (1,008 combinations), including restart and fork after package changes. Local instructions and skills use the repository content; assets normally downloaded by package setup use small fixtures. A separate subprocess lifecycle for every engine verifies workspace init, context and skills, tool execution, artifacts, verdicts, restart and fork. These tests do not call provider models or install every native toolchain.
After cd desktop && flutter test --coverage, run
python3 desktop/tool/check_portability_coverage.py from the repository root. It requires 100%
coverage of changed executable desktop lines. Pass --base <merge-base> when checking committed
changes. The interactive host at desktop/tool/harness_portability_review.dart uses production
workspace widgets with an in-memory transport and records launch selections without starting agents.
It requires an isolated native bundle, FLUTTER_TEST=1, and HARNESS_REVIEW_CATALOG pointing to a
JSON array of dsh_list rows. Keep its bundle identity separate from the installed application.
Review evidence (2026-09-23)
- Shuffled portability suite, seed
20260926: 975 passed, 9 native-toolchain opt-in tests skipped. Core coverage: 217/217 statements, 205/205 branches, 36/36 functions, 172/172 lines, including semantic model selection and resolution. - Desktop, seed
20260928: 679/679 changed executable lines covered; 3,166 passed, 11 skipped, 18 failures. All 18 reproduce on unchanged33380665in account lifecycle, sign-out, expiry, local CLI discovery, environment setup, and the machine/model acknowledgement badge test. The changed-file coverage gate passes without exclusions. - Final CLI full shuffled regression, seed
20260926, two workers: 4,432 passed, 63 skipped, no failures. The desk relay test now resets its shared socket inventory before running; its previous shuffle-order failure was independently reproduced on unchanged33380665. - Focused desktop run: all 99 model selection, form, configured keyboard and entry-rule tests passed, including a correction that labels an explicit Codex subscription profile by name.
- All 27 store packages with an npm test script passed before the rebase. Model Manager was the only store package changed by the rebase; its current suite passed all 43 tests.
- TypeScript type checking, CLI build, isolated native app build, and Dart analysis of changed production files and new regression tests passed.
- Computer-use walkthroughs exercised the actual native review app at narrow and wide widths: Coding and store harnesses; engine-only Agent choices; a legacy harness's compatibility filter; the complete scrollable harness catalog; relevant subscription, owned and shared model choices; independent model/agent machines; search and Enter; Advanced; and fixture session creation. Manage Models and reopening the launch form preserved the selected agent, model, machine and project. Native File > New Harness exercises the same command as Cmd-N; synthetic modifier injection did not deliver Cmd-N, so physical shortcut behavior is not claimed by that walkthrough. Flutter's configured-key and native-command regression tests cover the command dispatch.
- The native walkthrough found and fixed two layout/accessibility problems: expanding Advanced could push Start below the viewport, and its semantics merged with the form after pinning it. Start is now pinned and has its own accessible bounds. Wide/compact widget tests assert both; a final native accessibility click created the fixture session with the chosen shared model.
- Final review also found and fixed a model-to-Terminal transition that kept a model behind the disabled Model row and blocked launch. Both forms now omit model routing for Terminal. All 22 model/Terminal regressions passed, and the native walkthrough selected a Mac Studio model, switched to Terminal, and successfully submitted a fixture launch without model routing.
Coverage percentages above describe their measured scopes, not full CLI/desktop branch coverage. Real provider model calls and the optional native studio installations were not exercised.