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.

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 tools only when /gno is invoked. 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

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 status # see what's configured

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"

# Meaning-based search (~0.5s)
gno vsearch "how to handle errors"

# Hybrid: BM25 + vector + rerank
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