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

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 `<!-- consult:start -->` and `<!-- consult:end -->` 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.
</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
consult 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](https://cli.github.com), 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:

```bash
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
```

| 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) |
| `tree` | Everything `repo` allows, plus sessions whose directory is above or below this one, such as a session in `~/code` and one in `~/code/app` |
| `machine` | Every consult session you run on this machine |

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.

| CLI | How consult finds the session |
| --- | --- |
| claude | the record Claude Code keeps for each running process (`~/.claude/sessions/<pid>.json`), so it follows `/resume` and `/clear`; `CLAUDE_CODE_SESSION_ID` as a fallback. Listed once the conversation is saved, after its first message |
| codex | the `rollout-*.jsonl` file the codex process holds open, from the session's first turn on |
| grok | the `~/.grok/sessions/<cwd>/<session id>/events.jsonl` file the interactive grok process holds open, from the session's first turn on; not identified if several sessions are open |

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

| CLI | While it is working | While it is idle |
| --- | --- | --- |
| claude | read after its next tool call or when it finishes its turn | woken within a few seconds: a background hook (`asyncRewake`) started at the end of each turn waits for a message |
| codex | read as its next prompt, after the current turn | woken at once: the message is queued with `codex queue` and starts a turn. If that command fails, the message waits for Codex's hooks, which only run once you have trusted them |
| grok | read after its next tool call or when it finishes its turn | not woken: Grok has no way to start a turn from outside, so it reads the message after you prompt it |

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:

```bash
npx -y consult-mcp@latest install --sessions=repo --messages=on
npx -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.

| CLI | Flags |
| --- | --- |
| claude | `-p --restricted --tools Read,Grep,Glob --strict-mcp-config` |
| codex | `exec`, `sandbox_mode="read-only"`, `approval_policy="never"`, plugins off, and every enabled MCP server disabled by name (Codex runs MCP tools outside its sandbox) |
| grok | `--tools read_file,grep,list_dir --disallowed-tools Agent,search_tool,use_tool` (the MCP helper tools can reach servers that write files) |
| agy | `-p --output-format stream-json --disable-slash-commands`, only after a check of agy's own config (below) |

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](#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:

| CLI | Worker flags |
| --- | --- |
| codex | `exec`, `sandbox_mode="workspace-write"` with `network_access=false` and `writable_roots=[]` (writes confined to the cwd and temp dirs, no network), `approval_policy="never"`, plugins off, and every enabled MCP server disabled by name |
| grok | `--tools read_file,grep,list_dir,search_replace,write_file,run_terminal_cmd --always-approve --disallowed-tools Agent,search_tool,use_tool`. Without Grok's kernel sandbox (see above), its shell commands run unconfined as your user, with network access. Its shell could even start another agent CLI, so for grok "no MCP servers" stops loops through consult but is not a hard boundary |

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](SECURITY.md) covers read scope and the threat model.

## CLI

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

```bash
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 pipe
consult review --base main            # every installed advisor reviews the branch
consult doctor --ask                  # check the setup and that each advisor answers
consult agents
consult 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

```bash
npm install
npm run build
npm test                              # unit tests, no CLIs needed
npm run test:live                     # real calls to all three CLIs through the MCP server
node 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](.github/workflows/release.yml) 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/`](site) and deploys to [getconsult.dev](https://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](https://github.com/neelsatyavolu/consult/issues/new?template=bug_report.yml) and paste it in.

Security problems go to [private vulnerability reporting](https://github.com/neelsatyavolu/consult/security/advisories/new) instead (see [SECURITY.md](SECURITY.md)).

## License

[MIT](LICENSE)