Give your agent suss

Paste this prompt into your coding agent and it sets suss up in the repository. It installs the CLI, runs one check, connects suss to the agent, and tells you which boundaries paired and which did not. Pick the tab for the agent you use. Only the step that connects suss to the agent changes from one tab to the next.

Claude Code installs the CLI, runs one check, and adds the suss plugin, which checks each edit it makes.

Show the promptHide the prompt

Set up suss in this repository. suss reads the code and reports where the two sides of a boundary disagree, such as a route and the client that calls it. Run the commands below as written. For a flag that is not here, look in `npx @suss/cli --help` instead of guessing, and for anything else read https://github.com/nimbuscloud-ai/suss/blob/main/AGENTS.md.

1. Install the CLI as a dev dependency with the project's package manager, for npm `npm install --save-dev @suss/cli`. Skip this when the repository has no package.json, since `npx @suss/cli` fetches it.

2. Run `npx @suss/cli init --write`. It prints the packs suss found here and writes them to `suss.json` at the root, with a config file beside it for each pack that takes one, so later runs and the MCP server read the same packs. If a `suss.json` is already there, init leaves it alone and says so; keep it, and tell me it was already there. If init says it left a pack out, tell me which one and what it needs.

3. Run `npx @suss/cli check --json` at the repository root. If `pairs` in its output is empty, stop here and tell me that nothing paired, quoting any entry under `run` and what suss printed about the files it read. A report with no findings looks the same whether both sides agreed or nothing was compared, so never report an empty one as a pass. Otherwise run `npx @suss/cli map` and tell me the path of the page it wrote, which I can open in a browser.

4. Install the suss plugin for Claude Code, which adds the suss MCP server, hooks that check each edit you make, and the intent skill. The plugin needs a suss release that has `suss check --since` and `suss extract --out-dir`, so look for both in `npx @suss/cli --help` first. If either is missing, skip the plugin and tell me it needs a newer suss than the one on npm. Otherwise run `claude plugin marketplace add nimbuscloud-ai/suss --sparse .claude-plugin plugins && claude plugin install suss@suss`, and tell me to run `/reload-plugins` so the plugin loads.

5. Finish with a short report: the packs suss found, which boundaries paired (`pairs`), which had only one side (`unmatched`), each entry under `findings` and `run`, what you changed to set suss up, and what I still have to do.

In Claude Code the prompt installs the suss plugin, which starts the MCP server described below and checks each edit the agent makes. The plugin needs a suss release that has suss check --since and suss extract --out-dir, so the agent looks for both in suss --help first, and tells you when the release on npm does not have them yet.

In Cursor and Codex the prompt adds the MCP server to the project's config (Cursor, Codex) and a short suss section to the instructions the agent reads (Cursor rules, Codex AGENTS.md). The last tab is for any other agent that can start an MCP server.

suss init asks before it writes suss.json, and an agent has no way to answer, so the prompt runs suss init --write. That prints what init found and writes suss.json without asking. If your repository already has a suss.json, init leaves it alone, and the agent tells you so.

When nothing pairs, the agent stops and says so. A report with no findings looks the same when both sides agreed and when nothing was compared, and Fix an empty run goes through the causes.

Set it up by hand

Add this to the host's MCP config and point it at the project:

{
  "mcpServers": {
    "suss": {
      "command": "npx",
      "args": ["-y", "@suss/mcp", "/path/to/project"]
    }
  }
}

Claude Code reads .mcp.json at the repository root and Cursor reads .cursor/mcp.json, and both take that block unchanged. If you drop the path argument, the server reads whichever directory the host started it in.

In Claude Code, the suss plugin starts this server for you, and also checks each edit the agent makes.

The server reads suss.json, which npx @suss/cli init writes. The file lists which packs to read the code with and where your contracts are. If you do not have one, the server picks the packs init would have picked and prints a note on stderr. When nothing in the project matches a pack, every answer comes back empty, and suss_status explains why.

The tools

suss_ask takes one question about one boundary and works the answer out from the code as it is right now. The question has to be one of ten forms, and an optional limit sets how many results come back before the rest are counted and left out. Your agent calls this one before it changes a route, a table or a function signature:

what can I project from <boundary>   the statuses a route returns, the fields a store serves
what reads <boundary>                every unit that reads it, with the file, line and call
what writes <boundary>               the same, for writes
what invokes <boundary>              the same, for invocations of a function or a queue
what calls <unit or boundary>        every unit that calls it, in-process or across a route or table
what does <unit> reach               every boundary a file or a summary goes through
what reaches <target>                every boundary that ends up going through the target
what does <package or unit> provide  every boundary it provides, one per line
why does <unit> reach <boundary>     the call chain, with each hop proved from source
why does <name> at <file>:<line> resolve to <target>

suss_check compares both sides of every boundary and reports where the two disagree, such as a caller reading a field the provider never returns or a status no caller handles. An agent runs it after writing code that crosses a boundary. Pass a boundary to narrow a whole-project report down to one thing. To review a branch, pass a base such as origin/main: the result keeps the findings that are new since the commit the branch started from and touch what it changed, and lists the ones it resolved. It works the way suss check --base does.

suss_boundaries lists the boundaries in three groups: the ones with both sides present, the ones only something serves, and the ones only something calls. An agent uses it to get oriented in an unfamiliar project, and to tell "the two sides agreed" apart from "nothing was compared" after suss_check comes back with no findings.

suss_stub_draft handles a package your project uses that suss cannot read into, such as a compiled binding or a private wrapper. It drafts a stub for that package from your own call sites and leaves the semantic blanks for you or the agent to fill in from the package's source. Teach suss a dependency covers the file it writes.

suss_intent_outcomes lists the outcomes your boundary intent documents declare. Each one comes back as <intent-name>.<outcome-id>, the string a PRD scenario puts in its link. An agent calls it before it writes or edits a link. The intent name and the outcome id are both declared in a boundary intent document, so a link made up from the feature description is a guess. A link to an outcome nothing declares comes back from suss_check as danglingScenarioLink. Pass an intentDir when the documents are somewhere other than intent/.

suss_status shows which extract and contract commands ran, which of them failed, and whether they came from a suss.json or the server picked them itself. Call it when an answer looks thinner than you would expect from the code.

Every tool is marked read-only, and none of them changes anything in your tree, so the host does not have to ask you before it calls one.

What an answer looks like

An agent about to edit a route asks what it returns today:

suss_ask { "question": "what can I project from GET /orders/{reference}" }

{
  "question": "what can I project from GET /orders/{reference}",
  "shape": "declares",
  "subject": "GET /orders/{reference}",
  "found": true,
  "headline": "GET /orders/{reference} declares 2 things you can ask it for:",
  "items": [
    {
      "what": "response",
      "name": "404",
      "detail": "error",
      "from": "orders-api::src/api.ts::get"
    },
    { "what": "response", "name": "200", "from": "orders-api::src/api.ts::get" }
  ],
  "needs": [],
  "caveats": []
}

Read found first. When it is false, needs lists the input that would let suss answer, and that is usually what to go and fix. caveats contains one warning: line for every call suss could not follow, with the file and line of the unit it was in. An agent uses those lines to tell a complete answer from one that stopped partway.

Staying current

The server runs one extract when it starts, then watches the tree. When a source file changes it re-runs the part of the extract that file affects, so every answer describes your working tree as it is now. Editing one file only costs one file's worth of work.

Telling the agent to use it

You have to tell the agent to use it. The prompt adds this section to the instructions the agent reads (AGENTS.md, a Cursor rule or the equivalent), and when you set suss up by hand you add it yourself:

## suss

suss checks both sides of each boundary in this repository, such as a route and the code that calls it, or a table and the code that reads and writes it.

- Before changing a route, a table, a queue or a function signature, ask the suss MCP server what reads, writes or calls it with `suss_ask`.
- After an edit that crosses a boundary, run `suss_check`. Fix what it reports, or tell the developer why a finding should stay.
- A `suss_check` with no findings means the two sides agreed only when `suss_boundaries` lists a boundary with both sides present.

The MCP package README covers how to mount the server on a transport of your own.