cross-harness

Run BizOS CLI, Claude Code, Codex, Kimi Code, OpenCode, Gemini CLI and other coding agents side by side — as one team.

One message to several agents · agents ask each other · one approval queue · a git worktree each · review by a different agent before merge · goals checked with evidence

中文 · Install · Quick start · User guide · Protocol · Architecture · Providers · BizOS Code ↗

_{Recorded from cross-harness's real terminal UI. The agents are scripted stand-ins that speak the BizOS CLI (bizos acp), Codex and Claude Code protocols, so the recording can be repeated: what they say is scripted, while the engine, the worktrees, the test runs, the approval and the question passed from one agent to another are real. How the recordings are made.}

Every coding agent comes with its own terminal, its own permission prompts and its own idea of the repository. Use two at once and you are copying answers between windows, approving the same command twice and untangling edits made to the same files.

cross-harness puts them on one stage. It starts each agent through the protocol its vendor ships, so it sees every command, edit, plan step and permission request as data. You address agents with @mentions, they can ask each other questions through cross-harness, everything they want to do waits in one queue for you, each works on its own git branch, and nothing is merged until a check you trust — a command cross-harness runs itself, or a review by a different agent — has passed.

cross-harness is the open cross-harness protocol from the team behind the BizOS CLI, with this reference implementation: a terminal UI, a local web UI and a command for scripts, in plain Node.js with no dependencies. The BizOS CLI is built in: type @bizos and it works next to Claude Code, Codex and the rest.

⭐ If cross-harness saves you time, please star it on GitHub — stars help other developers find it and keep the BizOS team going.

• One message, many agents. @codex @claude review src/ starts both at once; one line per agent gives each its own task. @all, @auto and @compare:claude cover the rest.
• Real sessions, not screen scraping. Each agent runs through its vendor's own protocol — ACP, codex app-server or Claude Code's stream-json — so cross-harness sees every command, edit, plan step and permission request as data.
• Agents talk to each other. Every agent gets tools to ask another agent (with deadlock detection), ask you for a decision, share a project board and post its status. They work inside agent sandboxes because they go through files, not sockets.
• You approve in one place. Permission requests from all agents land in one queue. Choose allow once, always allow for this agent, or deny. Plan, ask, workspace and full modes decide what is automatic.
• Isolated by default. In git repositories each agent works in its own worktree on its own branch, so parallel agents never step on each other.
• Review, then merge. See an agent's diff, have a different agent review it, then merge with --no-ff. Dirty projects and conflicts are refused cleanly.
• Goals with evidence. Write down what "done" means: commands cross-harness runs, reviews by another agent, confirmations by you. cross-harness checks the work itself, sends failures back to the agent, and holds merges until the checks pass on the exact tree being merged.
• Anywhere. A terminal UI, a local web UI, cross-harness run for scripts and CI, and --ssh host to run every agent on another machine.

Press d to see what an agent changed on its branch and m to merge it. cross-harness first asks a different agent to review the diff — here Codex reviews the BizOS CLI's fix — and merges with --no-ff only when you confirm.

cross-harness gui serves the same engine on 127.0.0.1: the agents and their live work, approval cards with one-click answers, diffs, reviews and merges, goals and the project board. It follows your light or dark theme and works in a phone-sized window.

_{Recorded from the real web UI in Chrome, served by cross-harness's own request handler. This image follows your system's light or dark theme.}

One engine serves one project. Every interface talks to it through the same small client protocol, in the same process, over stdio or over SSH. Every agent is reached through the session protocol its vendor ships, normalised into the same seven events; agents reach cross-harness back through an MCP server (cross-harness mcp) that carries their tool calls as files, so it works inside their sandboxes. The protocol is specified in spec/ and the implementation is described in docs/architecture.md.

Requirements: Node.js 20.11 or newer, git, and at least one coding agent installed and signed in (for example claude, codex, opencode, kimi).

Install the 0.2.0 preview from its release:

npm install -g https://github.com/AI-BizOS/cross-harness/releases/download/v0.2.0/bizos-ai-cross-harness-0.2.0.tgz
cross-harness detect           # shows which agents cross-harness found

Or from source:

git clone https://github.com/AI-BizOS/cross-harness.git
cd cross-harness
npm install -g .        # installs the `cross-harness` command; there are no dependencies

Update with cross-harness update (--check only reports a newer release); a source checkout is updated with git pull. The terminal UI and the web UI also mention a newer release, after checking GitHub at most once a day. The user guide covers installing, everyday use and troubleshooting step by step.

cd your-project
cross-harness                  # terminal UI
cross-harness gui              # or: web UI in your browser

Then type a message that starts with the agents you want:

@codex fix the failing test in src/parser
@claude add edge-case tests for the parser; ask codex if the error format is unclear

Approve what they ask for, watch them work, press d to see an agent's changes and m to review and merge them.

Mentions count only at the start of a line.

Type in the composer; press Esc to switch to keys, i or Enter to type again.

Chinese and other wide characters are measured correctly; NO_COLOR is respected; --lang zh (or a Chinese locale) switches the interface to Chinese.

cross-harness gui serves the same features on 127.0.0.1 and opens your browser. The address carries a random token in its fragment; requests without it, from another origin, or with an unexpected Host header are refused. It works on a phone-sized window and follows the system's light or dark theme.

cross-harness run "@codex @claude review the last commit" --json
cross-harness run "@codex fix the lint errors" --yes --timeout 900

run sends the message, waits until every agent it reached is idle, and prints the answers. It never waits for a person: requests a mode would ask about are denied unless you pass --yes.

cross-harness --ssh dev@buildbox --cwd src/shop-api
cross-harness gui --ssh dev@buildbox --cwd src/shop-api

The interface stays local; the engine, the agents and the worktrees run on the remote host (which needs cross-harness installed). A relative --cwd starts from your home directory there. The connection is the plain ssh command in batch mode: your SSH config, keys, agent and jump hosts apply, password prompts do not, so use key-based login.

A goal is a short document: the outcome, acceptance criteria, boundaries, open questions and who works on it.

{
  "title": "Parser reports line numbers",
  "outcome": "Every parse error says on which line and column it happened.",
  "criteria": [
    { "id": "tests", "text": "The test suite passes", "check": { "run": "npm test" } },
    { "id": "review", "text": "Readable, public API unchanged", "review": { "by": "codex" } }
  ],
  "assignees": ["claude"]
}

Before it can start, the goal needs an independent check (a command or a review by another agent), answers to its open questions, and your approval of that exact revision. While it runs, cross-harness checks the agent's worktree after every turn and sends failures back, up to maxIterations. A merge waits until the checks pass on the tree being merged. Press g in the terminal UI (or open Goals in the web UI) to write, draft with an agent, approve, start and check goals.

All 13 built-in integrations have passed end-to-end checks with real agent installations. Windows workflows have also passed end-to-end checks. The deterministic automated suite uses mock agents to exercise protocol and engine behavior separately from those real-agent checks. See docs/providers.md.

cross-harness detect finds an agent on your PATH, in its installer's own folder (Kimi Code's ~/.kimi-code/bin), or where npm, nvm, pnpm, volta, bun, Homebrew and other managers put commands, and it runs DeepSeek Harness from its desktop app when no dsh command is registered. If an agent you installed is missing, see the guide.

The BizOS CLI, BizOS Code, is built in as @bizos. cross-harness starts it in its Agent Client Protocol mode (bizos acp), so it takes tasks, asks and answers other agents, and goes through the same approvals, reviews and goal checks as every other agent, while the runner behind it stays closed source.

curl -fsSL https://bizos-ai.com/code/install.sh | sh    # Windows: irm https://bizos-ai.com/code/install.ps1 | iex
bizos login
mkdir -p ~/.cross-harness/worktrees && bizos sandbox grant-write ~/.cross-harness/worktrees

BizOS Code runs its agent in an operating-system sandbox that reads and writes only where you allowed it. The last line, run once while BizOS Code is idle, lets it work in the worktrees cross-harness gives it and reach the other agents through its mailbox, which cross-harness keeps in the same directory; cross-harness's own configuration, goals and transcripts stay outside. With --shared, also grant the project directory. If cross-harness runs from a source checkout instead of an installed package, let BizOS Code read the checkout too (bizos sandbox grant-read <dir>), so it can start cross-harness's collaboration tools.

@bizos fix the failing test in src/parser
@bizos @codex review the last commit

Any other closed-source agent runtime can join the same way without publishing its code. Make it speak a session protocol — the Agent Client Protocol is the simplest — and register it in ~/.cross-harness/config.json:

{
  "providers": {
    "acme": { "name": "Acme Agent", "command": "acme-agent", "args": ["--acp"], "protocol": "acp" }
  }
}

@acme then works like any other agent. See docs/providers.md.

~/.cross-harness/config.json (or $CROSS_HARNESS_HOME/config.json):

{
  "defaults": { "mode": "workspace", "isolation": "worktree", "maxPerProvider": 3, "idleMinutes": 15 },
  "providers": { "codex": { "args": ["-c", "model_reasoning_effort=high"] } },
  "lang": "zh"
}

Only this user-level file can name commands to run. A repository cannot make cross-harness execute anything by itself; goal checks run only after you approve the goal.

Once, after your first merge or the third time you open it, the terminal UI or the web UI asks whether you would like to star cross-harness on GitHub; it opens the page only if you choose to and sends nothing. "Later" asks again in two weeks; "Star on GitHub" and "Don't ask again" are final. "starPrompt": false in this file, or CROSS_HARNESS_NO_STAR_PROMPT=1, turns it off; cross-harness run and CI never ask.

At most once a day, the terminal UI and the web UI read this repository's release tags (git ls-remote, so git's proxy settings apply) and mention a newer release. "updateCheck": false, or CROSS_HARNESS_NO_UPDATE_CHECK=1, turns that off; cross-harness run and CI never check.

• Agents run as you, with your credentials; cross-harness adds no privileges. Use the permission modes and each harness's own sandbox to limit them.
• The only network request cross-harness makes by itself is the daily release check above, which reads public tags and sends nothing about you or your projects.
• In workspace mode an agent's edits are automatic only inside its own worktree; edits anywhere else, or inside .git, are asked. "Always allow" for a command covers that command, never one chained, piped or redirected after it.
• Output from agents is treated as untrusted text: terminal escape sequences are stripped and the web UI never inserts it as HTML.
• The web UI listens only on this machine (127.0.0.1 unless you choose ::1 or localhost), requires a random token, checks Host and Origin, and sends a strict Content-Security-Policy.
• Agent mailboxes are private (0700/0600), requests are authenticated with a per-agent token, and links planted in a mailbox are never followed.
• See SECURITY.md for reporting.

• cross-harness drives agents through their protocols. Agents without one run one-shot (no live session, no approvals, no collaboration tools).
• The built-in integrations are end-to-end tested. New custom definitions or changed commands still need their own checks; vendor updates may require argument adjustments.
• Windows workflows have passed end-to-end checks. The selected agents must still be installed and signed in on that machine.
• There is no built-in editor, terminal, pull-request integration or usage billing.

npm test        # node --test; every harness protocol is exercised with mock agents

The browser test also runs when CROSS_HARNESS_PLAYWRIGHT points at a Playwright installation. The animations in this README are recorded from the real interfaces by npm run media (tools/media). See CONTRIBUTING.md. Licensed under the Apache License 2.0.