{"id":45806475,"url":"https://github.com/jrollin/cartog","last_synced_at":"2026-06-07T21:00:57.337Z","repository":{"id":340615087,"uuid":"1166636683","full_name":"jrollin/cartog","owner":"jrollin","description":"Pre-indexed code knowledge graph via treesitter, enchanced query with RAG, MCP server, private and local storage. Agent ready.","archived":false,"fork":false,"pushed_at":"2026-06-07T12:51:43.000Z","size":7544,"stargazers_count":11,"open_issues_count":6,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T14:21:34.519Z","etag":null,"topics":["claude","cli","lsp","lsp-server","mcp","rag","rlm","rust","skills","token","treesitter"],"latest_commit_sha":null,"homepage":"https://jrollin.github.io/cartog/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jrollin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"jrollin"}},"created_at":"2026-02-25T12:45:48.000Z","updated_at":"2026-06-06T17:29:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jrollin/cartog","commit_stats":null,"previous_names":["jrollin/cartog"],"tags_count":79,"template":false,"template_full_name":null,"purl":"pkg:github/jrollin/cartog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrollin%2Fcartog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrollin%2Fcartog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrollin%2Fcartog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrollin%2Fcartog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jrollin","download_url":"https://codeload.github.com/jrollin/cartog/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrollin%2Fcartog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34037777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","cli","lsp","lsp-server","mcp","rag","rlm","rust","skills","token","treesitter"],"created_at":"2026-02-26T14:04:47.920Z","updated_at":"2026-06-07T21:00:57.330Z","avatar_url":"https://github.com/jrollin.png","language":"Rust","funding_links":["https://github.com/sponsors/jrollin"],"categories":["Rust"],"sub_categories":[],"readme":"# Cartog\n\n[![CI](https://github.com/jrollin/cartog/actions/workflows/ci.yml/badge.svg)](https://github.com/jrollin/cartog/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/jrollin/cartog/branch/main/graph/badge.svg)](https://codecov.io/gh/jrollin/cartog)\n[![Crates.io](https://img.shields.io/crates/v/cartog.svg)](https://crates.io/crates/cartog)\n[![Crates.io downloads](https://img.shields.io/crates/d/cartog)](https://crates.io/crates/cartog)\n[![GitHub stars](https://img.shields.io/github/stars/jrollin/cartog)](https://github.com/jrollin/cartog)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n**Map your codebase. Navigate by graph, not grep.**\n\n**~280 tokens per query, 97% recall, 8 us to 20 ms latency, 12 languages.**\n\nSingle binary. Microsecond queries. 100% local by default.\n\nCartog pre-computes a code graph — symbols, calls, imports, inheritance — and lets you query it instantly. Use it from the CLI for day-to-day navigation, as an MCP server for AI agents, or both. No Python, no pip, no Docker. One binary, one SQLite file, zero cloud dependencies.\n\n\u003e **[Documentation site](https://jrollin.github.io/cartog/)**\n\n![cartog demo](docs/demo.gif)\n\n## Quick Start\n\n```bash\ncargo install cartog          # or download a binary from GitHub Releases\ncd your-project\ncartog init                   # 1. scaffold .cartog.toml\ncartog index                  # 2. build the code graph\n```\n\nThat's it for CLI use. Two commands.\n\nIf you want MCP wired into your editor (Claude Code, Cursor, VS Code, Claude Desktop, Codex CLI, Gemini CLI, OpenCode, Windsurf, Zed, Antigravity, Kiro, Hermes Agent), add one more:\n\n```bash\ncartog ide                    # optional — only if you want editor integration\n```\n\nAll three commands are idempotent.\n\nNow query:\n\n```bash\ncartog search validate        # find symbols by name         (sub-ms)\ncartog refs validate_token    # who calls this?              (\u003c 500 us)\ncartog impact validate_token  # what breaks if I change it?  (\u003c 20 ms)\ncartog outline src/auth.py    # file structure, no cat       (\u003c 15 us)\n```\n\n## Teach your agent to use cartog\n\nWiring MCP is half the job. The other half is telling the agent **when** to\nprefer cartog over grep + read. Drop the snippet from\n[docs/agent-snippet.md](docs/agent-snippet.md) into your project's `AGENTS.md`,\n`CLAUDE.md`, `.cursor/rules/`, or equivalent, and the agent will route\n\"where is X?\" / \"who calls X?\" / \"what breaks if I change X?\" through\ncartog's 16 MCP tools instead of flooding context with raw text.\n\n## Why Cartog\n\nEvery code navigation tool makes you choose: fast but shallow (grep), or precise but slow (language servers). Cartog gives you both.\n\n| | grep / cat / find | Language servers | **Cartog** |\n|---|---|---|---|\n| **Query speed** | depends on codebase size | seconds to start | **8-450 us** |\n| **Transitive analysis** | impossible | partial | **`impact --depth 5`** |\n| **Setup** | none | per-language config | **one binary, zero config** |\n| **Languages** | all (text) | one per server | **12 languages, one tool** |\n| **Token cost** (LLM context) | ~1,700 tokens/query | n/a | **~280 tokens/query** |\n| **Recall** (completeness) | 78% | ~100% | **97%** [*](#benchmark-notes) |\n| **Privacy** | local | local | **100% local** |\n\nMeasured across 13 scenarios, 10 languages ([benchmark suite](benchmarks/)).\n\n\u003ca id=\"benchmark-notes\"\u003e\u003c/a\u003e\n\u003e **\\*** 97 % recall requires a matching language server on PATH. The\n\u003e default build ships LSP support; heuristic-only resolution (no server\n\u003e found, or `--no-lsp`) lands around 25–37 %, with specifics varying by\n\u003e language.\n\n## What You Get\n\n### Fast structural queries\n\nPre-computed graph means no re-reading files, no multi-step discovery.\n\n```bash\ncartog search parse              # symbol name lookup (sub-ms)\ncartog refs UserService          # all callers, importers, inheritors\ncartog callees authenticate      # what does this function call?\ncartog impact SessionManager     # blast radius — callers-of-callers, depth N\ncartog hierarchy BaseService     # inheritance tree\ncartog deps src/routes/auth.py   # file-level imports\ncartog changes --commits 5       # symbols affected by recent git commits\ncartog map --tokens 4000         # codebase overview, ranked by centrality\n```\n\n### Semantic search (optional, still fully local)\n\n```bash\ncartog rag setup                 # download models (~1.2 GB, one-time)\ncartog rag index .               # embed symbols + docs into sqlite-vec\ncartog rag search \"authentication token validation\"\n```\n\nThree-tier hybrid pipeline: **FTS5 keyword** + **vector KNN** + **cross-encoder re-ranking**. Indexes both code (functions, classes, methods) and Markdown documents. Models run locally via ONNX Runtime — no API keys, no network calls.\n\n\u003e **Prefer Ollama or a hosted endpoint?** Set `provider = \"ollama\"` or `provider = \"openai\"` (any OpenAI-compatible `/v1` endpoint) in `.cartog.toml`. See [Configuration](#configuration).\n\n### Live index\n\n```bash\ncartog watch .                   # auto re-index on file changes\ncartog watch . --rag             # also re-embed (deferred, non-blocking)\n```\n\n### MCP server for AI agents\n\n```bash\ncartog serve                     # 16 tools over stdio\ncartog serve --watch --rag       # with live re-indexing + semantic search\n```\n\nWorks with Claude Code, Cursor, Windsurf, Zed, OpenCode — any MCP client.\n\n### LSP precision, built in\n\nCartog auto-detects language servers on PATH (rust-analyzer, pyright, typescript-language-server, gopls, ruby-lsp, solargraph, jdtls, intelephense, dart, sourcekit-lsp, kotlin-language-server) and uses them to boost edge resolution from ~25% to **up to 81%**. Enabled by default; results persist in SQLite — pay the cost once. Disable at runtime with `--no-lsp`, or omit at build time with `cargo install cartog --no-default-features`.\n\n## Install\n\n### Install script (macOS / Linux, no Rust required)\n\n```bash\ncurl -fsSL https://jrollin.github.io/cartog/install.sh | sh\n```\n\nDetects your OS + architecture, downloads the matching binary from the latest\nGitHub Release, verifies its SHA-256, and installs to `/usr/local/bin` (or\n`~/.local/bin` if non-root). Override with `CARTOG_INSTALL_DIR`; pin a\nversion with `CARTOG_VERSION=\u003cversion\u003e` (e.g. the tag from [Releases](https://github.com/jrollin/cartog/releases)). Audit the script: [`scripts/install.sh`](scripts/install.sh).\n\n### From crates.io (Rust toolchain required)\n\n```bash\ncargo install cartog                                  # default: LSP + S3 sync + Ollama + OpenAI providers\ncargo install cartog --no-default-features            # minimal: drops LSP, S3, Ollama, OpenAI\ncargo install cartog --no-default-features --features lsp  # LSP only\n```\n\n### Pre-built binaries (manual)\n\n```bash\n# macOS (Apple Silicon)\ncurl -L https://github.com/jrollin/cartog/releases/latest/download/cartog-aarch64-apple-darwin.tar.gz | tar xz\nsudo mv cartog /usr/local/bin/\n\n# Linux (x86_64)\ncurl -L https://github.com/jrollin/cartog/releases/latest/download/cartog-x86_64-unknown-linux-gnu.tar.gz | tar xz\nsudo mv cartog /usr/local/bin/\n\n# Linux (ARM64)\ncurl -L https://github.com/jrollin/cartog/releases/latest/download/cartog-aarch64-unknown-linux-gnu.tar.gz | tar xz\nsudo mv cartog /usr/local/bin/\n\n# Windows (x86_64) — download .zip from releases page\n```\n\n### Upgrade\n\nOnce cartog is on your `PATH`:\n\n```bash\ncartog self update           # upgrade in place to the latest stable\ncartog self update --check   # report whether an update exists; exit 1 if outdated\ncartog self version          # show installed version + last-check timestamp\ncartog self rollback         # restore the previous binary\n```\n\nCargo-installed binaries upgrade with `cargo install cartog --force`. See [docs/updates.md](docs/updates.md) for env vars, exit codes, and the state file location.\n\n### Agent integration: which path?\n\nThree setup paths for agents and editors. Pick the one that matches your stack — they are alternatives, not steps.\n\n| Path | Use it when | What you get |\n|---|---|---|\n| `cartog ide` | You want MCP wired into one or more editors (Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI, Claude Desktop, OpenCode, Windsurf, Zed, Antigravity, Kiro, Hermes Agent). | MCP entries written to the right files; interactive picker if you run it without flags. |\n| Claude Code plugin | You are on Claude Code and want install + skill + MCP wired in one step. | Bundled: binary install, behavioural skill, MCP server, all preconfigured. |\n| Agent skill | You use an agent that follows the skills protocol (Cursor, Copilot, others) and only need the behavioural rules, not MCP. | Skill files installed into the agent's skill directory; works alongside any install method. |\n\n### Claude Code plugin\n\nRun these two commands **one at a time** in Claude Code:\n\n```bash\n/plugin marketplace add jrollin/cartog\n```\n\n```bash\n/plugin install cartog@cartog-plugins\n```\n\n**First session**: if the cartog binary is not already on your PATH, the plugin starts a background install and prints a one-line notice. The cartog MCP server cannot start in this first session because the binary lands after Claude Code has already tried to spawn it.\n\n**Second session**: restart Claude Code. The MCP server starts, code-graph tools become available, and the SessionStart hook keeps the index fresh on every subsequent session.\n\n**Repair or upgrade**: type `/cartog-install` at any time to install the binary synchronously (e.g. to retry a failed background install), or to upgrade an existing install to match the plugin's pinned version. The skill at [`skills/cartog-install/`](skills/cartog-install/SKILL.md) handles both cases.\n\n**Offline / vetted install**: the manual fallback is the same one used by the curl one-liner at the top of this section: download [`scripts/install.sh`](scripts/install.sh) (mirrored at `https://jrollin.github.io/cartog/install.sh`), inspect it, then run it.\n\n### Agent Skill (Cursor, Copilot, others)\n\n```bash\nnpx skills add jrollin/cartog\n```\n\n## Why Not...\n\n**grep/ripgrep?** Great for string literals and config values. But grep can't trace call chains, can't do transitive impact analysis, and floods your context with raw text. Cartog returns structured, ranked, deduplicated results — one `refs` call replaces 6+ discovery steps.\n\n**A language server?** LSPs give perfect precision but require per-language setup, take seconds to start, and only cover one language at a time. Cartog covers 12 languages with one binary and answers in microseconds. When you need LSP precision, cartog can use it as an optional layer.\n\n**Python-based graph tools?** They solve a similar problem but require a Python runtime, pip dependencies, and virtual environments. Cartog is a single static binary — download and run. It also queries 10-100x faster thanks to compiled Rust + SQLite.\n\n## MCP Server Setup\n\nFastest path: let cartog write the right config for your editor.\n\n```bash\ncartog ide                                  # all installed clients, all scopes\ncartog ide --client cursor                  # one client\ncartog ide --client claude-desktop --dry-run  # preview without writing\n```\n\nIdempotent. Existing servers in each file are preserved.\n\nPrefer the brew/npm shape? `cartog install` takes editors as positional args\nand is always non-interactive — safer than `cartog ide` for scripts and agents:\n\n```bash\ncartog install cursor                 # one editor\ncartog install cursor vscode codex    # several at once\ncartog install                        # all detected editors\ncartog install cursor --dry-run       # preview\n```\n\nPrefer to wire it yourself? Pick your client below.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Code\u003c/strong\u003e — project-scoped \u003ccode\u003e.mcp.json\u003c/code\u003e or user settings\u003c/summary\u003e\n\nOne-shot:\n\n```bash\ncartog ide --client claude-code             # writes .mcp.json + user settings\nclaude mcp add cartog -- cartog serve --watch       # user scope\nclaude mcp add --scope project cartog -- cartog serve --watch\n```\n\nManual (`\u003crepo\u003e/.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"cartog\": { \"command\": \"cartog\", \"args\": [\"serve\", \"--watch\"] }\n  }\n}\n```\n\n\u003e Only Claude Code gets `--watch` by default — the others ship plain `[\"serve\"]`.\n\u003e Agent-driven flows churn files faster than human-driven editor flows, so the\n\u003e in-process file watcher pays off. Drop `--watch` with `cartog ide --no-watch`\n\u003e if you don't want it.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCursor\u003c/strong\u003e — project \u003ccode\u003e.cursor/mcp.json\u003c/code\u003e or user settings\u003c/summary\u003e\n\nOne-shot:\n\n```bash\ncartog ide --client cursor\n```\n\nManual:\n\n```json\n{\n  \"mcpServers\": {\n    \"cartog\": { \"command\": \"cartog\", \"args\": [\"serve\"] }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCodex CLI\u003c/strong\u003e — user-only TOML at \u003ccode\u003e~/.codex/config.toml\u003c/code\u003e\u003c/summary\u003e\n\nOne-shot:\n\n```bash\ncartog ide --client codex\n```\n\nManual:\n\n```toml\n[mcp_servers.cartog]\ncommand = \"cartog\"\nargs = [\"serve\"]\n```\n\nCodex is user-global only. If you use cartog on multiple projects, `cartog ide`\nauto-names each section `cartog-\u003cslug\u003e-\u003chash8\u003e` so they coexist.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWindsurf\u003c/strong\u003e — \u003ccode\u003e~/.codeium/windsurf/mcp_config.json\u003c/code\u003e\u003c/summary\u003e\n\n```bash\ncartog ide --client windsurf\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"cartog\": { \"command\": \"cartog\", \"args\": [\"serve\"] }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eVS Code (GitHub Copilot)\u003c/strong\u003e — project \u003ccode\u003e.vscode/mcp.json\u003c/code\u003e\u003c/summary\u003e\n\n```bash\ncartog ide --client vscode\n```\n\nNote: VS Code's top-level key is `servers` (no `mcp` prefix):\n\n```json\n{\n  \"servers\": {\n    \"cartog\": { \"type\": \"stdio\", \"command\": \"cartog\", \"args\": [\"serve\"] }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eZed\u003c/strong\u003e — \u003ccode\u003e~/.config/zed/settings.json\u003c/code\u003e\u003c/summary\u003e\n\n```bash\ncartog ide --client zed\n```\n\n```json\n{\n  \"context_servers\": {\n    \"cartog\": { \"command\": \"cartog\", \"args\": [\"serve\"] }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eOpenCode\u003c/strong\u003e — \u003ccode\u003e~/.config/opencode/opencode.json\u003c/code\u003e\u003c/summary\u003e\n\n```bash\ncartog ide --client opencode\n```\n\n```json\n{\n  \"mcp\": {\n    \"cartog\": {\n      \"type\": \"local\",\n      \"command\": [\"cartog\", \"serve\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eGemini CLI\u003c/strong\u003e — \u003ccode\u003e~/.gemini/settings.json\u003c/code\u003e\u003c/summary\u003e\n\n```bash\ncartog ide --client gemini\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"cartog\": { \"command\": \"cartog\", \"args\": [\"serve\"] }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Desktop\u003c/strong\u003e — \u003ccode\u003eclaude_desktop_config.json\u003c/code\u003e\u003c/summary\u003e\n\n```bash\ncartog ide --client claude-desktop\n```\n\nManual (macOS: `~/Library/Application Support/Claude/`; Windows: `%APPDATA%\\Claude\\`):\n\n```json\n{\n  \"mcpServers\": {\n    \"cartog\": { \"command\": \"cartog\", \"args\": [\"serve\"] }\n  }\n}\n```\n\nRestart Claude Desktop after editing.\n\u003c/details\u003e\n\nSee [docs/mcp-setup.md](docs/mcp-setup.md) for the canonical long-form reference,\nincluding the path-naming scheme for Codex's multi-project setup, and\n[docs/usage.md](docs/usage.md#mcp-server) for all `cartog ide` flags.\n\n## Commands\n\n```bash\n# Index\ncartog index .                              # build the graph (with LSP if available)\ncartog index . --no-lsp                     # heuristic-only (~1-4s)\ncartog index . --force                      # re-index all files\n\n# Search\ncartog search validate                      # partial name match (sub-ms)\ncartog search validate --kind function      # filter by kind\ncartog rag search \"token validation\"        # semantic search (natural language)\n\n# Navigate\ncartog outline src/auth/tokens.py           # file structure without reading it\ncartog refs validate_token                  # who references this?\ncartog refs validate_token --kind calls     # only call sites\ncartog callees authenticate                 # what does this call?\ncartog impact SessionManager --depth 3      # what breaks if I change this?\ncartog hierarchy BaseService                # inheritance tree\ncartog hierarchy BaseService --mermaid      # paste-into-PR diagram\ncartog deps src/routes/auth.py              # file-level imports\ncartog deps src/routes/auth.py --mermaid    # graph LR with file as root\n\n# Inspect\ncartog stats                                # index summary\ncartog savings                              # tokens saved vs grep+read baseline\ncartog map --tokens 4000                    # codebase overview by centrality\ncartog map --mermaid                        # codebase map as graph TD\ncartog changes --commits 5                  # recently changed symbols\ncartog doctor                               # environment health check\n\n# Watch \u0026 Serve\ncartog watch .                              # auto re-index on save\ncartog serve --watch --rag                  # MCP server with live index\n```\n\nAll commands support `--json` for structured output and `--tokens N` for budget-aware output.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eExample outputs\u003c/strong\u003e\u003c/summary\u003e\n\n### outline\n\n```\n$ cartog outline auth/tokens.py\nfrom datetime import datetime, timedelta  L3\nfrom typing import Optional  L4\nimport hashlib  L5\nclass TokenError  L11-14\nclass ExpiredTokenError  L17-20\nfunction generate_token(user: User, expires_in: int = 3600) -\u003e str  L23-27\nfunction validate_token(token: str) -\u003e Optional[User]  L30-44\nfunction lookup_session(token: str) -\u003e Optional[Session]  L47-49\nfunction refresh_token(old_token: str) -\u003e str  L52-56\nfunction revoke_token(token: str) -\u003e bool  L59-65\n```\n\n### search\n\n```\n$ cartog search validate\nfunction  validate_token    auth/tokens.py:30\nfunction  validate_session  auth/tokens.py:68\nfunction  validate_user     services/user.py:12\n```\n\n### impact\n\n```\n$ cartog impact validate_token --depth 3\n  calls  get_current_user  auth/service.py:40\n  calls  refresh_token  auth/tokens.py:54\n    calls  impersonate  auth/service.py:52\n```\n\n### refs\n\n```\n$ cartog refs UserService\nimports  ./service  routes/auth.py:3\ncalls    login  routes/auth.py:15\ninherits AdminService  auth/service.py:47\nreferences  process  routes/auth.py:22\n```\n\n\u003c/details\u003e\n\n## Supported Languages\n\n| Language | Extensions | Symbols | Edges |\n|----------|-----------|---------|-------|\n| Python | .py, .pyi | functions, classes, methods, imports, variables | calls, imports, inherits, raises, type refs |\n| TypeScript | .ts, .tsx | functions, classes, methods, imports, variables | calls, imports, inherits, type refs, new |\n| JavaScript | .js, .jsx, .mjs, .cjs | functions, classes, methods, imports, variables | calls, imports, inherits, new |\n| Rust | .rs | functions, structs, traits, impls, imports | calls, imports, inherits (trait impl), type refs |\n| Go | .go | functions, structs, interfaces, imports | calls, imports, type refs |\n| Ruby | .rb | functions, classes, modules, imports | calls, imports, inherits, raises, rescue types |\n| Java | .java | classes, interfaces, enums, methods, imports | calls, imports, inherits, raises, type refs, new |\n| PHP | .php | classes, interfaces, traits, methods, functions | calls, inherits, implements, references (traits, new) |\n| Dart | .dart | classes, mixins, extensions, enums, methods, functions, typedefs | calls, imports, inherits, implements, type refs |\n| Swift | .swift | classes, structs, actors, protocols, enums, extensions, methods, functions, typealiases | calls, imports, inherits, implements, type refs |\n| Kotlin | .kt, .kts | classes, data/sealed classes, interfaces, enums, objects, methods, functions, typealiases | calls, imports, inherits, implements, type refs |\n| Markdown | .md | document sections (chunked by heading) | — |\n\n## How It Works\n\n```mermaid\ngraph LR\n    A[\"Source files\u003cbr/\u003e(py, ts, rs, go, rb, java, php, dart, md)\"] --\u003e|parse| B[\"Symbols + Edges\"]\n    B --\u003e|write| C[\".cartog/db.sqlite\u003cbr/\u003e(SQLite)\"]\n    C --\u003e|query| D[\"search / refs / impact\u003cbr/\u003eoutline / callees / hierarchy\"]\n    C --\u003e|embed locally| E[\"ONNX embeddings\u003cbr/\u003e(sqlite-vec)\"]\n    E --\u003e|query| F[\"rag search\u003cbr/\u003e(FTS5 + vector KNN + reranker)\"]\n```\n\n1. **Index** — tree-sitter parses your code, extracts symbols (functions, classes, methods) and edges (calls, imports, inherits, type refs). Markdown is chunked by heading.\n2. **Store** — everything goes into a local `.cartog/db.sqlite` SQLite file.\n3. **Resolve (heuristic)** — links edges by name with scope-aware matching.\n4. **Resolve (LSP, optional)** — sends unresolved edges to language servers for compiler-grade precision. Results persist.\n5. **Embed (optional)** — generates vector embeddings via local ONNX or Ollama, stored in sqlite-vec.\n6. **Query** — instant lookups against the pre-computed graph. Hybrid FTS5 + vector search with RRF merge and cross-encoder re-ranking.\n\nRe-indexing is incremental: git diff + SHA-256 skips unchanged files, Merkle-tree diffing updates only modified symbols. `cartog watch` automates this on file save.\n\n## Performance\n\nIndexing: **69 files / 4k LOC in 95ms** (incremental re-index skips unchanged files).\n\n| Query | Latency |\n|-------|---------|\n| outline | 8-14 us |\n| hierarchy | 8-9 us |\n| deps | 25 us |\n| stats | 32 us |\n| search | 81-102 us |\n| callees | 177-180 us |\n| refs | 258-471 us |\n| impact (depth 3) | 2.7-17 ms |\n\n### Edge Resolution\n\n| Project | Language | Heuristic | With LSP | LSP time |\n|---------|----------|-----------|----------|----------|\n| TS microservice (230 files) | TypeScript | 37% | **81%** | 13s |\n| Vue.js SPA (739 files) | Vue/TS/JS | 31% | **72%** | 25s |\n| Rust CLI (358 files) | Rust | 25% | **44%** | 72s |\n| PHP webapp fixture (25 files) | PHP | 82% | **84%** | 22s |\n\nUnresolved edges are mostly calls to external libraries outside the project boundary. The PHP row uses the self-contained `webapp_php` benchmark fixture (no `composer install`), so LSP gains are modest; real PHP projects with `vendor/` populated typically see larger lifts from `intelephense`.\n\n## Configuration\n\nDatabase path is resolved automatically — no config needed for standard use:\n\n1. `--db` flag / `CARTOG_DB` env var (highest priority)\n2. `.cartog.toml` at git root\n3. Auto git-root detection (`.cartog/db.sqlite`; legacy `.cartog.db` still read with a warning)\n4. `.cartog/db.sqlite` in current directory\n\n**`.cartog.toml`** (optional):\n\n```toml\n[database]\npath = \"~/.local/share/cartog/myproject.db\"\n\n[embedding]\nprovider = \"ollama\"          # \"local\" (default), \"ollama\", or \"openai\"\nmodel = \"nomic-embed-text\"\n# auto_embed = true          # watcher auto-embed; unset = auto-detect (embed if the\n                             # repo already has embeddings). CARTOG_WATCH_RAG \u003e this \u003e --rag\n\n[embedding.ollama]\nbase_url = \"http://localhost:11434\"\n\n# Or an OpenAI-compatible /v1 endpoint (OpenAI, Mistral, Voyage, Jina, OVHcloud,\n# or a local server like Ollama /v1, LM Studio, vLLM):\n# [embedding]\n# provider = \"openai\"\n# model    = \"text-embedding-3-small\"\n# [embedding.openai]\n# base_url    = \"https://api.openai.com/v1\"  # swap base_url to change vendor\n# api_key_env = \"OPENAI_API_KEY\"             # env var NAME; never the key itself\n\n[reranker]\nprovider = \"none\"            # \"local\" (default) or \"none\"\n# model  = \"BAAI/bge-reranker-base\"   # default: jinaai/jina-reranker-v1-turbo-en (~150MB)\n```\n\n## Privacy\n\n- **Parsing**: tree-sitter runs in-process\n- **Storage**: SQLite file in your project directory\n- **Embeddings**: local ONNX, Ollama on localhost, or an OpenAI-compatible endpoint you configure (API key from env, never from config)\n- **Re-ranking**: cross-encoder runs locally via ONNX\n- **MCP server**: stdio only, no network sockets\n- **No telemetry**, no analytics, no phone-home\n\nYour code never leaves your machine — unless you explicitly opt in to\n[S3-compatible index sync](docs/usage.md#cartog-push---remote-s3-url)\n(`cartog push` / `cartog pull`), which is inert until you configure a remote.\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---|---|\n| **\"not initialized\" / no results** | Run `cartog init` then `cartog index .` in the repo first. |\n| **`cartog index` seems to hang** | Cold index of a large repo takes a few seconds; re-run with `RUST_LOG=info cartog index .` if nothing after 60s. |\n| **MCP \"Connection closed\" on a 2nd editor window** | Expected: single-writer election makes the 2nd instance read-only (14 of 16 tools). Ensure `cartog --version` ≥ 0.17 and `CARTOG_SINGLE_WRITER` is unset. |\n| **`.cartog.toml` ignored** | Cartog walks up to the git root; with no `.git`, put it in the cwd or pass `--db`. `cartog config` prints the resolved paths. |\n| **Missing symbols / recall lower than expected** | Wait for the watcher (or run `cartog index`), check the file's language is supported and not `.gitignore`d. Install a language server on PATH to lift edge resolution from ~25% to up to ~81%. |\n| **Anything else** | `cartog doctor` checks git, config, DB, and models. |\n\nFull list with detailed fixes: **[docs/troubleshooting.md](docs/troubleshooting.md)**.\n\n## Documentation\n\nFull index: [docs/README.md](docs/README.md). Highlights:\n\n- **[Documentation site](https://jrollin.github.io/cartog/)** — quick start, CLI reference, configuration, MCP setup\n- [Usage](docs/usage.md) — full CLI reference and integration guides\n- [Editor integration](docs/editor-integration.md) — Neovim, VS Code, Emacs recipes\n- [Troubleshooting](docs/troubleshooting.md) — common issues and fixes\n- [Product Overview](docs/product.md) — vision, target users, benchmark caveats\n- [Technology Stack](docs/tech.md) — architecture and RAG design\n- [Project Structure](docs/structure.md) — workspace layout\n\n## Contributors\n\nThanks to everyone who has contributed to cartog.\n\n[![Contributors](https://contrib.rocks/image?repo=jrollin/cartog)](https://github.com/jrollin/cartog/graphs/contributors)\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup, commit style, and how to add a new language extractor.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrollin%2Fcartog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjrollin%2Fcartog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrollin%2Fcartog/lists"}