# Joint Chiefs setup guide

You're here because the user pasted a setup prompt into you and you got stuck — or the prompt told you to fetch this for backup before giving up. Read it top to bottom. The user wants this conversation to end with Joint Chiefs wired up and a successful test review. Not "I think it's added, let me know if it works."

## What Joint Chiefs is

Joint Chiefs is an MCP server. It exposes one tool, `joint_chiefs_review`, that runs the user's code past OpenAI, Gemini, Grok, and Claude in parallel — plus any local model the user has configured via Ollama or an OpenAI-compatible server (LM Studio, Jan, llama.cpp-server, Msty, LocalAI) — and returns a single consensus. The in-app setup prompt includes the installed binary path. If you arrived here directly, install the released macOS app first. Your job is to verify the binary, add the client configuration, and prove a review works.

## Order of operations

1. Confirm the binary exists.
2. Find your own MCP config file.
3. Add the entry.
4. Restart whatever needs restarting.
5. Verify `joint_chiefs_review` shows up in your tool list.
6. Run a test review.
7. Report back to the user with proof.

Don't skip steps. Step 6 is what proves it works — anything short of that is a guess.

## 1. Confirm the binary

Use the exact path from the setup app's prompt. The released app installs to `/opt/homebrew/bin` when that directory is writable, otherwise to `~/.local/bin`. The user can also choose a different directory. Do not assume the Homebrew path exists.

If no path was supplied, check the two defaults:

```bash
ls -l /opt/homebrew/bin/jointchiefs-mcp "$HOME/.local/bin/jointchiefs-mcp"
```

One missing default is fine. Verify the chosen `jointchiefs-mcp` is executable and that `jointchiefs-keygetter` is installed beside it. Use the full absolute path in client configuration; do not rely on a GUI client's PATH or tilde expansion.

If neither is installed:

1. Open https://jointchiefs.ai/download and download the released DMG (currently v0.5.13).
2. Open the DMG, move Joint Chiefs.app to Applications, and open it. The setup app installs the bundled CLI, MCP server and keygetter.
3. In the app's MCP Config section, wait for **Ready to connect**. If it says **Install failed**, click **Choose location…**, choose a writable folder, then **Install Here**.
4. Use the installed path shown by the app and check it again.

The Homebrew tap is not available. Use the DMG or the source-build instructions on the download page. Apple Silicon only; macOS 15 (Sequoia) or later.

## 2. Find your own config file

Check your client's current documentation for local stdio MCP support, configuration location and format. Some clients use JSON, others TOML or a settings interface. Use its supported configuration method.

If you cannot identify the client or access its settings, state that specific blocker. A missing config file does not prove that a client lacks MCP support. A remote-only client cannot directly launch this local stdio binary.

## 3. Add the entry

For a client that uses an `mcpServers` JSON object, the entry looks like this. The path below is only an example; replace it with the absolute path verified in step 1:

```json
{
  "mcpServers": {
    "joint-chiefs": {
      "command": "/opt/homebrew/bin/jointchiefs-mcp",
      "args": []
    }
  }
}
```

Use the equivalent server entry in your client's native format. Merge it into the existing config; update an existing Joint Chiefs entry instead of creating a duplicate. Preserve unrelated servers and settings.

API keys do NOT go in this entry. Joint Chiefs reads them at request time from a permission-locked local file (`~/Library/Application Support/Joint Chiefs/credentials.json`, mode `0600`), written there by the setup app's Keys page. Configure the review providers in the setup app first: save and test cloud-provider keys on the Keys page, or configure a supported local model. Also check the selected moderator and tiebreaker in Roles & Weights. Never ask for keys in the conversation or put them in MCP configuration.

After you write the file, show the user the exact entry you wrote. Not paraphrased — the literal block. They want to verify it landed.

## 4. Restart

Most MCP hosts read the config at startup. They don't hot-reload. Quit the host fully — Cmd-Q on macOS, not just close the window — and reopen it.

Some hosts can reload MCP servers without a full restart. Check your own docs. If yours can, do it that way.

After the restart you may be in a fresh session that doesn't remember any of this conversation. The user will paste a follow-up — be ready to pick up where you left off.

## 5. Verify the tool is visible

After restart, your tool list should include `joint_chiefs_review`. If it doesn't, the three likely causes in order:

- **Restart didn't fully reload the config.** Quit and reopen the host completely.
- **Config syntax or schema is invalid.** Re-read and validate the file in the format your client supports.
- **Path in the config is wrong.** Re-run the `ls` from step 1 and confirm the binary is exactly where the entry points.

If the tool is visible, move on.

## 6. Run a test review

After the user has asked to set up and test Joint Chiefs, call `joint_chiefs_review` with a tiny, non-sensitive snippet. The released tool’s guidance calls for a request that names Joint Chiefs. A review uses the configured model providers and may incur their charges; tool discovery alone does not run a review.

```javascript
function add(a, b) {
  return a + b
}
```

Pass it as `code`, with `goal: "smoke test"` and `rounds: 0` for the initial review without extra debate rounds. Wait for the response. The consensus comes back as Markdown with findings, severity, agreement level, and a recommendation.

What you'll see:

- **A consensus summary** — wired up and working. Show the actual output to the user. Don't summarize it — paste it.
- **"No LLM providers configured"** — no review provider is available. Check the setup app's provider configuration and weights: an enabled cloud provider needs a valid saved key, while local providers need their server and model configured. A weight of zero excludes a provider.
- **Rate-limit rejection** — defaults are one concurrent review and 30 reviews per rolling hour, per MCP server process. Limits come from `rateLimits` in `~/Library/Application Support/Joint Chiefs/strategy.json`. Follow the returned wait time.
- **Timeout or network error** — inspect the returned error and provider progress. Show the actual error; name a provider only if the response identifies it. Local-model reviews can take many minutes. A partial result or provider error is not proof that every configured provider worked.

## 7. Report back

End the conversation with one of:

- **Success:** "Joint Chiefs is wired up. Here's the consensus from a test review of a 3-line snippet:" — paste the actual output.
- **Specific blocker:** "I got as far as [step]. The blocker is [exact error or symptom]. The fix is [concrete next action]."

Don't end on "I think it's added" or "let me know if it works." That's how the user ended up reading this guide in the first place. Either you proved it works or you tell them exactly what's broken.

## Reference

- Source code and full docs: https://github.com/djfunboy/joint-chiefs
- Issue tracker: https://github.com/djfunboy/joint-chiefs/issues
- License: MIT
- Requirements: macOS 15+, Apple Silicon only
