Skip to content

v0.1.0

Choose a tag to compare

@github-actions github-actions released this 24 Oct 16:13
· 22 commits to main since this release

scree v0.1.0

First release. scree gives Claude Code search over a repo's markdown: by meaning, and by exact identifiers. It runs locally as an MCP server, and each repo opts in.

Highlights

  • Per-repo, opt-in. Register scree in a repo's committed .mcp.json with claude mcp add scree --scope project -- scree mcp. Each repo gets its own index, stored outside the repo.
  • Search that fits how docs are used.
    • auto (the default) uses semantic search for plain questions, and adds keyword search when a query contains an identifier like MAX_RETRIES or R7-Q2.
    • semantic, keyword and hybrid are available explicitly. keyword needs no API call.
  • Precise hits.
    • Each result gives its file, heading trail and line range (docs/api.md:486-492).
    • If the file changed since indexing, the range is relocated, or the hit is marked stale.
    • Duplicate copies fold into one hit, listed under also=.
  • Respects your repo.
    • Follows .gitignore with git's rules, including nested files, info/exclude and your global excludes.
    • Indexes markdown in .github/, .claude/, .cursor/ and similar folders at the repo root.
    • Supports .screeignore and scree: ignore front matter.
    • scree run doctor -v shows what's indexed and ignored, with a cost estimate.
  • Stays current. One session per repo indexes in the background and watches for changes; other sessions share the index.
  • Cheap and light. About $0.0025 per MB of markdown to index once, through OpenRouter with zero data retention requested. About 13–20 MB of memory per process. A single static binary.

Install

  • Download the archive for your platform below, or docker pull ghcr.io/jrapakko/scree:0.1.0.
  • Put scree on your PATH (for example ~/.local/bin).
  • Write ~/.config/scree/env (mode 600) containing OPENROUTER_API_KEY='…'.
  • In a repo: claude mcp add scree --scope project -- scree mcp, then commit .mcp.json.

Full guide: https://scree.jrpko.dev/getting-started.html

Security notes

  • The settings file is the only source of configuration. scree mcp re-runs scree with a clean environment.
  • scree takes the indexed folder from where Claude Code started it, refuses folders that haven't opted in, and never indexes your home directory.
  • Approving scree in a repo's .mcp.json means trusting that repo: Claude Code applies the repo's env, including PATH, which decides which program runs. Only approve it in repos you trust. Details: https://scree.jrpko.dev/security.html

Known limitations

  • On Windows, scree mcp and scree run aren't supported yet. Run scree serve directly.
  • On macOS, the binary links the system library dynamically, so DYLD_INSERT_LIBRARIES from a repo's .mcp.json can reach it. That falls within the repo-trust note above.
  • Docker on SELinux hosts needs SCREE_MOUNT_OPTS=ro,z, which relabels the mounted folder.

Checksums are in checksums.txt. Licenses for bundled dependencies are in each archive under THIRD_PARTY_LICENSES/.

Changelog

  • bdd52c9 Add MIT license, CI, and GoReleaser/GHCR release workflow
  • 8c339c0 Docs: match the code before v0.1.0
  • 0fd9bac Fix pass: ignore rules, red-team fixes, ZDR, Docker, key-safe wrappers
  • de7d0a4 Initial scree: semantic search over markdown notes via MCP
  • e76e251 Merge branch 'main' into per-repo
  • d1af508 Merge branch 'main' into per-repo
  • 5ff78d5 README: add Quick start; keep the API key out of shell profiles
  • 107e772 SPEC: record open items, including local and LAN embedding models
  • 1c7d72e Tests: don't expect one watcher event per file on macOS
  • aa579d4 Tests: pass when the temp dir is behind a symlink (macOS)
  • cb88f0a Use invented example identifiers in tests and docs
  • fa35156 Wrappers read the settings file as data; scrub the key before truncating
  • 7f14b84 Wrappers: re-exec once in an empty environment before running anything
  • 41fad78 Wrappers: the settings file is the only source of configuration
  • a337551 per-repo step 4: folder from -notes or CLAUDE_PROJECT_DIR, per-folder index
  • f298b98 per-repo step 4b: canonical on-disk names, NFC and case folding, read races
  • b97e7d1 per-repo step 4c: file rules beat folder negations, looser front matter, search re-checks
  • 66a5ecf per-repo step 5: writer lock per index, background sync in serve, watcher split
  • be4f2d1 per-repo step 5c-1: no symlinked git files, no echoed content, serve uses only the repo
  • a369232 per-repo step 5c-2: FIFO-safe reads, bounded shutdown, trust only your own .git, fast Canonical
  • e526434 per-repo step 6-1: search_docs/read_doc, line ranges, cost estimate, first-sync cap
  • 17bb689 per-repo step 6-2: current line ranges for changed files, duplicate collapse
  • 4def87d per-repo step 6b: hybrid search (FTS5 keyword index + vectors, RRF)
  • c2a2afe per-repo step 7: scree indexes [-prune]
  • 2967301 per-repo step 8: final README and SPEC; settings file always from passwd home
  • 5ba5bc3 per-repo steps 1-3: git-style ignores, hidden-folder allowlist, watcher pruning
  • ee50679 per-repo: final fix round (red-team round 4, final verifier)
  • d56292d policy: let TestUnsafeName run where the filesystem refuses a name
  • 6a575f9 policy: map paths that reach the notes folder through another symlink
  • 0425233 scree mcp / scree run: the launchers move into the static binary
  • fcd92a3 scree-mcp-docker: never pull the image
  • 7c56901 search: auto is the default mode