Install the nima plugin for Claude Code

The nima plugin for Claude Code bundles nima's MCP server, the nima skill, a filing skill, a read-only reader agent and hooks that run on their own. It is published from the public getnima/skills repository on GitHub, which is both the plugin and its marketplace. This page covers what it adds, how to install it, what it does without being asked, and the rules that limit how the agent files signals.

What the nima plugin adds to Claude Code

The plugin adds nima's MCP connection plus behavior around it: the agent is told when to ask nima, and the agent can file a signal under a guard that enforces the rules.

A bare MCP connection (see Connect a coding agent) gives the agent the tools and nothing else. With the plugin you also get:

• The nima MCP server, so there is no claude mcp add step.
• The nima skill, which teaches the agent when to query nima and how to read the answer.
• The file-signal skill, which teaches the agent when and how to file a signal. It is internal to the plugin and is not installed by npx skills.
• A nima-provenance agent. It is read-only and is meant for three or more nima lookups, or for a check before changing a module.
• Hooks that print a session card, nudge the agent toward nima, guard create_signal and track what the agent searched.

The plugin's tools use four scopes: knowledge:read, signals:read, documents:read and signals:write. The consent screen lists the permissions nima requests; see MCP server.

Install the nima plugin in a repository

Add the getnima/skills marketplace, install nima@nima with project scope, then sign in from /mcp.

/plugin marketplace add getnima/skills

claude plugin install nima@nima --scope project

Has anyone asked for CSV export? What exactly did they say?

What the nima plugin does automatically

Once installed, the plugin's hooks run on their own at session start, on each prompt, around create_signal and when the agent finishes a turn.

• Session start. A short card tells the agent when to query nima, which filing mode is active, and the exact sourceLabel to use, agent:claude-code:<repo>. It also tells the agent to ask you once to run /mcp if the nima tools are missing or unauthenticated, instead of retrying.
• Prompts. A prompt that looks like a product-evidence or history question (for example "has anyone asked", "customers", "why did we", "feedback", "roadmap") gets a one-line nudge to call ask_knowledge_graph first, up to 5 times per session. A prompt that asks to implement, build, add, design, plan or propose a feature, endpoint, flow, integration or tool gets a pre-flight nudge to check open signals and prior decisions, up to 3 times per session. A prompt gets at most one nudge, and the evidence nudge wins. Slash commands and prompts shorter than 12 characters are skipped.
• Before claiming demand. The nima skill tells the agent to query nima before it says customers did or did not ask for something, before it writes a spec, plan or PRD that asserts demand, and before it removes or redesigns a feature that has product history. It does not use nima for questions grep answers.
• Stop check. If a final answer of 200 characters or more mentions a likely product gap and nothing was filed that turn, one nudge asks the agent to file it or to reply No signal to file. It fires at most once per session.

How the agent files a signal to nima

The agent files a signal only when it has confirmed a concrete product gap in the current session, and only after it searched nima for the same need.

The file-signal skill sets the bar. All of these must hold:

1. The agent verified it this session, with a path:line, an endpoint, a command and its output, or your own statement. A hunch does not count.
2. It is a product gap, not an agent artifact: not the agent's own mistake, a local environment problem, a style or refactor preference, or a third-party bug.
3. It is not a test or probe. The agent never files connectivity checks or "testing the plugin" signals.
4. It is not already fixed at HEAD or on origin/main, and not already tracked in nima.
5. It is within the caps below.
6. It comes from the main session. A subagent reports candidates to its parent.

Search first. The agent runs ask_knowledge_graph and search_signals, one call at a time, and compares the results. An open match means it does not file and tells you "already in nima". A dismissed match means a PM already said no, and the skill tells the agent not to re-file without your say-so. That is an instruction to the agent; the guard does not check it. A resolved or merged match, if it still reproduces, is raised with you first. A spec that is approved, in progress or shipped and covers the need also means no filing. Signals whose source label starts with agent: count as matches too.

Fixed template. Content is 80 to 1500 characters of plain facts. The first line must stand alone, because nima's extraction turns the content into an intent. Here is the template with a generic example:

Gap: Invoices cannot be exported; only customers and orders have an export path.
Observed: Looked for an invoice export route while building a report; src/billing/routes.ts has list and get but no export, and no other module exposes one.
Expected: An endpoint that returns an invoice with its line items as a file.
Evidence: app@a1b2c3d src/billing/routes.ts:42.

The agent also sets productAreas to one to three lowercase kebab-case tags such as billing and export, and leaves stakeholders empty, because an agent cannot assert who asked for something.

The notice. After a successful filing the agent ends its reply with one line:

Filed to nima: <id> - "<first sentence>" (agent:claude-code:<repo>). nima classifies it asynchronously; a PM can dismiss it.

Claude Code also shows a short message with the running count for the session.

What the agent will not file: opinions ("the settings page feels cluttered"), its own failed test or an unrebuilt package, refactor or style preferences, third-party bugs, anything already open, dismissed or specced in nima, URLs, customer names, emails, tokens, absolute user paths, raw logs, or your prompt verbatim. If you want to test filing, the skill tells the agent to warn you that it creates a real signal in your team's queue.

If a call fails, the agent handles it as the skill says. On a 401 or 403 it tells you to re-authenticate with /mcp (or grant signals:write) and prints the draft so it is not lost. On a 429 it stops filing for the session. You can also file by hand with /nima:file-signal <text>: your statement counts as the verification, and the dedupe, template and guard still apply.

What the guard enforces on create_signal

A PreToolUse hook checks every create_signal call and blocks it with a reason unless every check passes. The agent reads the reason and fixes the draft.

The guard fails closed. If Node is missing, if the hook crashes, or if you turn the plugin off, create_signal is blocked rather than left unchecked. Every other hook fails open: a problem there never blocks your work. Each filing is also written to an audit log, filed.jsonl, in the plugin's data directory (~/.claude/plugins/data/nima-nima/ by default, Claude Code's plugin data directory).

Modes and opt-outs for the nima plugin

Set NIMA_SIGNAL_MODE to auto, ask or off to control filing, and use the other switches to quiet the hooks. Filing is on by default (auto).

Set the variables in the env block of a Claude Code settings.json. For example, in the repository's .claude/settings.json:

{
  "env": {
    "NIMA_SIGNAL_MODE": "ask"
  }
}

Any value other than ask or off for NIMA_SIGNAL_MODE is treated as auto.

How agent-filed signals appear in nima

An agent-filed signal enters the pipeline like any other: nima classifies it asynchronously, and it can cluster into a beacon. It carries the source label agent:claude-code:<repo>, which tells a reader that a coding agent observed it in a specific repository.

Treat these signals as agent observations, not customer demand. The plugin's own reader agent ranks signals whose label starts with agent: as lowest trust and never counts them as demand. A PM can dismiss one that is wrong, and the file-signal skill tells the agent not to re-file a need a PM dismissed without your say-so. This is an instruction, not something the guard checks. For how signals are classified and clustered, see the loop.

Use the nima plugin headless or in CI

OAuth needs a browser, so a headless run connects with a personal API key instead. Create the key under Settings > API keys in the nima web app with the plugin's four scopes, then add your own user-scope server, which takes precedence over the bundled one:

claude mcp add --transport http --scope user nima https://mcp.getnima.io/mcp \
  --header "Authorization: Bearer $NIMA_API_KEY"

The tools then appear as mcp__nima__* instead of mcp__plugin_nima_nima__*. The plugin's skills, agent and hooks cover both names. Your shell expands $NIMA_API_KEY when you run the command, so Claude Code saves the key text in ~/.claude.json; see Connect a coding agent for a way to keep it off disk.

Use nima with Codex and other agents

Codex and other agents install only the read skill with npx skills add getnima/skills --agent codex. The plugin is Claude Code only, because the filing rules depend on its hooks.

npx skills add getnima/skills --agent codex

The file-signal skill is marked internal, so npx skills never installs it: an agent without the plugin's hooks has no guard to enforce the caps. Connect the MCP server for those agents by hand, as on Connect a coding agent.

Do not install both in Claude Code. The plugin already carries the nima skill, and npx skills add would add a duplicate.

Update and uninstall the nima plugin

Claude Code updates and removes plugins with its own commands. The ones below come from Claude Code's plugin documentation.

Auto-update is off by default for a third-party marketplace such as nima; turn it on from the Marketplaces tab in /plugin. By default, Claude Code deletes the plugin's data directory, including the filed.jsonl audit log, when you uninstall the plugin from its last location. Disconnecting the server is separate: see the MCP server overview.

Troubleshooting the nima plugin

• The nima tools are missing or every call fails with 401. Run /mcp, pick plugin:nima:nima and sign in again. After an install during a session, run /reload-plugins. For the 1-hour access token and 30-day refresh token, see the MCP server overview.
• You installed both the plugin and the npx skills copy. Remove the npx copy; see Use nima with Codex and other agents.
• A create_signal call is blocked. A rule failure begins with nima: and names the failed rule; the agent should fix the draft. A cap message means stop. The off, missing-Node and crash blocks begin with nima plugin.
• create_signal is blocked with nima plugin: Node is required. Install Node 18 or newer. The guard cannot enforce the caps without it, so it blocks instead.
• create_signal is blocked with nima plugin is off for this repo. NIMA_PLUGIN=off is set or a .nima-off file exists in the project root. Remove it to re-enable filing; the block is deliberate.
• The agent never nudges toward nima. The nudges are keyword-based and capped per session. Ask the question directly, or call the nima skill with /nima:nima.
• Windows. The hooks run through bash and are not supported on Windows.

Limits of the nima plugin guard

The guard is a set of mechanical checks, not a review of the signal's meaning.

• The search-first check proves that a search ran, not that it was relevant. Whether a signal duplicates an existing one is still the model's judgment.
• The guard cannot redact semantically. It catches secret and email patterns, not a customer name in prose.
• A subagent is blocked when the hook input carries an agent id. That field is best effort.
• The caps are per machine. Two machines can each file 5 signals in a day.