Harness Courier

English | 简体中文

Send tasks from Codex to specific Kimi Code and ZCode desktop chats on Windows, then collect acknowledgements and results through MCP.

Harness Courier binds a readable alias to a real desktop session ID. Messages stay pinned to that session and binding revision, while a local SQLite mailbox tracks delivery, ACKs and results. An optional Cua Driver integration provides background computer input where the target application supports it.

Download preview · Quick start · MCP tools · Limitations · Contributing

What it does

• Bind a recipient: address a chosen Kimi Code or ZCode chat by its real session ID, using an alias such as projectA-kimi-review.

• Send and track: store messages, bindings and receipts in a shared local SQLite mailbox.

• Deliver in the background: use a verified local CDP endpoint to submit recipient-scoped wake metadata. A receiver Hook or exact-ID receiver inbox call fetches the message body, including when Kimi steering skips a Hook.

• Protect active work: check the target session, drafts, attachments and busy state before sending. Preserve uncertain submission records to guard against duplicate sends.

• Return a result: receivers acknowledge the message and report success or failure through MCP. Codex queries the original message ID.

• Observe agent activity: read current turn state separately from receipts, including supported ZCode and Kimi session metadata without selecting the chat.

• Add optional computer control: use the Cua background policy and registration helpers separately from message delivery.

This is a community integration for Windows desktop applications. Codex, Kimi Code, ZCode and Cua are independent products; their names do not imply official endorsement.

Related MCP server: agent-bridge

How it works

Codex --send to bound session--> SQLite mailbox
  |                                  |
  +--CDP wake marker--> Kimi / ZCode --receiver Hook--> fetch message
  |                                  |
  +--query original message ID-------+--MCP ACK / result--> mailbox

The stored message states are:

Desktop submitted is a separate transport signal. It does not prove receipt or task completion. A completed receipt still needs the sender's review of the actual work.

Quick start

1. Install from source

You need Windows, Python 3.11+, and installed Kimi Code / ZCode desktop applications. The Python dependencies are psutil and websocket-client.

git clone https://github.com/xiaoctf/harness-courier.git
cd harness-courier
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
Copy-Item apps.example.toml apps.toml

You can also download the complete source ZIP from Releases. It includes the documentation, CMD launchers and optional Cua integration. The wheel contains the Python service, Hooks and required resources. The package is not published to PyPI.

2. Set application paths

Edit apps.toml with your actual application executable paths. apps.example.toml shows the format. Defaults are generic Program Files examples; the launcher does not discover installations automatically.

HARNESS_COURIER_APPS can point to an alternate TOML file by absolute path. The old HARNESS_BRIDGE_APPS variable remains a fallback. Invalid fields, relative executable paths, duplicate ports and a missing explicitly selected file are rejected.

3. Register MCP and receiver Hooks

All three clients must share one mailbox. The installer registers MCP servers and Kimi/ZCode receiver Hooks while preserving unrelated settings.

# Preview the installation plan.
.\.venv\Scripts\python.exe bridge\install_integrations.py

# After reviewing the plan, apply it.
.\.venv\Scripts\python.exe bridge\install_integrations.py --apply

A fresh installation uses the MCP registration name harness_courier. An existing owned harness_bridge registration is retained. Conflicting registrations are rejected. Reload the desktop clients after applying configuration so their sessions can run the receiver Hooks.

4. Start background delivery

.\launcher\start_background.cmd --check
.\launcher\start_background.cmd --app all

--check does not launch or close applications. Exit code 0 means the check finished; inspect background_ready for readiness. If an application is already running without its debugging endpoint, save your work and close it before launching again. The launcher never forcibly closes applications, and starts new processes minimized without activating their windows.

The CMD launcher chooses HARNESS_COURIER_PYTHON, then the legacy HARNESS_BRIDGE_PYTHON, the repository .venv, py -3, or python on PATH. Set the environment variable to an absolute interpreter path when needed.

--autostart supports delayed startup and logging to bridge/data/startup.log; it does not create a Windows startup entry by itself.

5. Bind, send and receive

1. Trigger the receiver Hook in the intended Kimi/ZCode chat.

2. Use courier_list_sessions to find its real session ID. Confirm the project and recipient, then call courier_bind_target with a distinct alias.

3. Call courier_send_message with that alias and task body. Save the returned id for all later message_id arguments.

4. The receiving agent uses its Hook-provided caller_session_id to receive, acknowledge and return the result.

5. Codex uses courier_wait_for_receipt or courier_get_message_status to query that same message.

The message body is limited to 6,000 characters. Use aliases such as <project>-<harness>-<role> for different projects; this is a naming convention, not an access-isolation boundary. Chat titles alone are not session identity.

MCP tools

Tool discovery also exposes the original bridge_* aliases with the same schemas and role restrictions. The old harness_bridge imports, CLI commands and environment variables remain supported.

For supervision, use courier_get_agent_status(alias="project-kimi-review"). Codex receipt queries also include an agent observation for the message's original recipient. running, idle, recent stop_observed, approval_requested, waiting_for_input, and unknown describe different evidence. An idle agent with unfinished receipts needs attention; idle never marks a message completed. Queries do not switch chats or retry tasks. Supported ZCode versions expose exact-session controller state even when the target chat is unselected or absent from the rendered sidebar. An old Stop event does not invalidate that current observation. Kimi Code 1.0.4 also supports an exact-session metadata query for hidden chats; missing and archived targets are reported separately. A missing ZCode workspace runtime is distinguished from a desktop connection failure. See Agent activity for Hook loading, freshness and background-job limits.

The MCP server runs a fixed background dispatcher internally, so agents do not need an extra shell command to send a wake. Host approvals still apply; tool annotations describe behavior and do not grant permissions.

For manual configuration, the source entry is:

.\.venv\Scripts\python.exe bridge\bridge.py mcp --harness codex

After installation, harness-courier mcp --harness codex is the equivalent CLI entry. The default mailbox remains bridge/data/bridge.sqlite3 in a source checkout. Keep installation and configuration paths valid when moving the repository.

Optional Cua background control

integrations/cua contains the policy, registration helper, MCP verifier and WPF test source for Cua Driver. The integration expects Driver version 0.33.3; that is not a claim about the latest upstream version. No Driver binary is bundled.

Its MCP registration remains cua_background. Input actions should explicitly use delivery_mode="background". An unavailable background action or policy denial must not trigger automatic foreground fallback. Support depends on the application, control and action.

Cua computer input and the Courier CDP message transport are separate integrations.

Agent instructions and documentation

The following detailed guides and prompt templates are currently in Chinese:

• Collaboration workflow: binding, task design, receipts and review.

• Codex controller instructions.

• Kimi/ZCode receiver instructions.

• Task card template.

• Codex approval behavior.

• Naming and compatibility.

• Development and release preparation.

Adapt the templates to the project and place them in the client's supported instruction files. MCP does not load these texts automatically or grant authority to send tasks.

Limitations

0.1.0 is a preview. The current source has 242 regression tests. Windows CI is configured for Python 3.11 and 3.13, Ruff and package builds; see Actions for each commit's actual result. Automated tests and isolated browser fixtures do not establish compatibility with every desktop application version.

• Receipts are stored in message records and queried by the sender. There is no complete scheduler that automatically wakes the original Codex chat with a result.

• Explicit dispatch requests use a durable outbox and one delivery worker per mailbox. Priority jobs go first; jobs of the same priority use FIFO order when ready. Transient pre-input failures have bounded retries, while drafts and uncertain submissions are held for inspection. Real multi-project desktop concurrency still needs acceptance testing.

• Local desktop tests with Kimi Code 1.0.4 and ZCode 3.14.4 verified real receipts, native priority consumption and activity observations from one originating Codex environment. Other versions, simultaneous independent Codex senders, Cua input and host approval behavior still need acceptance testing in target environments.

Messages, databases, logs, local configuration, backups and third-party binaries are excluded from the source distribution.

The latest reliability update validates MCP argument types before changing state, preserves receipt evidence over historical delivery errors, and bounds transport recovery. ZCode can select an unrendered bound session through a verified native workspace/session lookup, then recheck the composer before input. This fallback was tested locally on ZCode 3.14.4; unknown application contracts fail closed. It does not automatically replay exhausted jobs. Kimi activity still requires a verifiable rendered target, and intermittent renderer timeouts remain possible.

Development and license

Install development tools with python -m pip install -e ".[dev]". See CONTRIBUTING.md for checks and SECURITY.md for security reporting.

Harness Courier's own code is MIT licensed. External dependencies retain their own licenses; see THIRD_PARTY_NOTICES.md.

The current source adds a durable outbox, bounded retries, lock waiting, busy-chat navigation, native priority delivery and an optional administrator policy that forces priority. Recipient-scoped wake metadata also supports exact-ID inbox retrieval when native steering skips a receiver Hook. Dispatch acceptance is asynchronous: inspect dispatch_queue, the original message ID's receipts and current agent activity. Local desktop validation is bounded to the versions above. The earlier v0.1.0-preview release archive does not include these upgrades; use the current main source. See dispatch and priority (Chinese).

Dispatch defaults to native priority and busy-chat navigation. Set priority=false to queue normally only when the mailbox administrator has not enabled force_priority. With that policy enabled, enqueue and delivery override false; existing draft and identity guards remain in force.