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](#review-your-changes) in one call, and so can you, from the terminal:

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

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

[getconsult.dev](https://getconsult.dev) · [npm](https://www.npmjs.com/package/consult-mcp)

## Install

```bash
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](#how-advisors-are-contained)). 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:

```bash
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](#live-sessions) and [session messages](#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.

<details>
<summary>What install changes</summary>

- **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](#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.

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.
</details>

## 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](#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](#live-sessions) are on.

**`send_message`** `{session_id, message}` appears when [session messages](#session-messages) are on.

**`dispatch_task`**, **`task_status`** and **`cancel_task`** appear when [task dispatch](#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`:

```bash
consult review --base main --focus "the new caching layer"
consult review --agents codex --effort high > review.md
```

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, 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:

```bash
npx -y consult-mcp@latest install --sessions=repo   # or off, 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
```

| Setting | Who can see and ask whom |
| --- | --- |
| `off` (default) | Nobody. The tools don't appear. |
| `repo` | Sessions in the same git repository, including its worktrees (outside git: the same directory) |
| `machine` | Every consult session you run on this machine |

Settings are stored in `$XDG_CONFIG_HOME/consult/settings.json` (default `~/.config/consu