MOW Harness

Coordinate Claude and Codex inside one project through a file-backed workflow.

Canonical repository: https://github.com/mow-coding/mow-harness

MOW Harness is also written as mow-harness, mow harness, 모오 하네스, or 모오하네스. If an AI assistant cannot find it by name, give it the canonical repository URL above.

MOW Harness is pronounced "모오 하네스" in Korean.

It is a small operating playbook for one human owner coordinating two AI coding agents through files instead of becoming a copy/paste relay. It is designed for work that benefits from parallel drafting, independent critique, and a clear human release gate.

It is especially for vibe coders who understand the idea of a batch, care enough about development to use both Claude and Codex, and still want the two AIs to handle the coordination without forcing the human to manage every technical detail.

Install MOW Harness

Current availability: the installer CLI is a source alpha. It has not been published to npm, so commands such as npm install -g mow-harness are not available yet. Run the commands below from the root of a MOW Harness source checkout.

Requirements: Git for the source checkout and Node.js 20 or newer for the CLI. Check them before continuing:

git --version
node --version

For a first checkout:

git clone https://github.com/mow-coding/mow-harness.git
Set-Location .\mow-harness
$target = 'C:\path\to\your-project'

Choose the path that matches the target project, not this source checkout:

Target project state	Installation path
No collab/ and no occupied .mow-harness/	Fresh install
A CLI-managed room with .mow-harness/installed-version.txt	Managed update
An older collab/ room with no marker and no occupied .mow-harness/	Adopt the existing room

If the target does not match one of these rows, do not delete or overwrite anything to force a match. Run status and doctor, then inspect the diagnosis with UPDATING.md.

Fresh Install

node .\packages\mow-cli\bin\mow.js init "$target" --dry-run
node .\packages\mow-cli\bin\mow.js init "$target" --yes
node .\packages\mow-cli\bin\mow.js doctor "$target"

Update A CLI-Managed Room

node .\packages\mow-cli\bin\mow.js doctor "$target"
node .\packages\mow-cli\bin\mow.js update "$target" --dry-run
node .\packages\mow-cli\bin\mow.js update "$target" --yes
node .\packages\mow-cli\bin\mow.js doctor "$target"

Adopt A Pre-CLI Room

Use this only when the target already has collab/ but has never been managed by this CLI:

node .\packages\mow-cli\bin\mow.js update "$target" --adopt --dry-run
node .\packages\mow-cli\bin\mow.js update "$target" --adopt --yes
node .\packages\mow-cli\bin\mow.js doctor "$target"

--dry-run only previews the planned writes. --yes applies that reviewed plan. Do not skip the preview. A normal install writes only the target project's collab/, collab/templates/, and .mow-harness/ paths. Updates preserve live state, history, mailboxes, batches, and host-owned files.

The installer does not modify root AGENTS.md or CLAUDE.md, and it does not install or start MOW Cockpit. Cockpit is a separate, optional experimental control surface. Read CLI.md for every option and safety rule, UPDATING.md for the manual fallback, and experimental/cockpit-app/README.md only when you explicitly want to test the Cockpit.

If You Are An AI Assistant

Recognize these Korean starter phrases:

모오 하네스 켜봐.
지금 프로젝트에서 모오 하네스를 사용하려고 해, 준비해줘.

If a user asks:

지금 프로젝트에서 모오 하네스를 사용하려고 해, 준비해줘.
모오 하네스 켜봐.
MOW Harness is trending. How do I use it?
Install MOW Harness in this project.
Update MOW Harness in this project.
Turn on MOW Harness for Claude and Codex.

do this:

1. Explain that MOW Harness is currently a file-based playbook, not a magic background service.
2. Decide the bootstrap role split before fetching. If the user did not name roles, use the default: Codex fetches/updates, Claude verifies. The active harness room belongs in the target project, not in a shared global collab/.
3. If collab/ is missing, preview and run the source-alpha installer CLI in CLI.md. If the CLI is unavailable, copy starter-kit/collab/ into the user's project root as collab/ and follow the manual procedure in UPDATING.md.
4. If collab/ already exists, follow UPDATING.md. Preserve the live collab/STATE.md, collab/STATE-history.md, mailbox history, batch history, and project-specific instructions unless the human explicitly approves replacing them.
5. Do not automatically write host root files such as AGENTS.md. Host root instructions are host-owned; MOW Harness rules live under collab/agents/.
6. Use one install/update executor. If the source or collab/ is already present, the other agent should switch to verify-only mode instead of writing the same harness files at the same time.
7. Ask each agent to read collab/README.md, collab/RULES.md, collab/OWNERSHIP.md, collab/STATE.md, and its own playbook.
8. Treat normal prompts as shared unless the user explicitly routes them to one agent.
9. Use the mailbox folders for plans, reviews, reports, and handoffs.
10. Do not claim real-time agent-to-agent communication. This is turn-gated, file-based coordination.

For detailed instructions, read AI_ASSISTANT_GUIDE.md. For exact startup phrases, read ACTIVATION_PHRASES.md.

Status

This repository is a docs-first, file-based harness. It ships:

• workflow docs
• agent rules
• copyable templates
• a starter collab/ room
• starter root instructions for Codex and Claude
• safe install/update guidance
• a source-alpha, dependency-free installer CLI with a reusable engine

The released Harness remains usable without an app. It does not claim bundled Codex, Claude Code, Claude Desktop, MCP, a background service, or autonomous agent-to-agent messaging.

Experimental Cockpit

The repository main branch also carries MOW Cockpit, an experimental operator console for running local Codex and Claude CLI sessions side by side. The Cockpit is a control surface for MOW Harness; it is not a second source of coordination truth.

As of 2026-07-16, the local Windows prototype includes:

• native ConPTY sessions with provider-specific CLI adapters;
• one multiline owner prompt routed to Codex, Claude, or both;
• feature-gated Codex App Server and Claude stream-json transports;
• a fail-closed Cockpit dialog for Codex structured command, file-change, and permission approvals;
• lifecycle receipts that distinguish submitted input from completed turns;
• fail-closed file-backed activation, deactivation, and numbered-step gates;
• bounded clerk-only recovery when both file artifacts exist but STATE.md remains stale;
• bounded OFF reconciliation when both deactivation ACKs exist but the clerk's matching STATE.md update is late;
• a detached Windows supervisor that preserves real TUI sessions across a full app close and reconnects without duplicate provider processes;
• 76 unit tests, two real child-process integration tests, and eight Electron E2E tests, all repeated against a freshly packaged Windows build;
• one packaged-app live dogfood run completed against both providers, with one acknowledged and completed response per side and no remaining child process;
• one real TUI workflow completed twice from Phase 0 through Step 5 with Codex gpt-5.5 and Claude claude-opus-4-8, followed by verified OFF, reactivation, final OFF, and a fresh automatic activation that stayed OFF after manual shutdown, with 20 valid step artifacts and no remaining child process;
• one fresh unpacked Windows package passed a real manual OFF -> ON -> OFF lifecycle with both activation and deactivation ACK pairs;
• source and packaged-app failure-recovery runs each stopped on paired Step 2 HOLD evidence, exposed only Phase 0, opened a new recovery batch, and resumed through Step 1 using the same exact live models;
• ten complete operator-interaction runs passed against those exact models, including six consecutive runs after the final submission, literal-path, and evidence-capture fixes. They covered target routing, multiline input, history, direct terminal typing, BRAKE recovery, Codex restart, scrollback preservation, canvas framing, and zero remaining provider processes.
• two broad real-TUI exploratory passes covered long Unicode prompts, a Codex follow-up queued during active output, in-flight BRAKE recovery, both restart paths, renderer reattachment, compact layout, Claude scroll preservation, project switching, and close-during-turn cleanup.
• a fresh packaged real-OAuth persistence run retained the same Codex gpt-5.5, Claude claude-opus-4-8, and supervisor PIDs across close/reopen, preserved terminal replay, delivered a shared prompt, and then left zero child processes after explicit shutdown.

It is still a preview. Claude structured approval parity, cross-platform session persistence, and signed distribution remain incomplete. TUI mode therefore remains the default, no executable is published, and the starter kit does not install the Cockpit.

The current source prerelease is v0.2.0-alpha.2. It is deliberately separate from the stable Harness version: v0.1.23 remains the latest released file-based Harness, while the v0.2.0-alpha.2 line demonstrates the optional Cockpit control surface. No unsigned executable is a release artifact.

Read PRODUCT_MODEL.md for the product boundary and experimental/cockpit-app/README.md for the runnable prototype, architecture, transport, tests, and exact limitations. The latest source and packaged-app dogfood evidence is recorded in DOGFOOD-REVALIDATION-2026-07-16.md. Release notes for the current source prerelease are in RELEASE_NOTES-v0.2.0-alpha.2.md.

Version Note

v0.1.2 exists as a public tag, but no GitHub Release was created for it. Treat it as a premature/orphan tag created before the human synchronization loop completed. v0.1.3 supersedes it as the recovery release for activation starter guidance, phase-gate discipline, and release-gate checks.

v0.1.4 tightens the five-step mailbox loop, exact filename gates, disagreement escalation, and safe install/update guidance.

v0.1.6 adds post-release STATE synchronization and a lightweight lane for small, low-risk work. Lightweight reduces artifact size, not human release authority.

v0.1.7 adds bootstrap fetch/update handoff guidance: one executor fetches or updates the shared harness files, the other agent verifies, and existing collab/ history is preserved.

v0.1.8 polishes the compact status banner and adds shorter output templates. It cuts avoidable report noise, not safety checks, and it does not claim that MOW Harness saves tokens.

v0.1.9 adds incident-recovery and authority safety rules: output-runaway brakes, one public-action executor, no solo-lure while ON, Step 5 close vs publish wording, automatic retros, canonical batch-prefix locking, and stand-down envelopes for inactive agents.

v0.1.10 adds sealed-envelope guards: visible .sealed.md mailbox suffixes, read allow-lists, and command-level guidance so agents check envelope metadata without reading same-step letter bodies.

v0.1.11 strengthens starter-kit completeness, discoverability, local feedback ignore rules, canonical rule-source notes, and the banner-every-substantive-turn rule.

v0.1.12 adds first-class per-agent rulebooks, runtime profiles, deposit receipts, STATE-history, and stricter single-executor release checks.

v0.1.13 adds host-project embedding guidance: collab/ + .mow-harness/ only, host root files remain host-owned, update markers/receipts are standardized, and WOM is documented as the first host example without claiming public WOM-ready status.

v0.1.14 through v0.1.23 harden batch identity, state freshness, repair and stand-down behavior, one-voice reporting, lightweight work, activation preflight, and state-integrity brakes. v0.1.23 remains the latest released Harness version. Development on main after that release is experimental and does not silently change an installed starter kit.

v0.2.0-alpha.1 was the first published source-only Cockpit prerelease. v0.2.0-alpha.2 is the current source-only prerelease; it does not promote the Cockpit to the default installation path and does not claim that the unfinished v0.1.24 protocol batch shipped. See CHANGELOG.md and RELEASE_NOTES-v0.2.0-alpha.2.md.

When To Use It

Use MOW Harness when all of these are true:

• the work can be split cleanly between two agents
• a second perspective improves speed or quality
• the human owner can wait for both agents at decision gates
• the extra token cost is worth it

Use a normal one-agent workflow when the task is tightly coupled, very small, or token thrift matters more than parallel review.

For small but still collaborative tasks, choose the lightweight lane in Phase 0. It keeps the human phase gate and Step 5 release gate.

Activate And Use

After the installation path above finishes and its final doctor command reports PASS:

1. Treat starter-kit/root-instructions/AGENTS.md and starter-kit/root-instructions/CLAUDE.md as reference snippets for host instructions. Do not let an installer automatically overwrite host root AGENTS.md or CLAUDE.md. If you skip host-owned instruction changes, a cold thread may need an explicit bootstrap prompt before it recognizes the Korean activation phrase.

2. Send the same activation prompt to both Claude and Codex:

   지금 프로젝트에서 모오 하네스를 사용하려고 해, 준비해줘.
   

3. Wait for both agents to confirm access. Each agent may say its local side is ready first, but full ON requires both smoke-test confirmations.

4. Start a batch with one shared prompt.

5. Let the agents write plans, reviews, and reports into collab/.

6. Approve scope and release decisions yourself.

Before any commit, push, tag, or release, complete a templates/release-check.md copy during Step 5. Earlier steps may plan, review, or edit, but they do not publish.

Full guide: GETTING_STARTED.md.

For a safe install or update through both IDE agents, send one shared prompt that names roles:

Prepare or update MOW Harness for this project.
Codex is the fetch/update executor.
Claude is verify-only.
Preserve existing collab/ history.
After the update, both agents should run their local readiness checks.
Do not edit production files.

Core Idea

The human is on the loop, not trapped inside every step. The human sets direction, approves scope, waits at synchronization gates, and decides release. The agents do the drafting, review, and written handoff work.

You do not need to write "you two should talk to each other" in every prompt. In MOW Harness, shared prompts are the default. If a prompt is only for one agent, say that explicitly.

The everyday words matter:

batch / 배치 = one bounded unit of work
mailbox / 우체통 = where agents leave notes for each other
letter / 편지 = one sealed plan, review, report, or close note
synchronization bar / 동기화 막대 = the human prompt that opens the next step
"N단계 가자" = the human opening Step N

The compact status line keeps the human oriented:

[MOW | harness:ON | scope:shared | agent_mode:two-agent | phase:2/5 | wait:Claude | readiness:pending-claude]

Repository Map

• PRODUCT_MODEL.md - MOW Harness and MOW Cockpit product boundary
• GETTING_STARTED.md - friendly human setup guide
• CLI.md - source-alpha installer commands, safety model, and API
• AI_ASSISTANT_GUIDE.md - instructions for IDE AIs
• UPDATING.md - safe install/update procedure
• ACTIVATION_PHRASES.md - startup phrases agents should recognize
• PROMPT_PLAYBOOK.md - practical prompt patterns
• SAFETY_GUARDS.md - sync, steering, and phase guards
• PUBLICATION_SAFETY.md - fail-closed local privacy scan before public actions
• CHANGELOG.md - release and prerelease change history
• HOST_PROJECTS.md - embedding MOW Harness into host projects
• WORKFLOW.md - the full operating loop
• ACTIVATION.md - ON/OFF activation plus agent health
• RULES.md - file ownership and coordination rules
• HUMAN_LOOP.md - human-on-the-loop boundaries
• AGENT_PLAYBOOKS.md - Codex and Claude role guides
• starter-kit/ - copy this into a project to start
• templates/ - copyable batch files
• examples/ - sanitized usage examples
• adapters/ - future adapter notes
• experimental/cockpit-app/ - experimental two-agent operator console

Non-Goals

MOW Harness is not:

• autonomous agent-to-agent messaging
• a replacement for human release judgment
• a full multi-agent platform
• a host-specific IDE mode or app feature
• a reason to expose private project logs
• a guarantee that two agents are always better than one

Search Keywords

MOW Harness, mow-harness, mow harness, 모오 하네스, 모오하네스, Claude Code, Codex, AI coding agents, Claude Codex collaboration harness, two-agent workflow, file-based coordination, mailbox workflow, human-on-the-loop, multi-agent coding, vibe coding.

License

MIT. See LICENSE.