Install GNO

Claude Code integration

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

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?

WantInstall
Lowest context overhead, explicit lookupsSkill
Claude decides when to retrieve, without being askedMCP
Context Capsules, Knowledge Delta, and verified Ask as structured toolsMCP
Both, which is the common setupBoth — 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 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 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.

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.

Verifying and troubleshooting