Karst

karst

Know what your change breaks — without your code leaving your machine. karst gives any AI coding tool — Cursor, Claude Desktop, a custom agent — a local map of your codebase. It answers questions with exact file:line citations and walks a real call / import / inheritance graph to compute the blast radius of a change — "what else breaks if I touch this?" — the question plain search and agentic grep can't answer.

It runs locally, speaks MCP (so it drops into any agent), and has no telemetry: the CLI sends nothing anywhere by itself. Indexing, search and impact analysis never call an LLM. Only karst ask and karst review do, and only when you have configured one. What leaves your machine lists every case. As a bonus, pack-scoped retrieval cuts ~60% of the input tokens per question.

Regulated, air-gapped, or IP-sensitive team? karst is built for the environments cloud coding tools structurally can't enter — fully offline, no telemetry, source you can audit. Start with What leaves your machine and the Compliance & Air-Gap Pack (attestation, network-egress table, pre-filled security questionnaire, offline install).

uv tool install karst      # recommended — fast, and puts `karst` on PATH for you
# or
pipx install karst         # isolated install, also handles PATH
# or
pip install karst          # if `karst` isn't found after, use `python -m karst …`

uv and pipx are the cleanest because they put the karst command on your PATH automatically. With plain pip --user (notably Microsoft Store Python) the command may not be on PATH — in that case python -m karst … always works, no PATH setup required.

First run: what gets downloaded

karst's own code makes no network requests, but two of its dependencies fetch files the first time they are needed. Both are cached on disk, so each happens once.

1. Tree-sitter parsers (tree-sitter-language-pack). Its wheel contains no grammars: on first use of a language it downloads a parser bundle and unpacks that language's library. To fetch the six languages karst parses now, run this once with the Python environment karst is installed in:

   python -c "from tree_sitter_language_pack import get_parser; [get_parser(n) for n in ('python', 'javascript', 'typescript', 'go', 'rust', 'java')]"
   

   .tsx files are parsed with the typescript grammar, so there is no separate tsx entry. The cache is per user and per tree-sitter-language-pack version, not per virtual environment, so any Python with the same version installed fills it. That helps for uv tool and pipx installs, where karst lives in a private environment.

2. Embedding model (BAAI/bge-small-en-v1.5, about 65 MB, from huggingface.co) on the first index, quickstart, ask, review or MCP search_code. Run karst quickstart once on any small repo to fetch it, then set KARST_OFFLINE=1 to forbid further model downloads.

Parser download details, for tree-sitter-language-pack 1.9.1 (the version pinned in pyproject.toml):

After that command has run once, analyze, graph-index and impact make no network requests. When a language's library is in the cache, the pack loads it from disk and never contacts GitHub; with all six cached it works with no manifest and no network. This holds while the cache folder for that version is intact: a different tree-sitter-language-pack version uses a different cache folder and would download again.

Do not use the pack's own download([...]) for this. In 1.9.1 it returns without fetching anything for languages the pack already lists; calling get_parser, which is what karst does, is what fetches. KARST_OFFLINE=1 covers the embedding model only, not the parsers.

The parser download happens in the pack's native code, not in Python. A Python-level network hook (a socket.socket monkeypatch, or an audit hook on socket.connect) does not see it, so it cannot show whether karst went online. Check at the OS level instead: a firewall log, or strace -f -e trace=network on Linux.

Why

Most "chat with your codebase" tools dump tens of thousands of vaguely-related tokens into the model on every question. You can't see what was loaded, you can't scope it, and the bill arrives at the end of the month. karst inverts that:

• Scopes — pack-filtered retrieval reads ~200 chunks, not 5,000.
• Cites — every chunk carries an exact file:line. Verify, don't trust.
• Predicts — a real call/import graph answers "what else breaks if I change this?" — which embeddings alone can't.

Measured on a real 246-file NestJS + Next.js repo: 906 chunks indexed, re-index 343s → 2.3s incremental, ~$0.019 per question on Sonnet 4.6 (shown before the call), 60% fewer tokens with packs attached.

Quickstart (CLI)

karst command not found? Your Python Scripts dir isn't on PATH (common with Microsoft Store Python). Everything below works the same with python -m karst … — no PATH setup. (Or install via uv/pipx, which put karst on PATH for you.)

cd your-project

# one command: index + call/import graph + suggested packs
karst quickstart                 #  or:  python -m karst quickstart

# ask questions about the code (defaults to this folder's index)
karst ask "how does checkout charge the user?" --no-llm    # cited code, no API key
karst ask -i                     # interactive: ask many questions

# what breaks if I change a function? (run inside the project; it finds the graph itself)
karst impact --target checkout

# review a diff with severity-tagged, cited findings
karst review --staged --storage ~/.karst/indexes/<your-project>-<hash>   # the path quickstart prints

karst examples                   # a copy-paste cheatsheet of everything

karst quickstart prints the exact follow-up commands with your index path filled in. karst ask writes an LLM answer when ANTHROPIC_API_KEY / OPENAI_API_KEY is set, which sends the retrieved code to that provider (see What leaves your machine); add --no-llm for cited chunks and no network call. The MCP server below needs no key either — your IDE supplies the model.

Use it from your IDE (MCP)

karst ships an MCP server (karst-mcp) exposing five tools — search_code, find_impact, list_packs, index_status, index_repository — over stdio.

Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json) — pick whichever launcher you have:

{
  "mcpServers": {
    "karst": { "command": "uvx", "args": ["--from", "karst", "karst-mcp"] }
  }
}

uvx needs nothing pre-installed — it fetches and runs karst on demand. Already installed it? { "command": "karst-mcp" } works too. No PATH at all? Use { "command": "python", "args": ["-m", "karst.mcp_server"] }.

Restart the host, then ask normally — it calls karst's tools when useful and gets back scoped, cited context. Full setup is in docs/MCP.md.

Guides

New here? Start with whichever fits you:

• Why karst? — what it is and what it's for, in plain language. Read this first if you're not sure what problem it solves.
• Quickstart — zero to asking real questions in 5 minutes, no API key, with real output.
• For vibe coders — use karst from Cursor / Claude Desktop with no CLI commands — you just chat.
• Connect your AI tool — copy-paste MCP setup for every client: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Zed, JetBrains, plus the web apps.
• Self-hosted & air-gapped — run karst and the AI answers fully on your machine with a local model. For teams whose code can't go to the cloud.
• Cookbook — real scenarios (onboarding, blast radius, cutting token cost, reviewing a diff) with copy-paste commands.
• MCP setup — connect karst to any MCP client.

How it works

1. Index — tree-sitter splits every function, class and method into an AST-aware chunk (Python, JS, TS, Go, Rust, Java); chunks are embedded into a local Qdrant store. Incremental: a SHA manifest + embedding cache skip unchanged files.
2. Graph — a NetworkX knowledge graph of CALLS / IMPORTS / CONTAINS / IMPLEMENTS edges powers impact analysis ("what depends on this?" — including which classes implement an interface or extend a base).
3. Pack — related files become named, attachable context packs (auth, billing). A query loads only its pack.
4. Serve — the MCP server returns ranked, file:line-cited chunks; your host's model reasons over them.

Everything is local and offline-capable (FastEmbed/ONNX embeddings, Qdrant local mode, sqlite caches — no Docker, no daemon). The one-time downloads and every path that can reach the network are listed below.

What leaves your machine

The CLI has no telemetry, analytics, update check or phone-home, and karst's own code contains no HTTP client. Network traffic comes only from the rows below. Each one is either a one-time download that sends none of your data, or something you start or configure.

Which LLM ask and review use: --llm (ask only) or KARST_LLM_PROVIDER if set; otherwise a local server if KARST_LLM_BASE_URL is set; otherwise Anthropic if ANTHROPIC_API_KEY is set; otherwise OpenAI if OPENAI_API_KEY is set. An API key that is already in your shell for another tool is enough to make karst ask send code chunks to that provider. Use --no-llm for cited chunks and no call, or --llm local / KARST_LLM_PROVIDER=local for a local model; the local server URL defaults to http://localhost:11434/v1 (Ollama), and if you point KARST_LLM_BASE_URL at a remote host the prompt goes there. The Anthropic and OpenAI SDKs are optional extras (karst[anthropic], karst[openai], karst[llm]); a plain pip install karst cannot call either, and the local option uses the openai extra.

The vector store (Qdrant) runs in embedded local-file mode under ~/.karst/indexes/; there is no remote Qdrant option. Once the embedding model is cached, FastEmbed loads it from disk without a request, and KARST_OFFLINE=1 turns a missing model into an error instead of a download. The model download goes through Hugging Face's client library, which has its own usage-telemetry switch (HF_HUB_DISABLE_TELEMETRY=1); that setting belongs to that library, not to karst.

Status

Live: AST chunking (6 languages), call/import graph + impact analysis, pack-scoped retrieval, token + cost meter, incremental indexing + embedding cache, diff code review with inline PR posting (review --pr --post-to-pr), and the MCP server over both stdio and remote Streamable-HTTP (karst-mcp --http). Coming next: hosted indexing, team-shared pack libraries, an autonomous GitHub PR review bot, and OAuth for browser connectors (claude.ai / ChatGPT).

License

Apache-2.0. See LICENSE.