scree

scree

Local semantic search over the markdown in your repos and notes, served to Claude Code over MCP.

Scree splits markdown by heading, embeds the pieces through an API, and stores them in a SQLite file on disk, one index per folder. Claude Code asks for the few chunks that match a question instead of loading whole files. Each hit says which lines it came from, so Claude can read just those. The markdown stays the source of truth; an index can be deleted and rebuilt at any time.

See docs/SPEC.md for the design.

Quick start

You need Go 1.26 and an OpenRouter API key from https://openrouter.ai/settings/keys. The commands run from the root of this repo unless a step says otherwise.

1. Build a static binary (no CGO):

   CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o bin/scree ./cmd/scree

1. Save the key in the settings file. scree key prompts for it without echoing it, so it never lands in your shell history or on screen, writes ~/.config/scree/env with mode 600, and makes one test call to the API:

   bin/scree key

It keeps any other lines in the file and replaces an earlier key. scree key < file reads the key from the first line of a file instead, and replaces a saved key only with -replace; -offline skips the test call, and -check makes only the test call. Ctrl-C at the prompt saves nothing. To see Claude Code's OpenRouter costs apart from your own searches, save a second key with bin/scree key -mcp: scree mcp then uses it, and everything else keeps the first (settings file).

1. Install the binary:

   mkdir -p ~/.local/bin

install -m 755 bin/scree ~/.local/bin/

Claude Code must find scree on its PATH. If ~/.local/bin isn't on it, add it in your shell profile.

1. Check a repo before indexing it. scree run loads the settings file and runs a scree command. From inside the repo:

   cd ~/code/myrepo

scree run doctor -v

doctor -v lists every file that will be ignored and estimates the cost of indexing the rest. Add a .screeignore or .gitignore entry before indexing if anything private shows up as indexable.

1. Turn scree on for the repo. From the repo's root:

   claude mcp add scree --scope project -- scree mcp

This writes .mcp.json with "command": "scree", "args": ["mcp"], with no key and no paths, so commit it. Claude Code asks each person to approve a project server once. Every session in the repo then keeps the index current; the first session builds it in the background. serve refuses a repo whose own .mcp.json doesn't name scree mcp, so a repo without this entry is never indexed, even if scree is also registered elsewhere. Don't register scree at user scope anyway.

Approving a project server means trusting the repo. Claude Code applies the env of a repo's .mcp.json, including PATH, before it starts the server, so a repo you approve decides which program scree is, and that program gets your settings file. Approve scree only in repos whose .mcp.json you trust, as you would any project server. To take that choice back for yourself, see absolute paths.

1. Optional: a notes folder outside any repo. See A notes folder.

Build

Requires Go 1.26. No CGO. Tagged releases also publish prebuilt binaries for Linux, macOS and Windows (amd64 and arm64) on the GitHub releases page, a ghcr.io/jrapakko/scree image, and a Claude Desktop bundle, which scripts/mcpb.sh zips from the release's binaries.

CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o bin/scree ./cmd/scree

Configure

Settings come from environment variables. The settings file is the one place to keep them, including the API key. Don't export the key in a shell profile. With OPENROUTER_API_KEY unset, a command run directly (scree search, doctor, reindex, watch) still uses the key in the settings file, by running as scree run would; see below.

$XDG_DATA_HOME defaults to ~/.local/share; a relative value is ignored. With neither it nor an absolute home directory, scree refuses to open an index unless -db names one.

Which folder. -notes names it on the command line. Without it, CLI commands use the git root of the current directory, or the current directory outside git. Under Claude Code, serve indexes the git root of the working directory Claude Code starts it in (the project, or the active worktree), refuses -notes, -db and SCREE_DB, and requires CLAUDE_PROJECT_DIR to be in the same repo; a .mcp.json can set environment variables but not the working directory. It also refuses a folder whose root .mcp.json names no scree mcp server. Outside Claude Code, serve has no default folder: pass -notes. A folder found automatically is refused if it is your home directory (from the password database, falling back to $HOME only if that lookup fails), a folder above it, or a filesystem root; on the command line, pass -notes to index it anyway. serve refuses such a folder even as -notes (a client such as Claude Desktop passes the folder a user picked) unless -allow-home is given. The check compares the folders themselves, not just their paths, so another path to your home folder (a bind mount, different letter case on macOS, /System/Volumes/Data/Users/…) is refused too. It only compares the chosen folder with your home folder and the folders above it, so a folder that holds a mount of your home somewhere inside it (as some containers and devcontainers set up) is not caught. Each index records its folder and refuses to be used for another one.

Changing the model or dimensions requires scree reindex -all. The index records which model built it and refuses to mix them.

Privacy

Every embedding request asks OpenRouter to route only to endpoints with zero data retention and data_collection: deny. A model with no such endpoint fails with a clear error naming the model, rather than falling back to one that keeps data. SCREE_ZDR=0 turns this off, which other OpenAI-compatible endpoints may need. Only chunk text, with its path and heading, is sent to the API; keyword search runs locally.

Ignoring files

An ignored file is never read for indexing, never sent to the embedding API, never returned by search, and refused by read_doc and reindex. Four layers decide:

• Built-in: hidden files and folders, except the root .claude/ (not .claude/worktrees/), .github/, .gitlab/, .gitea/, .forgejo/, .cursor/, .codex/, .gemini/, .windsurf/, .circleci/ and .buildkite/; anything that isn't .md, .markdown or .mdc; symlinks that lead outside the folder; files over SCREE_MAX_FILE_BYTES; non-regular files such as FIFOs, which are never opened and which doctor reports as unreadable; and names with control characters.
• `.gitignore`: in a git repo, everything git ignores (nested .gitignore files, .git/info/exclude, your global excludes file). Ignored folders such as node_modules/ are never read, and nested repositories are skipped. A tracked file that matches a pattern is still ignored. -gitignore=false turns this layer off.
• `.screeignore` at the root of the indexed folder, in gitignore syntax.
• Front matter: scree: ignore in a file's front matter.

# .screeignore

journal/ **/private-*.md /inbox/scratch.md !journal/public.md

include-hidden .name/ in .screeignore indexes another root hidden folder, and a pattern like /.cursor/ drops one of the defaults. A ! rule re-includes files inside an excluded folder, but never a file that a rule matched by name, so *.private.md stays ignored even under !archive/2024/; doctor -v lists what ! re-included. If .screeignore can't be read, is a symlink, or has a line scree can't parse, nothing is indexed until it is fixed; doctor names the bad lines by number.

---

scree: ignore

Run scree doctor -v to see what each layer ignores before relying on a pattern. The full rules are in docs/SPEC.md.

Use

scree key                # save the API key in the settings file

scree key -mcp # optional: a separate key for scree mcp (Claude Code) scree doctor # check config, index, and the API scree doctor -v # also list every ignored file, and check the keyword index scree reindex # index new and changed files scree reindex docs/a.md # re-index one file scree reindex -all # rebuild from scratch scree search "how do I rotate the backup keys" scree search -mode keyword PURGE_OLD_RECORDS # exact words, no API call scree search -format text "ci seed" # hits grouped by query word (the default on a terminal) scree search -no-pager "ci seed" # the same, printed without the pager scree search -format json "…" # one JSON object per hit scree search -format grep "…" # path:line:text, for fzf or vim -q scree watch # keep the index current (run as a service) scree serve -notes . # MCP over stdio, from a terminal scree serve -notes . -http 127.0.0.1:7077 # MCP over HTTP, loopback only scree indexes # list per-folder indexes; -prune deletes ones whose folder is gone

Every command but indexes and key takes -notes , -db and -gitignore=false. serve needs -notes outside Claude Code. From a terminal, search, reindex, doctor and watch run as scree run would whenever OPENROUTER_API_KEY is unset and the settings file holds a key; scree run loads the file in any case, for example scree run search "…".

Search modes

scree search -mode and the search_docs tool's mode take:

• `auto` (the default): semantic, unless the query has an identifier-like word, a word with a letter plus _ or a digit, such as PURGE_OLD_RECORDS, psycopg_pool, R7-Q2 or v2, or a word from the folder's