cross-agent
Run headless Claude, Codex and Grok as one team: this MCP server lets a host session delegate work, monitor tasks, manage git/worktrees, enforce review and test gates, and run solo, dev-team or dev-team-engine workflows.
Inspect the active mode: loop text, roles, workspaces, sandbox defaults/prompts, git policy and project root.
List roles and their engine/model/effort bindings or per-seat bindings, with workspace and sandbox profiles.
Delegate a brief to a specialist in a working directory, optionally forcing model, engine, effort, branch, seat, resume or a writable worktree; returns a task id.
Wait for a task to settle, stall or time out and get the next call to make.
Check task status, runtime and recent engine event stream; it records stalls and revivals.
Read a settled task's full final message and engine session; running tasks return status.
Cancel a task and all tasks it delegated, returning one outcome per task.
List every project task newest-first after reconciliation, filtered by status.
Verify linked worktrees and exact branches, returning canonical paths or a refusal reason.
Run whitelisted git mutations in verified worktrees under locks and journaling, using the mode's git policy by default.
Run whitelisted git verbs at the project root under locks and journaling;
merge --ff-onlyenforces tested-head and review/waiver gates.Run configured test or setup commands by selector at root or verified worktree, returning exit code and output, and journal tested/tests-passed steps.
Waive the merge review guard for a task's branch head, as operator or as lead under
review.afterResolverlead-decides after all seat reviews.
Owns git on behalf of the team: worktree creation and root repository operations are performed through the server's git_mutate and git_root tools and journaled per task, specialists are never allowed to write git metadata, and merges are gated by guards requiring a passing test suite on the exact branch head plus clean reviews (or a recorded waiver).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cross-agent Have Codex review src/parser.ts and summarize what it finds."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
cross-agent
Run headless claude, codex and grok processes as one team, from whichever of the
three you work in, or from OpenClaw. cross-agent is an MCP server and a launcher skill: your session, the
host, hands work to other engines, each running headless in its own CLI's sandbox on
your own subscription, and a mode decides the team — its roles, the loop its lead runs,
and its git policy.
Mode | The team | The loop runs in |
| one consultant: another engine reads and answers, or takes one change in a worktree of its own | your session |
| planner, plan reviewer, implementer, as many code reviewer seats as you bind, and a resolver; the planners read the project, and each task's change is made and reviewed in a git worktree of its own | your session |
| the same team | a Claude or Codex lead the server launches, so your session stays free |
A git repository with no cross-agent config runs as solo, so a one-off delegation needs
no setup.
How it works
One server, four hosts. The same MCP server and skill attach to Claude Code, Codex, Grok and OpenClaw, which runs
soloanddev-team-engine..cross-agent/config.jsonbinds each role to an engine, a model and an effort.Authority from process ancestry, not tokens. Your session gets the operator's tools, a lead the loop's, and a specialist a few read tools and never
delegate, so no delegation loop can form.Every specialist in its engine's sandbox. It writes only its own workspace, and it is denied launching
claude,codex,grok, this server or its CLI.Git stays with the server. Specialists never write git metadata; worktree and root git go through the server's
git_mutateandgit_root, journaled per task.Two merge guards. A merge needs the configured test suite to have passed on that exact branch head and, for a team task, a clean review from every reviewer seat, or your recorded waiver.
Related MCP server: Rutherford MCP Server
Requirements
Linux,
git, Node.js 24 or later, and util-linuxflock. There are no other dependencies: Node runs the TypeScript sources directly.The engine CLIs your roles use —
claude,codex,grok— installed and signed in.Each engine's sandbox prerequisites, such as
bwrapandsocatfor Claude: Linux prerequisites.
Install
Claude Code and Codex install it from the agent-plugins marketplace; Grok attaches it per project from a clone of this repository; OpenClaw installs it from the marketplace's git source. docs/install.md has every step, check and removal, and the installs from a clone.
Claude Code, in a session:
/plugin marketplace add WSH95/agent-plugins
/plugin install cross-agent@agent-pluginsKeep the default user scope, or use --scope local for one project; never
--scope project, which every Claude specialist would load.
Codex:
codex plugin marketplace add https://github.com/WSH95/agent-plugins
codex plugin add cross-agent@agent-pluginsThen ask Codex: "Use cross-agent to set up its MCP connection once for this host."
The skill configures MCP for the CLI and local Linux desktop Codex. Restart MCP or open
a new session afterwards. Each chat uses its own project; no per-session
CROSS_AGENT_PROJECT or versioned cache path is needed. Install and update the plugin
through the marketplace as usual; the connection follows the installed version.
Grok: clone this repository and name it in the project's own .grok/config.toml:
Install it in Grok.
OpenClaw (solo and dev-team-engine): install the plugin from the marketplace's git
source and register the server with its cwd the project:
openclaw plugins install cross-agent --marketplace https://github.com/WSH95/agent-plugins --force --accept-capabilitiesInstall it in OpenClaw has the server entry and the rest.
Quick start
Ask another engine, with no project setup. In any git repository, after attaching the plugin, ask your session, for example: "Use cross-agent to have Codex review src/parser.ts and tell me what it finds."
Run a team. Once per project, set it up in your host: /cross-agent:setup in Claude
Code, $ and the setup skill in Codex, /setup in Grok, /skill setup in OpenClaw, or say
"set up cross-agent". It
proposes a team — the mode, and the engine, model and effort of each role — from the
engines you have installed, and writes .cross-agent/config.json and two .gitignore
lines only once you confirm. Ask for setup again to change the team later.
Setup offers to commit that change. Commit that .gitignore change before the team's
first task if you decline: a loop's first step stops unless git status --porcelain --untracked-files=normal prints nothing at the project's root. Reconnect when setup says
so — the server reads the mode once, when it starts; in Claude Code, /mcp, choose
cross-agent, Reconnect, since /reload-plugins does not restart the server — and ask for
the work, for example:
"Use the cross-agent dev team to add a --json flag to the export command." Under dev-team your session runs the loop — plan, plan review, implementation
in a worktree, parallel code review, fixes, a tested merge. Under dev-team-engine a lead
runs it and puts its questions to you, which you answer with cross-agent answer.
docs/operator-guide.md covers the team's settings, the merge guards and the waiver, and running teams on several branches at once.
The operator CLI
The CLI ships inside the plugin, so it needs no separate install, but installing the
plugin does not put a cross-agent command on your shell's PATH:
In Claude Code the plugin's
bin/cross-agentis on the session's Bash toolPATH: ask Claude to runcross-agent report.In Codex the skills find the bundled CLI relative to their installed directory.
In OpenClaw the skills run the plugin's
bin/cross-agent, in~/.openclaw/extensions/cross-agent, from the project's root, since OpenClaw puts no plugin'sbin/on its shell'sPATH.From a terminal run the installed copy's launcher, for example
~/.codex/plugins/cache/agent-plugins/cross-agent/<version>/bin/cross-agent, or link a clone'sbin/cross-agentonto yourPATH.
Setup runs init for you; from a terminal, cross-agent init --mode dev-team writes a
mode's defaults. solo works without a config
after the one-time Codex setup. The rest is optional, since your session reaches the same operations
through the plugin's tools:
Command | What it does |
| what the team is doing |
| every task, its outcome and its final message |
| a lead's questions to you |
| stop a task and everything it delegated |
Every verb and its exit codes: The operator CLI.
Documentation
docs/install.md: installing, checking and removing it per host; the Linux prerequisites; installs from a clone.
docs/operator-guide.md: team configuration and the merge guards, every CLI verb, several branches at once.
docs/design.md: the design, which is authoritative, and docs/probes.md: what each engine CLI was observed to do.
Development
npm test # the suite, node:test
node tools/build-dist.mjs # the Claude and Codex payloads, from HEAD, into dist/cross-agent
python3 tools/publish_agent_artifact_pr.py --dry-run # preview the agent-plugins pull requestA release bumps the version in package.json and both plugin manifests (Claude Code keeps
users on their cached copy until it changes), commits, and pushes main. Then
python3 tools/publish_agent_artifact_pr.py --build --commit-message "…" --pr-title "…" --pr-body "…" --keep-temp builds the payloads from that commit and opens the pull request,
which replaces cross-agent/ alone: the marketplace's root entries for cross-agent came with
its first publication.
License
MIT. See LICENSE.
Available Tools
13 toolscancelA
Terminate a task and every task it delegated, leaves first, returning one outcome per task. A lead may cancel only its own.
Inputs: task_id (required).
checkC
The status of a task, how long it has been running, and the last lines of its engine's own event stream. Reconciles nothing, and records the stall or the revival its clock reads.
Inputs: task_id (required), lines.
delegateC
Launch a specialist for a role on a brief in a working directory, returning its task id. Validates the role, the workspace, its reservation, duplicates and the resume binding first. A role with no binding takes its engine in the call; worktree: true gives a role that works at the project root a writable task worktree of its own instead. A role bound to a list of bindings is delegated by seat, 1-based.
Inputs: cwd (required), role (required), brief (required), seat, +7 more.
describe_modeA
The active mode's loop text, its roles with their workspace, sandbox default and prompt, its git policy, and projectRoot, the root of the project this server serves. Call this first: it is how a launcher learns the loop, which is served rather than copied. review carries the loop's two settings, limits.planReviewRounds and review.afterResolver.
Inputs: no named parameters.
git_mutateB
Run one git subcommand in a verified worktree, under the project's locks and journaled. The only path that writes a worktree's git metadata; the workspace and branch default to the mode's own git policy.
Inputs: args (required), slug (required), path, branch.
git_rootA
Run one whitelisted git verb at the project root, under the project's git lock and, for a verb that changes the repository, the repository's own lock, and journal the step it completes. A merge --ff-only refuses a head without a tested step (unless testCommand is none), and for a team task in a gating mode, without every seat's clean review or a waiver. The verbs are worktree add -b, worktree remove, branch -d, merge --ff-only, rebase --abort, and the read-only status, log, rev-parse, rev-parse --abbrev-ref HEAD, merge-base, branch --list and worktree list; a verb that journals a step names the slug whose journal it belongs to.
Inputs: args (required), slug.
list_rolesC
The roles the active mode has: each one's workspace and the sandbox profile it will run under, with the engine, model and effort .cross-agent/config.json binds it to — or binding: null where it binds none, which is the engine a delegate call must name itself. A role bound to a list is answered as seats, each with its own engine, model, effort and sandbox.
Inputs: no named parameters.
list_tasksC
Every task of this project after a reconciliation pass, newest first, with the records no reader could judge.
Inputs: status.
resultB
The final message of a settled task in full, with the engine session it ran under. A task still running answers with its status.
Inputs: task_id (required).
run_commandA
Run this project's configured test or setup command — by selector, never as a command string — at the project root or for a verified worktree, returning the exit code and the last 64 KB of its output. Worktree tests run in a detached checkout of the branch head under .cross-agent/gate/ and journal tested on success. A passing test run at the root after the merge journals the slug's tests-passed step.
Inputs: where (required), which (required), slug, timeout_seconds.
verify_worktreeC
Verify a linked worktree and its exact branch, returning canonical Git and worktree paths or a refusal reason.
Inputs: path (required), branch (required).
waitB
Wait for a task to settle, for its engine to go quiet for the configured stall threshold, or for the timeout, and answer with the call to make next. A lead may wait only on a task it delegated.
Inputs: task_id (required), timeout_seconds.
waive_reviewB
Record the waiver of the merge's review guard for a task's branch head, as a review-waived step in its journal: git_root merge then takes that head without every seat's clean review. The commit must name the branch head as it stands. The operator's, and a lead's only under review.afterResolver lead-decides once every seat has finished its review of that head.
Inputs: slug (required), commit (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools target distinct resource+action pairs, but the task-inspection cluster (wait, check, result, list_tasks) has some conceptual overlap, and git_mutate vs git_root differ mainly by scope rather than action. Descriptions do clarify the boundaries (wait = block until settle, check = status snapshot, result = full final message), so an agent can generally choose correctly.
The set mixes compound verb_noun names (list_roles, list_tasks, verify_worktree, git_mutate, run_command, waive_review) with bare verbs/nouns (delegate, wait, check, cancel, result) and a describe_mode outlier. It remains readable, but there is no single predictable pattern.
13 tools is a reasonable scope for an orchestration server covering mode/role discovery, task lifecycle, git, worktree, and review concerns. Each tool earns its place, though the inspection tools are slightly numerous for their overlap.
Coverage is strong: role/mode discovery, full task lifecycle (delegate, wait, check, result, cancel, list_tasks), worktree verification, git mutation at both root and worktree, test execution, and review waiver. Gaps are minor, e.g. no obvious tool for reading or replying within a running task's stream beyond check.
Related MCP Connectors
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Git collaboration for AI agents and people: tasks, hand-offs, reviews, teams, shared memory.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Multiplayer for the coding agents your team already uses: shared tasks, decisions, skills and tools.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceOrchestrates multiple AI models (Gemini, OpenAI, Claude, local models) within a single conversation context, enabling collaborative workflows like multi-model code reviews, consensus building, and CLI-to-CLI bridging for specialized tasks.-
- AlicenseAqualityBmaintenanceEnables one AI coding agent to delegate tasks to, and build consensus across, multiple other coding CLIs (Claude Code, Codex, etc.) by orchestrating them as headless subprocesses.197MIT
- AlicenseNot gradedqualityAmaintenanceEnables coordinating Claude Code and Codex across separate Git worktrees with shared issue ownership, file reservations, messages, and explicit handoffs.213 PyPI3MIT
- AlicenseNot gradedqualityCmaintenanceEnables multiple AI coding CLIs (Claude Code, Gemini/Antigravity, Codex, and OpenCode) to collaborate as a coordinated team by routing cross-agent prompts, sharing messages and review tickets, tracking tasks on a shared store, and isolating each agent in its own Git worktree with turn-budget safeguards—all inspectable and steerable from a local web dashboard.MIT