Install GNO

Quickstart

Index a local folder and prove BM25 in under five minutes; semantic search and Ask follow once models download.

Index a local folder and prove BM25 in under five minutes; semantic search and Ask follow once models download. Skip downloads with --no-semantic or GNO_NO_AUTO_DOWNLOAD=1. Most users reach GNO from Claude Code, Claude Desktop, Cursor, Codex, OpenClaw, or Hermes Agent. This guide installs that connector after lexical proof. If GNO is not installed yet, start with installation.

No separate daemon installation is required. Models load on first use and unload after five idle minutes by default, so the first semantic request after a pause is slower. See runtime timeouts and runtime requirements.

1. Set up and prove your documents

A folder can be Markdown, PDF, Office, plain text, code, portable mail or calendar exports, transcripts, JSONL, browser exports, or a mix.

gno setup ~/notes --name notes
gno setup ~/Documents --name docs --exclude .env --exclude private
gno setup ~/Documents --name docs --no-semantic

Prefer a guided UI? Start gno serve, open http://localhost:3000, and use the first-run checklist to add a folder, pick a preset, and start indexing with zero CLI commands.

Setup returns only after an exact corpus-derived BM25 result. Reruns reuse the canonical folder and receipt. Semantic work is one-shot and independent; --no-semantic starts none. Add repeatable --connector flags for explicit agent handoffs.

--exclude is repeatable and literal. Likely credentials, private keys, and environment files fail closed unless an interactive default-No prompt is accepted or --authorize-secret-risk is passed explicitly. --yes, JSON, non-terminal input, decline, and EOF never authorize secret risk.

2. Finish semantic indexing

gno index

Lexical indexing is already proven. This finishes vector indexing. GNO handles Markdown, PDF, DOCX, XLSX, PPTX, plain text, JSONL, EML/MBOX, ICS, WebVTT/SRT, and explicit browser-export files.

On first run, GNO may download local embedding, reranking, expansion, or generation models. Cache use varies by the selected artifacts and quantization. To skip startup downloads, set GNO_NO_AUTO_DOWNLOAD=1 and run gno models pull explicitly.

Cached GGUF files are validated before load, so intercepted HTML or other non-model responses are removed with a clear recovery error.

gno ls

3. Prove retrieval works

gno doctor
gno status --json

Readiness is not inferred from an existing database or downloaded model. GNO derives a bounded probe from each indexed collection and proves that local lexical search can return the expected document. The same activation result appears in doctor, status, the REST API, and the Web UI. Semantic readiness is independent: it can remain pending while embeddings or local models catch up without hiding a successful lexical proof.

4. Connect your AI tools

Installed skills and MCP tools search the local index and return cited snippets into the client. Pick one or both integration paths:

Skills — for agents

Installs GNO as a /gno slash command. The agent loads GNO workflows when the skill is invoked or selected for a relevant task. Works with Claude Code, Codex, OpenCode, OpenClaw, and Hermes Agent.

gno skill install --target claude --scope user
gno skill install --target codex --scope user
gno skill install --target opencode --scope user
gno skill install --target openclaw --scope user
gno skill install --target hermes --scope user
gno skill install --target all --scope user # install everywhere

Teach your harness how to retrieve

For a second brain or LLM wiki, install the connector and the retrieval protocol together. The skill or MCP connector gives the harness access to GNO. The instruction block teaches when to retrieve, how to choose an efficient search path, and how to cite and maintain knowledge.

gno agents install
gno agents verify

This covers detected supported harnesses. Use --target codex, for example, to select one. Text outside the managed block stays unchanged. See agent instructions for supported targets and clients that need manual guidance. Start a fresh session and ask a question answered by your indexed files; verify retrieval and a source citation. The verify command checks the block, not model behavior.

MCP — for AI assistants and editors

Installs GNO as a Model Context Protocol server for ten named targets: Claude Desktop, Claude Code, Cursor, Codex, Zed, Windsurf, OpenCode, Amp, LM Studio, and LibreChat. Raycast and other compatible clients use manual MCP configuration.

gno mcp install --target claude-desktop
gno mcp install --target cursor
gno mcp install --target zed
gno mcp install --target windsurf
gno mcp install --target claude-code # MCP for Claude Code
gno mcp install --target claude-code --tool-profile core # 7-tool core profile
gno mcp status # see what's configured, and each registration's profile

--tool-profile core writes the slim 7-tool profile into the registration (add --enable-write for capture and remember); omitting it keeps the default full profile. Rerun with --force --tool-profile <profile> to switch an existing client.

--force on an existing GNO entry repairs it rather than replacing it: GNO rewrites the Bun and GNO paths and keeps the rest of the entry (index, config, tool profile, write access, environment, and settings you added such as a timeout) unless you pass that option again. Run it after upgrading Bun or GNO, or when gno doctor reports a registration on an old or missing Bun.

When Bun comes from a version manager such as mise or Homebrew, the registration names the manager’s version-independent link (for example mise’s installs/bun/latest or Homebrew’s opt/bun), so a Bun upgrade reaches your clients. If no such link points at the Bun you ran the install with, the install output says the registration stays on that version.

Restart the client after install. The client can then call GNO. Example prompts: “Search my notes for deployment procedures” or “Find architecture docs related to this change”.

In the Web UI, open Connectors and use the explicit read-only verification action for an installed MCP target. It starts that configured MCP command, checks its tools and status, and runs a collection-scoped search without changing client configuration. Installed skill files can be detected, but the client’s skill runtime cannot be invoked safely from GNO; those targets report unverifiable rather than passed.

The installer pins the current Bun + GNO package runtime, active index, and absolute config, data, and cache roots. The client therefore opens the same workspace as the CLI even when launched outside your shell.

If you prefer the terminal, GNO exposes three search modes for different trade-offs between speed and depth.

# Fast keyword search (~5–20ms)
gno search "project deadlines"

# Questions in plain words: keyword + meaning, start here
gno query "how do we handle errors" --fast

# Meaning only: similar ideas in different words
gno vsearch "how to handle errors"

# Hybrid with expansion + rerank, when --fast misses
gno query "authentication best practices"

# AI answer with citations
gno ask "what is the main goal of project X" --answer

Use gno capture when you want to add a quick note to an editable collection with provenance metadata and an optional typed preset scaffold.

gno capture "thought to remember"
gno capture --file ./clip.md --source-url https://example.com --source-kind web --json
gno capture --preset person --title "Jane Doe" --folder people/
gno capture --preset meeting --title "Weekly sync" --folder meetings/

Output formats

Search and read commands accept --json, --files, --csv, and --md:

gno search "important" --json
gno search "important" --files
gno search "important" --csv
gno search "important" --md

Next steps

Typed metadata filters

After setup, custom metadata is optional: add nested gno.metadata fields to a note, run gno update, and constrain retrieval with a typed filter. Existing search commands work unchanged without a filter.

Read the metadata guide: examples, operators, missing fields, limits, and recovery.