agents-bridge-mcp
This MCP server lets you delegate questions, reviews, explanations, planning, performance analysis, and code edits to OpenAI Codex as a second AI opinion.
Ask Codex anything (
codex_query): pose a question or task, optionally choosing a model (gpt-5.3-codex,gpt-5.2-codex,gpt-5.1-codex-max), sandbox level, and working directory.Review code (
codex_review_code): get actionable feedback on a git diff range, file paths, or a snippet, with optional context and focus areas (bugs, performance, security, style).Critique a plan (
codex_review_plan): surface gaps, risks, missing edge cases, and improvements in an implementation plan, given constraints and codebase path.Explain code (
codex_explain_code): get an overview, detailed walkthrough, or full execution trace of a file, function, module, or snippet.Plan performance work (
codex_plan_perf): identify bottlenecks and get ranked optimizations targeting latency, throughput, memory, or binary size.Implement changes (
codex_implement): have Codex write code for a feature or bug fix, returning a summary of what changed (writes to your codebase; sandbox must allow writes).
All tools are read-only by default except codex_implement, and each accepts a workingDirectory to scope the work.
Enables Claude Code to delegate tasks to OpenAI Codex CLI, including asking questions, reviewing code and plans, explaining code, planning performance improvements, and implementing changes.
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., "@agents-bridge-mcp have codex review the diff on my current branch"
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.
AgentMate
AI agents work better together.
AgentMate connects AI coding agents so they can collaborate, delegate, review, and help each other complete tasks. Give your AI agent a teammate: let Claude Code and the Codex CLI ask, review, research, plan, implement, cross-review and lead each other as background jobs.
Why AgentMate
A second opinion from a different model. Ask the other CLI a question, or have it review your diff, before you commit to an approach. It reads your repository; it does not share your session's assumptions.
More than two CLIs. Besides Claude Code and Codex, AgentMate also drives the Gemini CLI and the Antigravity CLI (
agy), the same one the author's agy-staff plugin is built on. Both are experimental teammates: tested with fake binaries, never against the real CLIs.Work that does not block you. Every task is a durable background job with an id. The session that started it can end, and the result is still there.
Roles instead of raw prompts.
ask,review,research,plan,implementandteamleadeach send a tuned prompt with a defined output format, and each runs with the narrowest permissions that role needs. Jobs are read-only unless you say otherwise.crossreviewchains two of them: one agent implements, the other reviews, and the loop runs without you relaying anything.splitdivides a broad goal into independent parts that both agents work on in parallel and review each other's, sharing context through sessions.
Related MCP server: claude-code-codex-agents
60-second quickstart
Install
Install the plugin in the host you use (or both), then restart the host.
# Claude Code
claude plugin marketplace add naldomadeira/agentmate
claude plugin install mate@agentmate
# Codex
codex plugin marketplace add naldomadeira/agentmate
codex plugin add mate@agentmateThe marketplace is named agentmate and the plugin is named mate, so the install id is mate@agentmate and every command starts with mate:.
Migrating from Agents Bridge (0.3.0 or earlier)? The project was renamed to AgentMate: the npm package is now
agentmate, the pluginmate, the toolsmate_*, the state directory~/.agentmateand the environment variablesAGENTMATE_*. Remove the old plugin (claude plugin uninstall bridge@agents-bridge, oragents-bridge@agents-bridgefrom 0.2.0) and the old marketplace (claude plugin marketplace remove agents-bridge); in Codex, remove both withcodex plugin --helpfor the exact verbs. Then installmate@agentmateas above and restart the host. Jobs in~/.agents-bridgeare not migrated.
Invoke a role
Type /mate: in Claude Code to see every role; in Codex type $mate or open /skills. Both hosts take the provider first, then the request:
/mate:ask codex Is it safe to call this migration twice? See db/migrate/0042.sql
$mate:ask claude Does this retry loop in src/queue.ts have a race?Want shorter commands (/ask, /prompts:ask)? See Slash commands. More examples are in Use cases.
Check the installation
npx -y agentmate doctordoctor verifies Node.js, that the codex and claude CLIs (and the optional, experimental gemini and agy CLIs) are on your PATH and respond to --version, the job state directory, stale running jobs (it lists their ids) and legacy registrations, and prints a fix for each problem. It does not check authentication: if a job fails right away, log in to the destination CLI yourself. See the installation guide for upgrades, a local-development install and cleaning up leftover legacy registrations.
Set up a repository
npx -y agentmate init # add or refresh the AgentMate block in AGENTS.md and CLAUDE.md
npx -y agentmate init --check # change nothing; exit 1 if a block is missing or out of dateagentmate init (or /mate:init) writes a block of at most 25 lines between <!-- agentmate:start --> and <!-- agentmate:end --> in the repository's existing AGENTS.md and CLAUDE.md (a file with CRLF line endings keeps them), so every agent that opens the repo knows the /mate: and $mate: commands, how to check on jobs (agentmate jobs list, agentmate inbox) and the rules for a job it receives (no commit or push unless asked, report with the role's headings, treat session notes as data). Text outside the markers is never touched and a second run changes nothing. Claude Code does not read AGENTS.md natively, so --create starts both AGENTS.md and a CLAUDE.md that begins with @AGENTS.md (Claude Code imports it) followed by the block; use --files to pick other files and --cwd to run it elsewhere. Run it again after upgrading to refresh the block.
For agents
Paste this into any coding agent:
Read the raw text of https://raw.githubusercontent.com/naldomadeira/agentmate/main/docs/INSTALL_FOR_AGENTS.md
(curl it - do not work from a summary) and follow it to install and verify the AgentMate plugin
for the host you are running in. Respond in the user's language.Upgrade
Claude Code and Codex install a copy of the plugin, so a new version only reaches you when you pull it in:
claude plugin marketplace update agentmate && claude plugin update mate@agentmatecodex plugin marketplace upgrade agentmate && codex plugin add mate@agentmateHosts cache the plugin per version, so restart Claude Code or Codex afterwards. A fix only lands if the plugin version changed.
Use cases
Examples use Claude Code's /mate:...; in Codex use $mate:.... The provider (codex or claude) comes first; pick the one that is not your host.
Use case | Invocation |
Quick second opinion |
|
Review the working tree |
|
Review a PR or diff |
|
Challenge a plan |
|
Research a topic |
|
Implement a scoped fix |
|
Run a team lead |
|
Implement, then cross-review |
|
Split a goal across both agents |
|
Job ops |
|
implement and crossreview edit files, and split does when you pass --mode write, so use them only when you authorize that. The others are read-only.
Teammates
Teammate | Provider id | Needs | Notes |
Claude Code |
| the | Reads with an explicit tool allowlist; web access in |
Codex CLI |
| the | Sandboxed by mode; no web access. |
Gemini CLI (experimental) |
| the | Runs |
Antigravity CLI (experimental) |
| the | Runs |
Grok Build CLI (experimental) |
| the | Runs |
Cursor CLI (experimental) |
| the | Runs |
GitHub Copilot CLI (experimental) |
| the | Runs |
A job on an agent that is not installed is refused up front with an install hint, and agentmate doctor lists each agent (a missing Gemini or Antigravity CLI is reported as optional, for example ok agy not installed (optional)). teamlead, crossreview and split pair the provider with the first installed other agent (in the order codex, claude, gemini, agy, copilot), resolve and check it before anything starts, and record it as the job's partner. Pass partner (mate_teamlead, mate_crossreview, mate_split, or jobs start --partner <agent>) to pick the other agent yourself, for example /mate:crossreview codex <task> with partner: gemini to have Gemini review Codex's change. The partner must differ from the provider and be installed. Gemini limits, in short: it cannot run shell commands (reviews of its changes or by it get the diff inline, capped at 30 000 characters, and an implement job cannot run the tests), it cannot search the web, it cannot continue a job, and as a team lead it needs mode: write. agy shares the diff-inline, no-web and write-only team lead limits, but it can continue a job; its read-only results depend on the permissions of your agy profile (see the table above).
What you can do
Eight roles, each reachable as a skill, an MCP tool and a CLI command. <provider> is codex, claude, gemini, agy or copilot (the last three experimental); pick the one that is not the host you are in.
Role | Skill | MCP tool | CLI | Mode |
|
|
|
| read-only |
|
|
|
| read-only |
|
|
|
| read-only (Claude adds web access) |
|
|
|
| read-only |
|
|
|
| write (always) |
|
|
|
| read-only by default, write opt-in |
|
|
|
| write on the implementer, read-only review |
|
|
|
| read-only by default, write opt-in (one git worktree per part) |
mate_ask waits for the answer (up to 120 seconds by default) and returns it in the same call. The other role tools return a job id immediately unless you pass waitSeconds.
mate_implement accepts verify, and jobs start --role implement accepts --verify <command>. AgentMate runs it with sh -c in the job directory only after the provider reports success. A non-zero exit or timeout leaves the result text intact but ends the job needs_attention; mate_result and jobs result show the command and its output tail under Verify. verify is rejected for read-only roles.
mate_implement and mate_teamlead also accept allowPush; the CLI equivalent is jobs start --allow-push. It is off by default and available only to Claude and Copilot write jobs. It permits only a normal git push, sets GIT_TERMINAL_PROMPT=0 so credential prompts fail fast, denies force variants, and tells the worker to report the pushed ref. Codex, Gemini and agy refuse it: push from the coordinator after the job.
Codex limits an MCP tool call to about 60 seconds by default. When you run inside Codex, pass waitSeconds: 45 to mate_ask and continue with mate_wait if the answer has not arrived.
Six more skills cover the rest:
jobslists, observes, collects and cancels jobs, and inspects models viamate_models.delegateis the generic path (mate_start) for work that fits no role.codex,claude,gemini,agyandcopilot(the last three experimental) are shortcuts that route a plain request to the right role with the provider already set.initsets up a repository for AgentMate (see Set up a repository).
In Claude Code the plugin also adds four agents that wrap Codex: codex-teammate (questions and general delegation), codex-reviewer, codex-researcher and codex-teamlead. They brief Codex, verify what it returns and report their own conclusion instead of forwarding raw output.
Every command in the table works without MCP. Prefix CLI commands with npx -y agentmate.
Slash commands
Nine commands (ask, review, research, plan, implement, teamlead, crossreview, split and jobs) can be started as a command in either host. Both hosts take the provider first, then the request.
Host and style | How to invoke | How to get it |
Claude Code plugin |
| Installed with the plugin. |
Claude Code bare |
|
|
Codex skill |
| Installed with the plugin; or pick "Mate: Ask" from the |
Codex slash |
|
|
The plugin forms (/mate:ask, $mate:ask) need no extra install. The bare /ask and /prompts:ask rows are optional extras. Why two steps: Claude Code always prefixes plugin skills with the plugin name, so a bare /ask needs a user-level command file. Codex plugins can ship skills but not slash commands, so /prompts:<name> comes from a custom prompt file in $CODEX_HOME/prompts/ (default ~/.codex/prompts/).
npx -y agentmate install commands [claude|codex|both] [--global|--local] copies the templates from the package (templates/claude-commands/ and templates/codex-prompts/) and prints the command names it installed. The default target is both. It asks before overwriting an existing file. --local installs the Claude Code commands to ./.claude/commands/; Codex custom prompts are user-level only, so they are always installed globally.
Codex custom prompts are deprecated. OpenAI marks them deprecated in favour of skills. They still work today, and the
$mate:askskill needs no extra install, so use whichever you prefer. Restart Codex after installing prompts.
Each command calls the same mate_* tool as its skill, falls back to the npx -y agentmate jobs ... CLI when MCP is not loaded, and points to the skill for the full rules. jobs takes a verb instead of a provider: /jobs list, /jobs observe <id>, /jobs result <id>, /jobs cancel <id>.
Team lead mode
A team lead is a job whose worker plans a broad objective, delegates pieces to the other provider through the CLI, reviews the results and writes a report. You start it with mate_teamlead or the teamlead skill and follow it with mate_observe. The lead delegates to partner when you pass one (for example a claude lead with partner: gemini); the default is the first installed other agent.
your session
`-- teamlead job (depth 0, started by you) codex lead: danger-full-access
|-- research job (claude) depth 1, cannot start jobs
|-- review job (claude) depth 1, cannot start jobs
`-- implement job (claude) depth 1, write, one per working treeThe stored depth is 0 for a job started by a session and 1 for a job started by a worker. The limit is two levels: a session starts a team lead, the lead starts child jobs, and the children cannot start jobs.
The final report has the sections Objective, Plan, Delegations (id, provider, role, status), Findings, Decisions, Deliverables and Open questions. jobs observe <id> shows the lead's output with its children; jobs list --parent <id> lists only the children.
Codex sandbox warning. A Codex team lead runs with
--sandbox danger-full-accesswhethermodeis read-only or write. It has to start worker processes and write job state under~/.agentmate, so the sandbox cannot be narrower. In read-only mode the runtime refuses anywritechild job and the prompt forbids edits, but the lead itself is not sandboxed. Treat a Codex team lead like any Codex session with full filesystem access, or lead withclaudeinstead, whose permissions are an explicit tool allowlist that includes an explicit deny ofEdit,WriteandNotebookEditin read-only mode.
The team lead calls the CLI pinned to the installed version (npx -y agentmate@<version> jobs ...), so a local checkout that is not published to npm must be published or linked before team lead mode works.
Gemini team lead warning (experimental). A
geminiteam lead is accepted only withmode: write, because delegating needs the shell and Gemini allows it only in--approval-mode yolo, which approves every tool call without asking. A read-only Gemini lead is refused (A Gemini team lead needs mode write: delegation requires the shell, which Gemini only allows in yolo mode.). Treat it like the Codex lead above, or lead withclaude.
agy team lead warning (experimental). An
agyteam lead is accepted only withmode: write, because delegating needs the shell and headless agy allows it only with--dangerously-skip-permissions, which skips every permission check. A read-only agy lead is refused (An agy team lead needs mode write: delegation requires the shell, which agy only allows with --dangerously-skip-permissions.). Treat it like the Codex lead above, or lead withclaude.
Use a team lead only when the work has several independent parts. One question or one review is cheaper as ask or review.
Cross-review
Cross-review lets one agent implement and the other review, so you do not copy a diff between sessions. It is a workflow job: the worker does not call a CLI itself, it runs the steps as child jobs. provider implements; the other agent reviews (partner, when you pass one). Start it with mate_crossreview or the crossreview skill (/mate:crossreview codex <task>), and follow it with mate_observe.
implement (provider, write) -> review (other agent, read-only) -> verdict
^ |
| Verdict: request-changes, rounds left |
`---- implement --continue with the findings <---------------'
|
Verdict: approve -> doneEach round has two child jobs on the same working directory (depth 1, parentJob = the workflow id). The implementer runs in write mode; from round 2 it continues its own session with the reviewer's findings (an implementer that cannot continue, such as Gemini, starts a fresh implement job with the findings instead). The reviewer reads the uncommitted git diff (and git status for new files) read-only, or receives the diff in its briefing when it cannot run the shell (Gemini, agy), with the implementer's report as context, and must end its review with the line Verdict: approve or Verdict: request-changes. From round 2 the reviewer follows up the prior review: it reports each prior finding as resolved, not resolved or partially resolved, then checks only regressions introduced by the fix.
Stop rules:
Verdict: approveends the workflow asdone.Verdict: request-changesstarts another round while rounds remain (maxRounds, 1 to 5, default 2). When the budget is used up the workflow isdoneand the report says so; the latest edits stay in the working tree.No clear verdict ends the workflow at once as
donewith a## Needs humansection; it never loops blindly.A child that ends
error,needs_attention,timeoutorcanceledends the workflow aserror, naming that child's id and error. A child that endsquota_exhaustedends it aserrorwith that child's own error, which already says how to hand the work to the other agent. The workflow's own--timeoutis the overall deadline, andjobs cancel <id>on the workflow cancels its running children first (recursively), then the workflow itself.
The report (jobs result <id>) has ## Task, ## Rounds (round, implement job, review job, verdict), ## Final review, ## Changes, ## Needs human when it applies, and ## Next steps with the jobs result <child-id> commands. jobs events <id> lists one important event per step, such as round 1: review verdict approve.
npx -y agentmate jobs start codex "Add a --dry-run flag to the export command" --role crossreview --max-rounds 3It edits files, so start it only when you authorize that, and keep one write job per working tree. Only a top-level session can start it, like a team lead. --model applies to the implementer only.
Task splitting
Task splitting divides a broad goal into independent parts, runs the parts in parallel on both agents and has the other agent review each one, so you do not relay results between sessions. Like cross-review it is a workflow job: the worker calls no CLI itself, it runs the steps as child jobs (depth 1, parentJob = the workflow id) that share one session. provider plans; each part goes to an installed agent, or only to the provider and its partner when you pass one. Start it with mate_split or the split skill (/mate:split codex <goal>), and follow it with mate_observe.
goal -> plan (provider, read-only)
| 1..maxParts parts: closed interfaces, no overlapping files, one agent each
v
parts in parallel ---- read-only: a research job per part, on the working directory
| write: a git worktree + branch per part, an implement job in each
v
cross-review (the other agent of each part, read-only, Verdict: approve | request-changes)
|
v
integration report (parts table, merge order, what needs a human)Plan. A
planjob onproviderreturns a fencedjsonblock,{ "parts": [{ "id", "title", "briefing", "files", "agent" }] }, with 1 tomaxPartsparts (2 to 4, default 3). The worker takes the last such block and checks it: unique ids (a-z,0-9,-), known agents (a missing or unknown agent alternates, starting with the other agent). If the block is invalid the workflow endserrorwith a pointer tojobs result <plan-job>. The plan goes into the session notes, so every part sees it.Parts, in parallel. Read-only (default): one
researchjob per part on the part's agent, in the working directory. Write (--mode write): for each part the worker creates a worktree from the recorded base commit,git worktree add -b agentmate/<split-id>/<part-id> ~/.agentmate/worktrees/<split-id>/<part-id> <base-commit>, then animplementjob works there, so your working tree is untouched. When the implementer finishes, AgentMate commits what it left on the part's branch automatically (--no-verify, gpg signing off).Cross-review. Each finished part is reviewed read-only by the other agent of the pair (the provider or the partner): in write mode in the part's worktree, against the commit the branch started from (
git diff <base-commit>, or that diff inline when the reviewer is Gemini or agy and cannot run the shell); in read-only mode over the research result. The review ends withVerdict: approveorVerdict: request-changes.Report.
jobs result <id>has## Goal,## Parts(part, title, agent, part job, review job, verdict, branch),## Integration,## Needs humanwhen it applies and## Next stepswith thejobs result <child-id>commands. In write mode the report lists every worktree and branch with its cleanup commands (git worktree remove <path>,git branch -D <branch>),## Integrationhas the orderedgit merge agentmate/<split-id>/<part-id>commands for approved parts only, and every other part goes under## Needs human; in read-only mode it merges the research results.jobs events <id>lists oneimportantevent per step.
A part that fails does not stop the others: they run to completion (and are reviewed), then the workflow ends error naming the failed part. A part that is not approved (request-changes, a missing verdict or a failure) lands in ## Needs human. The workflow's own --timeout is the overall deadline, and jobs cancel <id> on it also cancels the running children.
Write mode limitations. It needs a git repository with a clean working tree, checked before the planner runs; commit or stash first. The worktrees are fresh checkouts: they have no node_modules, no .env and no submodule contents, so a part cannot run checks that need them unless its briefing says how to set them up.
What is not automated: AgentMate never merges, pushes, rebases or deletes branches for you, and merge conflicts between parts are not resolved automatically. Run the merges from the report yourself, resolve any conflict, run the tests, then remove the worktrees. There is no second round: a part with request-changes is for you (or a follow-up job) to fix.
npx -y agentmate jobs start codex "Add CSV and JSON export to the report command" --role split --max-parts 3
npx -y agentmate jobs start codex "Add CSV and JSON export to the report command" --role split --mode writeWrite mode edits files (in the worktrees), so start it only when you authorize that. Only a top-level session can start it, like a team lead. --model applies to the planner and to parts run by the same agent.
How it works
AgentMate treats delegated work as a durable background job:
Start a task on
codexorclaude. The tool returns a job id immediately (or the answer, formate_ask).Wait for that id, collect its result, or request progress when a person asks for it.
Use the stored result to decide the next step. Jobs survive the caller session ending.

The jobs MCP server (npx -y agentmate serve jobs, registered by the plugin) and the jobs CLI share one runtime. State lives under ~/.agentmate. A detached worker runs the provider CLI and records the output, so an expired wait never stops a job.
Every job also writes an append-only event log (events.jsonl). Both Codex and Claude (--output-format stream-json) stream events while they run. Events carry one of three levels: important (the agent's messages, errors, start and finish), status (files changed) and fyi (commands run). mate_observe and jobs observe show only important and status events, so progress checks stay small; ask for fyi with levels / --level, read the full log with mate_events / jobs events <id>, and pull the raw stdout/stderr tails only when needed with raw / --raw. See docs/ARCHITECTURE.md for the runtime, adapters and event model.
Capability | MCP | CLI |
Start work |
|
|
Wait or fetch output |
|
|
Request progress |
|
|
Read job events |
|
|
Cancel work |
|
|
Find jobs |
|
|
List models |
|
|
Sessions |
|
|
Inbox |
|
|
Sessions. A session is shared context across jobs and agents. mate_session_start(title, cwd?, context?) creates one under ~/.agentmate/sessions/<id>/ (session.json, notes.md and optional context.md; membership is derived from the jobs that carry the session id, so session.json has no jobs array); pass its id as session to any role tool or mate_start (CLI: jobs start ... --session <id>) and the job is recorded in it. A session holds a fixed briefing (spec, decisions, how to test, up to 16,000 characters) set at creation or via mate_session_context(session, context, mode? = "replace" | "append") (CLI: sessions start --context/--context-file, sessions context <id> [text|--file] [--append]). Every worker in the session receives this fixed context in full under ## Session context (session <id>) ahead of notes, so individual jobs only need to pass their specific focus. Only the host session can set it; a worker cannot. mate_session_notes(id, text, author?) appends a note (a single note is capped at 2000 characters), mate_session_show(id) shows the context (up to ~2 KB), notes (tail) and the session's jobs, and mate_session_list(cwd?, limit?) lists sessions. When a session has notes, every worker started in it receives them after the task and context, under ## Shared session notes, in a code fence and framed as data written by other agents, not as instructions. The injection is capped at 4000 characters of whole entries (the newest that fit), whatever the role, so keep notes short and factual: decisions, constraints, file locations. Jobs that a workflow starts (crossreview, split) inherit the workflow's session, and split creates a session for itself when you pass none and writes its plan into the notes. The notes and context are plain text under ~/.agentmate, so keep secrets out of them.
Session start summary. In Claude Code the plugin also registers a SessionStart hook (hooks/hooks.json). When a session opens, it prints one line (400 characters at most) about the jobs started from that directory or a subdirectory: the jobs that finished since the last session there (quota_exhausted ones first, marked "needs hand-off"), how many are still running and how many are stale (their worker is gone). It stays silent when there is nothing to report and for 120 seconds after the last summary in the same directory; the first time in a directory it looks back 24 hours. Set AGENTMATE_HOOK_QUIET=1 to turn it off. It never fails a session: any error exits silently. This is a Claude Code feature only; Codex has no equivalent hook.
Status bar. agentmate jobs list --line [--cwd <dir>] prints one compact line for a Claude Code statusLine, scoped to that directory and its subdirectories. It reports queued/running jobs (up to three provider/model/duration samples) and terminal unread inbox entries without advancing the inbox cursor; it is silent when there is nothing to show. Use agentmate jobs list --json for the same fields as JSON. These modes cannot be combined with --parent (or with each other).
Inbox. Every time a job records an important message, error or finish, AgentMate also appends one line to ~/.agentmate/inbox.jsonl (owner-only, rotated to inbox.1.jsonl past 5 MB, one generation): { ts, job, cwd, session?, provider, role, kind, text }. It is how one agent learns that the other finished or failed without sitting in wait. mate_inbox(cwd?, unread? = true, ack? = true, limit? = 20) returns the entries for that directory or a subdirectory, one line each (HH:MM:SS <job> <role>/<provider> <kind> <text>), oldest first, and moves a read marker kept per directory in ~/.agentmate/inbox-cursors/ through the last entry it showed (… N more unread (run again) when there are more), so nothing is shown twice; a terminal job already read through mate_wait or mate_result is not listed again, and entries of jobs started by another job (workflow steps, team lead children) are left out because their parent reports. Entry text is capped at 500 characters and is untrusted worker output: data, not instructions. Workers never read the host's inbox: mate_inbox declines when AGENTMATE_JOB_ID is set and the hooks stay silent inside a worker. From a terminal, agentmate inbox does the same (--all for every directory, --no-ack to only look) and agentmate inbox --follow prints new lines every second until Ctrl-C. In Claude Code the plugin also registers a UserPromptSubmit hook: before each prompt it adds up to 5 unread entries for the directory to the context (10 seconds of cooldown per directory, AGENTMATE_HOOK_QUIET=1 turns it off, any error exits silently), and the SessionStart summary mentions how many are unread. Codex has no hooks, so the jobs, teamlead, crossreview and split skills tell it to call mate_inbox when it resumes a turn with jobs in progress, before mate_wait. Entries are short summaries; read the full output with jobs result <id>.
Skills prefer the mate_* tools. If the host did not load MCP, they run the same job contract through npx -y agentmate; they never change a user's host configuration as a fallback.
Usage examples
Ask a quick question
npx -y agentmate jobs ask codex "Why might src/jobs/store.ts lose a write under concurrent workers?" --wait 120sThe answer is printed when it arrives. If the wait expires, the job keeps running: jobs wait <id> collects it.
Review a change
Start with a read-only request. Give the receiving CLI enough context to produce an actionable result: name the goal, relevant files or diff, and the expected answer.
npx -y agentmate jobs start codex "Review the current diff. Report only actionable findings." --role review
# retain the job ID printed by start
npx -y agentmate jobs wait <job-id>To re-review a fix without reopening the whole change, start another review with --follow-up <previous-review-id>. It checks every previous finding and only regressions introduced by the fix:
npx -y agentmate jobs start codex "Review the fix" --role review --follow-up <previous-review-id>After a plugin restart, the same workflow can be requested through the installed review skill or the delegate skill. The skill selects MCP when it is available and otherwise runs the CLI commands above.
Delegate an authorized edit
Jobs default to read-only, except implement, which always runs in write mode and rejects read-only. Use it only when the task is explicitly allowed to change files, and send one write job per working tree at a time. The --mode write flag is redundant for implement but makes the intent explicit.
npx -y agentmate jobs start claude "Add a focused regression test for the parser." --role implement --mode write --cwd .
npx -y agentmate jobs wait <job-id>Run a team lead
npx -y agentmate jobs start claude "Audit the CLI for inconsistent error handling and propose fixes. Delegate independent areas to codex." --role teamlead
npx -y agentmate jobs observe <job-id>
npx -y agentmate jobs wait <job-id> --timeout 10mCross-review a change
npx -y agentmate jobs start codex "Add a --dry-run flag to the export command" --role crossreview --max-rounds 3
npx -y agentmate jobs wait <job-id> --timeout 10m
npx -y agentmate jobs result <job-id>Codex implements, Claude reviews the uncommitted diff, and the report lists the rounds. Use jobs events <job-id> for the step-by-step log.
Split a goal across both agents
sid=$(npx -y agentmate sessions start "CSV and JSON export")
npx -y agentmate sessions notes "$sid" "Keep the CLI flags stable; formatters live in src/export/."
npx -y agentmate jobs start codex "Add CSV and JSON export to the report command" --role split --session "$sid"
npx -y agentmate jobs wait <job-id> --timeout 10m
npx -y agentmate jobs result <job-id>
npx -y agentmate sessions show "$sid"Codex plans the parts, both agents research them in parallel, and the report merges the findings. Add --mode write to implement each part in its own worktree and branch.
Continue, inspect, or cancel a job
An expired wait does not stop work. Repeat wait for the same ID, inspect output when progress is requested, or collect a stored result after an interrupted terminal session.
npx -y agentmate jobs observe <job-id>
npx -y agentmate jobs result <job-id>
npx -y agentmate jobs cancel <job-id>A finished job with a saved session can continue on the same provider (not available for gemini yet, whose --resume is unverified; start a new job with the full context. agy continues with --conversation <id>):
npx -y agentmate jobs start codex "Address the highest-priority finding." --continue <job-id>
| Meaning | Next action |
| Job completed | Read and assess the returned result. |
| Job failed, was canceled or hit its quota ( | Read |
| Wait expired while job remains active | Repeat |
jobs ask uses the same exit codes. Do not pipe wait or ask: a pipe discards the exit code.
jobs wait --timeout (for example 10m or 90s) only limits how long the command waits. To limit how long a job may run, pass jobs start --timeout <minutes>: a positive number of minutes, at most 120.
Reasoning effort
Pass effort (low, medium, high, xhigh) to any job-starting tool or --effort to jobs start / jobs ask:
Codex passes
-c model_reasoning_effort=<effort>onexecandexec resume.Claude passes
--effort <effort>.agy folds the effort into the model id (
<model>-<effort>, requiresmodel, acceptslow,medium, orhigh, e.g.gemini-3.1-pro+high→gemini-3.1-pro-high).Copilot passes
--reasoning-effort e, refused when no model orautois set.Gemini has no reasoning effort setting in headless mode and refuses it with a clear error.
Resuming with
--continueinherits the previous job'seffortandmodelunless overridden. Incrossreview,effortapplies to the implementer only. Insplit, it applies to the planner and same-agent parts.
Models and validation
Pass model / --model <id> to override the model. Inspect supported models and efforts with mate_models or npx -y agentmate jobs models [provider] [--refresh]:
agy queries
agy models, cached on disk for 6 hours in~/.agentmate/cache/models-agy.json(bypass withrefresh/--refresh).Codex reads
$CODEX_HOME/models_cache.jsonfor the job's account, listing supported reasoning levels.Claude, Gemini and Copilot are not checked (their CLIs do not provide a machine-readable model catalog; Copilot models depend on plan/policies,
autoalways works).Unknown models and unsupported efforts fail before dispatch with closest matches suggested. Set
AGENTMATE_SKIP_MODEL_CHECK=1to skip this check.
Accounts
For Codex or Claude, pass account / --account <name> to choose the account for that job:
Codex:
principal(ordefault) uses the defaultCODEX_HOME(~/.codex); a profile name uses~/.codex-profiles/<name>(override withAGENTMATE_CODEX_PROFILES);autorunslimites --json(override binary withAGENTMATE_LIMITES_BIN) and picks the suggested account, falling back toprincipalwith a note.Claude:
principal(ordefault) uses the main account and removesCLAUDE_CONFIG_DIRfrom the child environment. A name uses an exactAGENTMATE_CLAUDE_ACCOUNTSentry (name=/absolute/dir) when present, otherwise~/.claude-<name>; the directory must contain.claude.jsonorsettings.json.autois Codex-only.Resumed jobs (
--continue) enforce and inherit the original account. Incrossreview,accountapplies to the same-provider implementer and reviewer; insplit, to the planner, same-provider parts and reviewers.
Review with command execution
mate_review and jobs start --role review default to strict read-only inspection. Pass allowCommands: true or --allow-commands to widen the sandbox so the reviewer can run tests, builds, and verification commands:
Codex widens
--sandboxfromread-onlytoworkspace-write, so caches and local sockets work.Claude allows unrestricted
Bash; itsEdit,WriteandNotebookEdittools stay denied.Either way the reviewer can change files (through the shell or the writable sandbox); only its briefing forbids it. Use it only when you accept that, and check
git statusafterwards. The result header showscommands allowed.Gemini and agy refuse
allowCommandsbecause they lack shell capability in headless/read-only mode.The review prompt directs the reviewer to report concrete verification under
3. **Verified**(verified: <cmd> passed/failed) and4. **Not verified**.
Result header and listing
Job results (mate_wait, mate_result, jobs result) begin with a structured summary header:
job <id> · provider/mode [· role] [· <model> · <effort>] [· account <name>] [· commands allowed] [· in/out/reasoning tok] [· $cost] [· N premium request(s)] · <status> · <duration>s
When the CLI reports the effective model executed, the header displays ran <effective model> (asked <requested model>). Job listings (mate_list, jobs list) show model·effort (e.g. default·high or gpt-5·medium) for each entry.
Safety model
Read-only by default.
ask,review,planandresearchalways run read-only, andteamleadis read-only unless you passmode: write.implementalways runs in write mode:--role implementandmate_implementdefault to write and rejectread-only. Use it only after the user has authorized edits.Permissions per role. The sandbox or tool allowlist follows the role and mode:
Role and mode
Codex sandbox
Claude permissions
Gemini (experimental)
agy (experimental)
Copilot (experimental)
read-only (
ask,review,plan, read-onlyteamlead)read-onlyallowlist (below) and an explicit deny of
Edit,WriteandNotebookEdit--approval-mode defaultno permission flag (agy's own profile)
--deny-tool=write, onlyshell(git diff|log|show|status)allowedreview(allowCommands: true)workspace-writeallowlist with unrestricted
Bash, explicit deny ofEdit,Write,NotebookEditnot supported (no shell)
not supported (no shell)
--allow-tool=shell(whole shell),--deny-tool=writeresearchread-onlythe read-only allowlist plus
WebSearchandWebFetch, with the same explicit deny--approval-mode defaultno permission flag (agy's own profile)
same as read-only (no web)
implement, writeteamleadworkspace-writeacceptEditspermission mode plus the verification allowlist (below)--approval-mode auto_edit--dangerously-skip-permissions--allow-tool=writeplus the verification allowlistteamlead(Codex lead, read-only or write)danger-full-accessnot applicable
not applicable
not applicable
not applicable
teamlead(Claude lead)not applicable
the rows above, plus CLI access limited to
agentmate jobs *(installed version)not applicable
not applicable
not applicable
teamlead(Gemini lead, write only)not applicable
not applicable
--approval-mode yolonot applicable
not applicable
teamlead(Copilot lead, read-only or write)not applicable
not applicable
not applicable
not applicable
the rows above, plus
shell(agentmate:*)andshell(npx:*)teamlead(agy lead, write only)not applicable
not applicable
not applicable
--dangerously-skip-permissionsnot applicable
The read-only allowlist is
Read,Grep,Glob,git diff,git log,git showandgit status. The write-mode allowlist addspnpm,npm,npx,yarn,bun,make,git addandgit commitso a worker can run verification commands. Extend it with the environment variableAGENTMATE_CLAUDE_WRITE_TOOLS, a comma-separated list of Claude permission patterns. A Claude team lead cannot runinstall, onlyagentmate jobs *. Claude workers start with--strict-mcp-config, so none of your MCP servers (claude.ai connectors and plugins included) load into a job: they start faster and only have the tools above. SetAGENTMATE_CLAUDE_INHERIT_MCP=1to give workers your MCP servers. PassingallowCommandsonreviewwidens the sandbox (workspace-write on Codex, generalBashon Claude) so reviewers can run tests and verification commands requiring socket or cache writes; that also lets them change files, which only the briefing forbids; Gemini and agy have no shell capability in read-only mode and rejectallowCommands.allowPush/--allow-pushis a per-job, write-mode opt-in for Claude and Copilot only. It adds narrowly scopedgit pushpermission, setsGIT_TERMINAL_PROMPT=0, and explicitly denies--force,-fand--force-with-lease; it never enables pushes by default. Codex has a read-only.gitsandbox and no network, while Gemini and agy have no AgentMate per-command allowlist, so they reject the option; push from the coordinator after those jobs.Gemini runs with the least approval that fits the role (experimental).
--approval-mode defaultdenies every tool that needs approval in headless mode, so read-only and research jobs can read but not run shell commands or search the web;auto_editapproves file edits but still denies the shell, so animplementjob cannot run the tests. A Gemini team lead needs the shell, which only--approval-mode yoloallows: it is accepted withmode: writeonly, and it approves every tool call without asking, so it is as unrestricted as the Codex lead below.--sandboxand the legacy--yoloflag are never used.agy asks for nothing in read-only and for everything in write mode (experimental). Read-only jobs pass no permission flag, so headless agy denies the tool calls its own profile does not allow; a read-only job can therefore return thin results until you install the agy-staff allowlist or run in write mode.
--dangerously-skip-permissionsis passed to everymode: writejob, includingimplementand the team lead, and approves every tool call without asking, so it is as unrestricted as the Codex lead below. An agy team lead is accepted withmode: writeonly. agy has no--sandboxhere either.A Codex team lead is not sandboxed. It runs with
--sandbox danger-full-accessin either mode, because it must spawn worker processes and write job state. "Read-only" for a Codex lead means that the runtime refuses anywritechild job (a read-only parent cannot start write children) and that the prompt forbids edits; it does not restrict the lead's own process. Lead withclaudewhen this matters.Delegation depth limit of 2. A session starts a team lead (depth 0), the lead starts child jobs (depth 1), and children cannot start jobs. The runtime refuses a third level and refuses a team lead, a cross-review or a split started by a worker.
Cross-review writes only through its implementer. The
implementstep gets theimplementpermissions above; thereviewstep is read-only. The workflow job itself calls no CLI.Split writes only inside its worktrees. In write mode each part's
implementjob runs in its own git worktree on its own branch (agentmate/<split-id>/<part-id>), the planner and reviewers are read-only, and nothing is merged into your branch for you.One
writejob per working tree at a time. Two writers in one tree collide. The skills and the team lead prompt follow this rule; use separate git worktrees for parallel edits (splitdoes this for its parts).Post-run verification is explicit.
verify/--verifyruns one shell command only after a successful write job, with the remaining job time capped at 15 minutes and no retry. A failure becomes terminalneeds_attention, stores the command, exit code, timeout flag and output tail, and is counted as failed work in the status line.A spent plan is a status, not a crash. When a provider reports that its usage limit, quota or credits are used up, the job ends
quota_exhausted(terminal;waitandaskexit1). Itserrorreads<provider> quota exhausted: <line>. Retry after the reset or start the job on <other agent>., andresultaddsHand off: start the same job with provider <other>.; the other agent is the first installed one, and when none is installed both lines say to retry after the reset instead. Detection reads the stderr tail and parsed errors only, so a 429 alone is not exhaustion, and the job is not retried once a quota line is seen. Extend the detection withAGENTMATE_QUOTA_PATTERNS, case-insensitive regular expressions separated by|; invalid ones are ignored. The defaults cover agy'sRESOURCE_EXHAUSTEDstatus and itsIndividual quota reachedandquota exceededwording, as well as GitHub Copilot'spremium requestsand plan allowance lines; its barecode 429is too loose to be a default, so addAGENTMATE_QUOTA_PATTERNS='\bcode\s*429\b'if you want it (a 429 caused by a tool the agent called then counts as exhaustion too).The delegator owns acceptance. Job output is an input to your judgment. Verify claims and run the tests before you merge anything a worker produced.
No hidden configuration changes. The plugin registers its own MCP server. The fallback path runs the CLI and never edits host configuration. Do not put secrets in briefings: prompts and results are stored in plain text under
~/.agentmate, in files created with owner-only permissions (0600for files,0700for directories). Environment variables that configure job controls:AGENTMATE_CODEX_PROFILESoverrides the Codex profiles directory (~/.codex-profiles),AGENTMATE_LIMITES_BINoverrides the binary used to resolveaccount: "auto"(limites),AGENTMATE_CLAUDE_ACCOUNTSmaps Claude account names to absolute config directories,AGENTMATE_SKIP_MODEL_CHECK=1skips model and effort catalog validation before dispatch,AGENTMATE_COPILOT_BINoverrides the Copilot binary,AGENTMATE_COPILOT_WRITE_TOOLSextends Copilot's write-mode tools, andAGENTMATE_COPILOT_INHERIT=1keeps the user's built-in MCPs and skills in Copilot.
Troubleshooting
Start with npx -y agentmate doctor. It prints ok, warn or fail for each check with a hint, and exits 1 if any check fails. It runs without codex, claude or copilot installed and reports the missing CLI as a warning. It checks that each CLI responds to --version, not that you are logged in.
Symptom | Likely cause and fix |
| Restart the host after installing; check |
A job fails immediately | The destination CLI is missing from |
| The job is still running. Repeat |
A job shows | The worker process died. |
| A job started by a worker tried to start another job (a third level). Return the findings to the session that started the job instead. |
| A worker tried to start a team lead (or a cross-review or a split: |
Job ends | The provider's usage limit, quota or credits are spent. Detection looks at the stderr tail and parsed errors only, a 429 alone is not exhaustion, and the job is not retried once a quota line is seen. Wait for the reset it names, or start the same job on the other agent ( |
Duplicated or conflicting tools | A legacy registration ( |
Requirements
Node.js 18 or later
Claude Code and/or Codex CLI, authenticated
The destination CLI available on the initiating host's
PATH
Removed in 0.6.0
The deprecated synchronous servers (serve codex, serve claude), the setup command, the agentmate-codex / agentmate-claude binaries and the legacy /codex and /claude setup skill are gone; the plugin and the mate_* job tools replace them.
To remove a leftover registration, run claude mcp remove codex -s user for Claude Code, or delete the [mcp_servers.claude] section from ~/.codex/config.toml for Codex.
npx -y agentmate doctor flags both. See the installation guide for the details.
Development
git clone https://github.com/naldomadeira/agentmate.git
cd agentmate
pnpm install
pnpm build
pnpm test
pnpm lintCutting a release
pnpm version:bump x.y.z # package.json, src/lib/version.ts, both plugin manifests, the Codex marketplace
pnpm release:prepare # version check, build, smoke:pack (real tarball install), smoke:cli
git commit -am "chore: release vx.y.z"
git tag vx.y.z
git push --follow-tagsThe Release workflow runs on the tag: it fails when the tag does not match the package version, runs the checks, publishes through npm Trusted Publishing (no token) and verifies that the version appears on the registry.
Release notes are in the changelog.
License
Available Tools
6 toolscodex_explain_codeCodex Explain CodeB
Ask Codex to deeply explain code, logic, or architecture. Useful for understanding unfamiliar code, onboarding, or documenting complex systems.
Inputs: target (required), depth, context, workingDirectory.
codex_implementCodex ImplementA
Ask Codex to implement a feature, fix a bug, or make code changes. WARNING: This modifies your codebase. Returns a summary of what was changed.
Inputs: task (required), model, sandbox, workingDirectory.
codex_plan_perfCodex Performance PlanB
Ask Codex to analyze performance and create an improvement plan. Identifies bottlenecks, proposes ranked optimizations with expected impact.
Inputs: target (required), context, metrics, constraints, +1 more.
codex_queryAsk CodexB
Ask OpenAI Codex a question or give it a task. Use for getting a second opinion, exploring unfamiliar code, or tasks that benefit from a different model's perspective.
Inputs: prompt (required), model, sandbox, workingDirectory.
codex_review_codeCodex Code ReviewB
Ask Codex to review code. Provide a git diff range, file paths, or a code snippet. Returns specific, actionable feedback.
Inputs: target (required), context, focusAreas, workingDirectory.
codex_review_planCodex Plan ReviewA
Ask Codex to critique an implementation plan. Identifies gaps, risks, missing edge cases, and suggests improvements.
Inputs: plan (required), constraints, codebasePath, workingDirectory.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a distinct primary purpose, but codex_query is a generic catch-all that could overlap with the specialized tools. codex_review_plan and codex_plan_perf also have some conceptual overlap around planning, though their descriptions differentiate them.
All names use a consistent codex_ prefix and snake_case, following a clear verb or verb_noun pattern. Minor deviation: codex_query and codex_implement are single verbs, while others are compound.
Six tools is well-scoped for a Codex bridge, covering query, review, explanation, performance planning, implementation, and code review. Each tool appears to earn its place without excessive fragmentation.
The surface covers core Codex use cases: asking questions, reviewing plans/code, explaining code, performance analysis, and implementing changes. Minor gaps exist for specialized tasks like test generation or refactoring, but these can be handled via codex_query or codex_implement.
Maintenance
Related MCP Connectors
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Shared workspace where Claude, ChatGPT, Codex and Grok share files, tasks, decisions and handoffs.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Codex to delegate tasks to Claude Code, allowing Claude to investigate, edit, and verify changes in the repository with background job management.3 npmMIT
- AlicenseAqualityDmaintenanceEnables Claude Code to delegate tasks to OpenAI's Codex CLI (GPT-5.4) with structured execution traces, parallel execution, session persistence, and adversarial code review.15MIT
- AlicenseAqualityBmaintenanceEnables Claude Code to delegate tasks to OpenCode subagents asynchronously, with tools for starting tasks, polling status, and fetching results.7630 npm6MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude to hand off implementation tasks to OpenAI Codex models running through the Codex CLI, with tools for listing models, delegating work synchronously or in the background, collecting results, and continuing past sessions, while Claude stays the orchestrator that reviews diffs and runs tests.2MIT