# Claude Code integration

> Use GNO with Claude Code via the SKILL.md install or the MCP server.

Section: Integrations  
Canonical: https://gno.sh/docs/claude-code  
Markdown: https://gno.sh/docs/claude-code.md

Claude Code supports two integration paths. **Skills** install GNO as a `/gno` slash command. Tool definitions load only when the command is invoked. **MCP** exposes the same retrieval tools through the Model Context Protocol so Claude can call them automatically.

## Quickstart

```
bun install -g @gmickel/gno
gno setup ~/notes --name notes

# Install the skill (preferred — zero context overhead)
gno skill install --target claude --scope user

# Optional: also install MCP for automatic tool calls
gno mcp install --target claude-code
```

`gno setup` returns only after lexical search proves a real result from the folder you just indexed, so a successful exit means retrieval works rather than that files were copied. Semantic embeddings continue independently in the background. You can also do both steps at once with `gno setup ~/notes --name notes --connector claude-code-skill`.

The skill target is called `claude` (Claude Code is the default). Use `--scope user` to install globally, or omit it for project-local install.

## Using the skill

After installing the skill, Claude Code exposes a slash command:

```
/gno search "authentication patterns"
/gno query "how does our API handle errors"
/gno ask "what's our deployment process"
```

Skills are preferred for coding agents because they have zero context window overhead — the tool definitions only load when the slash command is invoked. Use `gno skill install --target all` to install across Claude Code, Codex, OpenCode, OpenClaw, and Hermes Agent at once.

## Using MCP

With MCP installed, Claude Code can call `gno_query` / `gno_search` without a slash command. Example:

> “Search my notes for deployment procedures”

> “Find my architecture docs and summarize the relevant parts for this change”

Claude picks the right tool (`gno_query`, `gno_search`, etc.) based on the request.

## Which one should you install?

| Want                                                                    | Install                     |
| ----------------------------------------------------------------------- | --------------------------- |
| Lowest context overhead, explicit lookups                               | Skill                       |
| Claude decides when to retrieve, without being asked                    | MCP                         |
| Context Capsules, Knowledge Delta, and verified Ask as structured tools | MCP                         |
| Both, which is the common setup                                         | Both — they do not conflict |

## Project scope

For project-specific knowledge, install at the project scope. This writes a `.claude/settings.json` in the current project instead of the user-level config.

```
gno mcp install --target claude-code --scope project
```

Pair this with a committed [project profile](https://gno.sh/docs/project-profiles) so the repository declares what should be indexed and everyone who clones it gets the same retrieval setup.

## Context Capsules from Claude Code

Ask Claude to compile one [Context Capsule](https://gno.sh/docs/context-capsules) for a goal, reason only from that evidence, and cite `evidenceId` values. You get a bounded, auditable payload instead of five searches filling the window.

> “Build a Context Capsule for why we dropped the queue rewrite, then answer only from its evidence and tell me if coverage is incomplete.”

The bundled skill recipes encode this and related workflows. Preview one with `gno skill show --file recipes/brain-first-lookup.md`.

## Search past Claude Code sessions

Connecting Claude Code imports none of its conversations. To search earlier sessions, import them manually into a dedicated archive outside your vault, then query it with its own config and index:

```
gno --config ~/gno-sessions/archive.yml --index sessions sessions source add claude --harness claude-code --path ~/.claude/projects --collection sessions-work
gno --config ~/gno-sessions/archive.yml --index sessions sessions import --source claude
gno --config ~/gno-sessions/archive.yml --index sessions query "why did we drop the queue rewrite" --category harness/claude-code --author human
```

Run sessions init once first. Tool calls, reasoning, injected context, and claude -p prompts are excluded; assistant turns are labelled as assistant output. [Read the session archive guide](https://gno.sh/docs/sessions).

## Session archive hook (opt-in)

Installing the MCP server or the skill never installs a hook. To keep the archive current after each session, opt in explicitly:

```
A="gno --config ~/gno-sessions/archive.yml --index sessions"
$A sessions source add claude-code --harness claude-code --path ~/.claude/projects --collection sessions-work
$A sessions automation set claude --source claude-code
$A sessions automation preview claude        # shows the exact hook command and settings file
$A sessions automation enable claude --hook claude-code
$A daemon --detach                            # performs the imports
```

`enable --hook claude-code` adds one SessionEnd entry to `$CLAUDE_CONFIG_DIR/settings.json` (else `~/.claude/settings.json`; pass `--settings` for another, existing file), keeps the previous file as settings.json.bak, and leaves every other hook untouched. When a session ends, the hook marks the profile pending in about 70 ms and returns; the import runs in gno daemon, never inside Claude Code. Set `GNO_SESSIONS_HOOKS=off` to silence it, `sessions automation disable claude --hook` to pause and remove the entry, and `sessions automation remove claude` to uninstall the profile. The hook works with Claude Code 2.1.280 for non-interactive claude -p runs. SessionEnd may not fire when you leave an interactive session with /exit, so add a daemon schedule if those sessions should be archived too. See [Automation](https://gno.sh/docs/sessions#automation-opt-in).

## Verifying and troubleshooting

- `gno skill paths` shows exactly where the skill was written; `gno mcp status` reports configuration presence.
- Neither command proves the client loaded anything. The real check is asking Claude Code for something only your corpus knows and seeing a citation into your files.
- No results at all? Run `gno doctor`. Lexical activation and semantic readiness are reported separately, and semantic can be legitimately pending while embeddings run.
- Tools missing after a GNO upgrade? Reinstall with `--force`, then restart the client.
- Wrong workspace? `gno mcp install --dry-run --json` prints the exact command, arguments, index, config, data, and cache paths that would be recorded.