Consult

consult

Let your coding agents get a second opinion.

consult is an MCP server that lets Claude Code, Codex and Grok ask each other, and Google's Antigravity CLI, for advice through the CLIs already signed in on your machine. No API keys: each advisor runs on the subscription its CLI already uses.

Claude Code on Opus can ask Codex on GPT-6 Astra to review a plan, Codex can ask Grok why a test is flaky, or any of them can put one question to all the others at once. Before calling work done, an agent can have the other vendors review its diff in one call, and so can you, from the terminal:

npx -y consult-mcp@latest review            # every installed advisor reviews your uncommitted changesnpx -y consult-mcp@latest review --base main

With live sessions on, agents can also ask the sessions you already have running and message them, and with task dispatch on, hand a coding task to a Codex or Grok worker and follow its progress.

getconsult.dev · npm

Install

npx -y consult-mcp@latest install

This registers consult with every agent CLI it finds on your PATH (claude, codex, grok), at user scope. Restart running agent sessions afterwards.

Antigravity (agy) is an advisor only. consult doesn't register itself with agy, because agy can only be kept read-only with no MCP servers enabled (details). If you install agy after consult, re-run install so the server's PATH includes it.

It stays up to date. Hosts launch the server with npx -y consult-mcp@latest serve, so each new agent session runs the latest release. Re-running install is safe: it replaces an existing registration, including ones written by older versions.

To remove it:

npx -y consult-mcp@latest uninstall

Requirements: Node 22 or later on macOS, Linux or Windows, and at least one of the claude, codex or grok CLIs, signed in.

On Windows, everything except live sessions and session messages works: those find sessions with ps and lsof and deliver messages through POSIX shell hooks, so they stay off there. consult never runs an advisor through cmd.exe, which would reinterpret characters like & and % in a question: for a CLI installed as an npm .cmd shim it runs the script or binary the shim points at directly.

Check the setup with npx -y consult-mcp@latest doctor. It reports each agent CLI and its version, whether consult is registered with it, your settings, the message hooks and whether agy's config is read-only, with a fix for each problem. doctor --ask also sends each advisor a one-word question, which shows that its CLI is signed in and can answer.

Tools

ask_agent {agent, question, model?, effort?, session_id?, cwd?} returns {agent, answer, session_id, model?, duration_ms}.

• agent: claude, codex, grok or agy (Antigravity, Gemini models).
• model: passed through to that CLI (opus, gpt-6-astra, grok-4.7, gemini-3.1-pro-high, …). Omit it to use the CLI's default.
• effort: low, medium or high.
• session_id: continues an earlier conversation with the same advisor.
• cwd: the directory the advisor can read. Defaults to the directory the host agent started the server in, which is normally its repo.

ask_agents {agents, question, effort?, cwd?} asks several advisors the same question in parallel and returns {results: [...]}, one entry per advisor. Each entry is either an answer with its own session_id or an error. One advisor failing doesn't fail the others.

review_changes {agents, base?, focus?, effort?, cwd?} gets a code review of the git changes in cwd from each advisor in parallel. See Review your changes.

list_agents shows the installed CLIs, their versions and the model IDs each account can use.

list_sessions and ask_session {session_id, question, effort?} appear when live sessions are on.

send_message {session_id, message} appears when session messages are on.

dispatch_task, task_status and cancel_task appear when task dispatch is on.

While an advisor is working, the server sends MCP progress notifications (codex is thinking (40s)), so hosts that show progress don't look stuck.

When agents consult

The server's MCP instructions, which hosts add to the agent's context, tell it to ask for a second opinion when:

• it has tried two fixes for a bug and neither worked,
• it is about to make an architecture, data-model, migration or other hard-to-reverse decision,
• it wants a plan or a diff reviewed before calling the work done,
• it is unsure and being wrong is costly.

The instructions also tell it to prefer an advisor from a different vendor, to write self-contained questions (the advisor can read the repo but not the conversation), and to check advice against the code before acting on it.

Review your changes

consult collects the diff itself and sends it to each advisor with review instructions: find real bugs, regressions, security problems and broken contracts with the rest of the code, give severity, file:line, the failing scenario and a fix, skip style nits, and say so plainly when nothing is worth fixing. Advisors read the surrounding code to check their findings before reporting them, and stay read-only like any other advisor.

• Without base, it reviews everything not yet committed: staged and unstaged changes against HEAD, plus the names of new untracked files, which advisors read directly.
• With base (e.g. main), it reviews the branch since it left base, including uncommitted work (git diff --merge-base main).
• focus adds what to look at especially, e.g. "error handling in the retry path".

It always reviews the whole repository, even from a subdirectory, and advisors run at the repository root. The question reaches each CLI as one command-line argument, so the diff is cut to fit: up to about 110 KB on Linux, 190 KB on macOS and 25 KB on Windows, whose command lines are shortest. The advisors are told to read the changed files for the rest. External diff, textconv, fsmonitor and clean/process filter commands are off, so collecting the diff runs nothing but git.

From the shell, consult review uses every advisor CLI on your PATH unless you pass --agents codex,grok:

consult review --base main --focus "the new caching layer"consult review --agents codex --effort high > review.mdconsult review --pr 42

--pr <number> reviews a GitHub pull request. It looks up the PR's base and head commits with gh pr view (it needs the GitHub CLI, signed in), checks that HEAD is the PR's head commit (run gh pr checkout 42 first) with no uncommitted changes to tracked files, since advisors read the working tree, and reviews the PR's commits since the merge base: the same diff GitHub shows, without uncommitted or untracked files. Only consult runs gh; advisors still get the diff and read-only access to the repository.

Progress goes to stderr and the reviews to stdout, one section per advisor, each with the command for a follow-up question in the same conversation. The command exits 1 only if every advisor failed.

Live sessions

Off by default. When on, agents can ask the agent sessions you already have running, not only fresh advisors. For example, the Codex session working on your API can ask the Claude Code session that wrote the client what it changed.

• list_sessions lists other live sessions: agent, session id, directory, git branch, title, its user's latest prompt (first 200 characters, so you can tell what it is working on), and when each started and was last active. Nothing else from their conversations.
• ask_session {session_id, question, effort?} asks a read-only copy of that session. consult forks it (claude --resume <id> --fork-session, codex exec fork <id>, grok --resume <id> --fork-session) with the same containment as any advisor. The copy knows everything the session has seen, while the session itself is not interrupted and never sees the question. Pass the reply's session_id and cwd to ask_agent for follow-ups.

Turn it on when you install, or later:

npx -y consult-mcp@latest install --sessions=repo   # or off, tree, machine; without the flag, install asks when run in a terminalnpx -y consult-mcp@latest settings                  # interactive: live sessions, messages, task dispatch, and which agents use consult

Settings are stored in $XDG_CONFIG_HOME/consult/settings.json (default ~/.config/consult/). Running sessions register in $XDG_STATE_HOME/consult/sessions/ (default ~/.local/state/consult/), and only you can read those files. Turning sessions on takes effect in new agent sessions; turning them off, or changing the scope, applies immediately.

Session messages

Off by default, and only available with live sessions on. ask_session asks a copy, so the session itself learns nothing. With messages on, an agent can tell a running session something. For example, the Claude Code session that just merged and pushed main can tell the Grok session with uncommitted edits in the same checkout which files changed under it.

• send_message {session_id, message} leaves a message of up to 4,000 characters for a session from list_sessions. The receiving agent reads it in its own conversation, marked with the sending agent, session id, directory and branch, and with a note that it comes from a peer agent and is not an instruction from you. It can reply with its own send_message.

Delivery uses each CLI's hooks, which consult install adds when messages are on, and for Codex its own codex queue command:

Waking a session starts a turn there without you, which uses that session's tokens and lets its agent act on the message. Nothing tells the sender that a message was read. A session without the hook still gets its messages with the reply to its next list_sessions, ask_session or send_message call. Unread messages are dropped after 24 hours; a session holds at most 20, and one session can send another at most 10 an hour.

Turn it on when you install, or later:

npx -y consult-mcp@latest install --sessions=repo --messages=onnpx -y consult-mcp@latest settings

Waiting messages are stored in $XDG_STATE_HOME/consult/inbox/ (default ~/.local/state/consult/), in files only you can read. The same repo and machine scopes decide who can message whom.

Task dispatch

Off by default. When on, an agent can hand a well-defined coding task to a Codex or Grok worker, keep working, and check in on it. For example, Claude Code can have Codex write the tests for a module while it builds the next one.

• dispatch_task {agent, task, model?, effort?, cwd?} starts the worker in the background and returns a task_id at once. agent is codex or grok. The worker runs headless in cwd (default: the host's directory) and can edit files and run commands there. It can't see the host's conversation or ask questions, so the task must be self-contained.
• task_status {task_id?, wait_sec?, since?} returns the task's state (running, succeeded, failed, cancelled), its latest updates (commands run, files edited, messages), and the worker's final report once it finishes. wait_sec (up to 600) waits for the task to finish, sending each update as an MCP progress notification as it happens. since returns only updates after the last_seq of an earlier call (the server keeps the last 200; earlier_updates_dropped says when you missed some). Without task_id it lists all tasks.
• cancel_task {task_id} stops the worker. Files it already changed stay changed.

Tasks live in the consult server's memory: they end with the agent session that started them, and the server stops any still running when it exits. CONSULT_TASK_TIMEOUT_SEC (default 3600) caps each task. The report includes the worker's session_id; pass it to ask_agent with the same agent to ask a read-only follow-up about the work.

Turn it on with npx -y consult-mcp@latest settings; it applies to agent sessions started afterwards. Workers change files, so review their diff before building on it, and don't point two workers at the same files.

How advisors are contained

Every advisor runs headless and read-only, and has no MCP servers. So an advisor can't call consult again, which prevents loops.

agy has no flags to restrict its tools or switch off MCP servers (--mode plan and --sandbox leave write, shell, browser and MCP tools on), so before every call consult checks the config agy will use and refuses to run it unless:

• toolPermission in ~/.gemini/antigravity-cli/settings.json is request-review (the default) or strict. Writes, shell commands and URL fetches then need approval, which headless mode can't ask for, so agy denies them. always-proceed and proceed-in-sandbox are refused. strict denies file reads too, which leaves agy unable to answer most questions.
• permissions.allow in that file is empty, since allow rules let commands run without approval.
• agy mcp list shows no enabled server, and agy plugin list shows no plugins (plugins bring their own MCP servers).
• No hooks or plugins can load: ~/.gemini/config/hooks.json and plugins.json are missing or empty, ~/.gemini/config/plugins/ and ~/.gemini/antigravity-cli/plugins/ are empty, and there is no .agents, .agent, _agents or _agent directory from cwd up to the repository root. Hooks run commands, and a hook can approve any tool call, which would get around the permission check.

The error says what to change. agy is also told to use only its file tools: when a tool is denied it ends the turn without an answer, and consult then reports which tool was denied. Its web search tool is not blocked, so search queries go to Google, the same provider that already receives the question. agy can't fork sessions, so it has no live sessions or task dispatch. Resume with session_id works through --conversation, but agy starts a new conversation if the id is unknown; the reply's session_id then differs from the one you passed.

ask_session copies use the same flags, plus --resume <id> --fork-session (claude, grok) or exec fork <id> (codex), so the live session's own transcript is only read.

consult doesn't use Grok's kernel sandbox (--sandbox read-only), because it refuses to start on machines where /var/run/docker.sock is a symlink, as it often is on Macs with Docker installed.

The first message of each session also tells the advisor that another agent is consulting it. It should answer directly, skip approval and brainstorming workflows, and not modify anything.

Task dispatch workers are the one exception to read-only, and only when you turn it on. They stay headless and have no MCP servers, so they can't call consult either:

Their first message tells them another agent dispatched them, to finish the task without asking questions, to stay within the task and the directory, and not to commit or push unless the task says so.

Advisors send what they read to their own provider. SECURITY.md covers read scope and the threat model.

CLI

The same calls are available from the shell, which is handy for debugging:

consult ask codex --model gpt-6-astra "Is the retry logic in src/sync.ts safe under concurrent calls?"consult ask codex --resume <session_id> "What would you change first?"consult ask grok - < question.md      # long questions from a file or pipeconsult review --base main            # every installed advisor reviews the branchconsult doctor --ask                  # check the setup and that each advisor answersconsult agentsconsult settings                      # live sessions, messages, task dispatch, and which agents use consult

Use npx -y consult-mcp@latest <command> if it isn't installed globally. Advisors are read-only here too: the same containment flags apply, so there is no need to tell them not to edit files. While one works, consult ask prints timestamped progress to stderr (commands run and messages for codex and grok, a heartbeat after 30 quiet seconds for any agent) and only the answer to stdout.

CONSULT_TIMEOUT_SEC (default 900) caps each advisor call; raise it for long grok runs on large questions. CONSULT_TASK_TIMEOUT_SEC (default 3600) caps each dispatched task.

Development

npm installnpm run buildnpm test                              # unit tests, no CLIs needednpm run test:live                     # real calls to all three CLIs through the MCP servernode dist/cli.js install              # register this checkout with your agents

Releases: bump version in package.json, then push a matching tag (git tag v0.3.0 && git push --tags). The release workflow publishes to npm with provenance through npm trusted publishing, then creates the GitHub release. Everyone using @latest picks it up on their next agent session. Tags with a pre-release suffix (v0.3.0-rc.1) publish to the next dist-tag instead of latest.

The landing page is in site/ and deploys to getconsult.dev on Vercel. The old address, consult.n3el.dev, redirects there.

Reporting bugs

1. Run npx -y consult-mcp@latest doctor and copy its output. It shows the consult version, your platform, each agent CLI and what's misconfigured, with your home directory as ~.
2. Open a bug report and paste it in.

Security problems go to private vulnerability reporting instead (see SECURITY.md).

License

MIT