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 changes

npx -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.

What install changes

• claude: claude mcp add consult --scope user …
• grok: grok mcp add consult …
• codex: a [mcp_servers.consult] table in $CODEX_HOME/config.toml (default ~/.codex/config.toml). It sets tool_timeout_sec = 960 because Codex's 60s default is too short for an advisor call, and startup_timeout_sec = 60 because a cold npx start can take longer than the default 10s. The previous file is kept as config.toml.bak. consult only writes the file if the result parses and every other setting is unchanged. Otherwise it stops and asks you to edit the file by hand.

Each entry sets PATH to the directories holding the launcher (npx or node) and the agent CLIs, because some hosts start MCP servers with a minimal environment.

With session messages on, install also adds consult's hooks to each CLI's own hook file: ~/.claude/settings.json, ~/.codex/hooks.json and ~/.grok/hooks/consult.json. Other hooks in those files are left as they are, and uninstall or turning messages off removes consult's. The server started through npx consult-mcp@latest also rewrites consult's own Claude Code entries when they differ from the current release's, so hook fixes reach you without reinstalling.

Install also adds a short consult section to each CLI's global instructions file (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.grok/AGENTS.md) so agents know what consult can do: ask advisors, and, when they are on, ask and message live sessions and dispatch tasks. It sits between and comments; the rest of the file is left as it is. consult settings keeps it in step with your choices, the server refreshes it on start, and uninstall removes it.

To pin to a specific build instead of following @latest, install globally with npm i -g consult-mcp and run consult install, or run node dist/cli.js install from a checkout. Hosts then launch that exact script.

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.md consult review --pr 42

--pr 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 --fork-session, codex exec fork , grok --resume --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 terminal

npx -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.

| grok | the `~/.grok