{"id":51355352,"url":"https://github.com/simplecore-inc/coregraph","last_synced_at":"2026-07-02T19:10:50.573Z","repository":{"id":363282615,"uuid":"1261964229","full_name":"simplecore-inc/coregraph","owner":"simplecore-inc","description":"A queryable code symbol graph for multi-language monorepos — find callers, impact, dead code, and cross-file inconsistencies, every edge confidence-scored.","archived":false,"fork":false,"pushed_at":"2026-06-15T23:38:10.000Z","size":4067,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T00:21:20.098Z","etag":null,"topics":["ai-agents","cli","code-analysis","code-graph","code-intelligence","codegraph","dead-code-detection","impact-analysis","llm","lsp","mcp","monorepo","multi-language","rust","stack-graph","stack-graphs","stackgraph","static-analysis","symbol-graph","tree-sitter"],"latest_commit_sha":null,"homepage":"","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/simplecore-inc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing/development.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-07T11:50:11.000Z","updated_at":"2026-06-15T23:17:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/simplecore-inc/coregraph","commit_stats":null,"previous_names":["simplecore-inc/coregraph"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/simplecore-inc/coregraph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecore-inc%2Fcoregraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecore-inc%2Fcoregraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecore-inc%2Fcoregraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecore-inc%2Fcoregraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simplecore-inc","download_url":"https://codeload.github.com/simplecore-inc/coregraph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplecore-inc%2Fcoregraph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35059455,"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-07-02T02:00:06.368Z","response_time":173,"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":["ai-agents","cli","code-analysis","code-graph","code-intelligence","codegraph","dead-code-detection","impact-analysis","llm","lsp","mcp","monorepo","multi-language","rust","stack-graph","stack-graphs","stackgraph","static-analysis","symbol-graph","tree-sitter"],"created_at":"2026-07-02T19:10:49.653Z","updated_at":"2026-07-02T19:10:50.551Z","avatar_url":"https://github.com/simplecore-inc.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.svg\" alt=\"CoreGraph\" width=\"120\" height=\"120\"\u003e\n\u003c/p\u003e\n\n# CoreGraph\n\n[![npm version](https://img.shields.io/npm/v/@coregraph/cli?logo=npm\u0026color=cb3837)](https://www.npmjs.com/package/@coregraph/cli) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) ![macOS arm64 | x64](https://img.shields.io/badge/macOS-arm64%20%7C%20x64-334155?logo=apple\u0026logoColor=white) ![Linux x64 | arm64](https://img.shields.io/badge/Linux-x64%20%7C%20arm64-FCC624?logo=linux\u0026logoColor=black) ![Windows x64 | arm64](https://img.shields.io/badge/Windows-x64%20%7C%20arm64-0078D6?logo=windows\u0026logoColor=white)\n\nOne queryable code graph for multi-language and monorepo codebases — find callers, impact, dead code, and cross-file inconsistencies, with every relationship tagged by how much you can trust it.\n\nCoreGraph is a Rust CLI (`coregraph`, v0.1.3, MIT). It indexes your source once,\nserves the graph from a background daemon, and answers questions over an IPC\nsocket, an MCP bridge for LLM agents, an LSP bridge for editors, and an optional\nHTTP API. Because every answer comes from the precomputed graph instead of\nre-reading files, results are precise, fast to return, and small enough to hand\nstraight to an LLM — a few hundred tokens where grepping and pasting files would\ncost thousands.\n\n---\n\n## What is CoreGraph\n\nCoreGraph builds an in-memory **symbol graph** of your codebase by combining two\nanalysis layers into a single result:\n\n- **tree-sitter** extracts symbols — functions, methods, structs, classes,\n  enums, config keys, doc comments — from each file.\n- **stack-graphs** resolves names *across files* — so a call site in one file\n  links to the definition it actually binds to in another, not just to anything\n  with the same name.\n\nBoth run inside one `coregraph index` pass — no language servers, build system,\nor compiler toolchain required.\n\nEvery edge in the graph carries a **confidence score** (0.0–1.0), the **origin**\nthat produced it (e.g. resolved by stack-graphs vs. matched syntactically), and a\n**trust model**. That means a consumer — an LLM agent or a human — can tell a\ncompiler-grade fact from a heuristic guess, and filter by `--min-confidence`\nwhen it matters.\n\n---\n\n## Highlights\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/highlights.svg\" alt=\"CoreGraph highlights — Token-efficient: built for LLM agents, exact symbols and edges instead of whole files, llm output paged to a token budget. Fast: one index pass (~280 files in ~2.3s), in-memory daemon over IPC, warm-load from snapshot. Many languages: Java, TypeScript, JavaScript, Python, Go, Rust, Kotlin plus config and Markdown in one index. Monorepo-native: cross-package and cross-language in one connected graph.\" width=\"860\"\u003e\n\u003c/p\u003e\n\n- **Token-efficient — built for LLM agents.** Every answer comes from the\n  precomputed graph, so CoreGraph returns the *exact* symbols and edges a question\n  touches instead of whole files. `--output-format llm` emits compact, structured\n  text; results are paged against a `--token-budget` (default `8000`; `--fast`\n  caps it at `2000`, `--full` raises it to `16000`) with a live `budget: used/total`\n  counter; and `--min-confidence` filters low-trust noise before it ever reaches\n  the model. A caller lookup that would otherwise mean pasting several files lands\n  in a few hundred tokens.\n- **Fast, and stays fast.** A single `index` pass builds the whole graph (~280\n  files in ~2.3s on this repo), then a background daemon serves every later query\n  from memory over an IPC socket — no re-indexing per command. Idle projects are\n  snapshotted to disk and **warm-load** on the next query (skipping tree-sitter\n  extraction) unless a source file changed, so repeat queries are effectively\n  instant and never stale.\n- **Many languages, one graph.** Java, TypeScript, JavaScript, Python, Go, Rust,\n  and Kotlin each get both symbol extraction *and* cross-file name resolution,\n  alongside config (YAML/TOML/JSON) and Markdown layers — all unified into one\n  index you query identically regardless of language.\n- **Monorepo-native.** One graph spans every package, service, and language in\n  the repo at once: a reference that crosses a directory or language boundary\n  resolves to its real definition, so cross-package call paths and shared\n  definitions are reachable in a single query rather than scattered across\n  per-language indexes. The daemon caches multiple projects under an LRU with an\n  optional heap budget, keeping a large polyglot repo responsive.\n\n---\n\n## Why CoreGraph\n\n| Tool | What it gives you | What it misses |\n|------|-------------------|----------------|\n| `grep` / ripgrep | Fast text matches | No symbols, no call edges, no cross-file resolution |\n| `ctags` | A symbol index | No callers/callees, no impact, single-pass only |\n| Single-language LSP | Rich nav in one language | One language at a time; nothing across a polyglot monorepo |\n| **CoreGraph** | A typed, cross-file, multi-language graph with confidence-tagged edges | — |\n\nCoreGraph is built for codebases where the answer spans files and languages:\na TypeScript route that maps to a Go handler, a Spring bean wired by config, an\nenum value duplicated across services. It answers \"who calls this\", \"what breaks\nif I change this\", \"what is dead\", and \"where do these disagree\" — across all of\nit at once.\n\n---\n\n## Quick start\n\n```bash\n# Install the CLI from npm — puts `coregraph` on your PATH\nnpm install -g @coregraph/cli\n# ...upgrade later to the latest:   npm install -g @coregraph/cli@latest\n# ...or run it without installing:  npx @coregraph/cli@latest \u003ccommand\u003e\n# ...or build from source:          cargo build --release  (binary in target/release/)\n# Check the installed version:      coregraph --version\n\n# Index the current project (creates .coregraph/config.toml on first run)\ncoregraph index --stats\n```\n\n\u003e **Updating:** re-run `npm install -g @coregraph/cli@latest` to move to the newest\n\u003e release; `coregraph --version` confirms the result and the [npm version badge](https://www.npmjs.com/package/@coregraph/cli)\n\u003e shows the latest published version. A background daemon already running from an\n\u003e older version keeps serving until restarted — run `coregraph server restart` to\n\u003e load the new binary.\n\n```\ncoregraph: skipped 1 minified/generated file(s) (e.g. ./vscode-extension/media/cytoscape.min.js)\nIndex complete — 281 files, 3396 symbols, 21342 edges (2337ms)\n```\n\nThe first query auto-spawns a background daemon and reuses the cached graph for\nevery subsequent command.\n\n### Find who calls a function\n\n```bash\ncoregraph query compute_impact \\\n  --direction incoming --edge-kind calls --hop-limit 1\n```\n\n```\n── query: compute_impact ──────────────────────────────────\n\n✓ compute_impact [crates/query/src/impact.rs:27]\n  kind: Function | package: query (cargo)\n\n  Incoming (14):\n  ├── calls ← run [Function] @ crates/cli/src/commands/diff.rs      [0.85] ✓\n  ├── calls ← run [Function] @ crates/cli/src/commands/impact.rs      [0.85] ✓\n  ├── calls ← cached_impact [Function] @ crates/cli/src/dispatch.rs      [0.85] ✓\n  ├── calls ← api_impact [Function] @ crates/server/src/handlers.rs      [0.85] ✓\n  └── ... (14 total)\n  ✓ trust: all paths verified\n\n── page 1/1 | 14 edges total | budget: 506/5600 tokens ──\n   [n]ext page | [e]xpand \u003cid\u003e | [f]ilter --edge-kind | [q]uit\n```\n\nThe `[0.85] ✓` on each edge is its confidence score.\n\n### See the blast radius of a change\n\n```bash\ncoregraph impact build_router --risk\n```\n\n```\nImpact of 'build_router': 1251 reachable symbols, 1251 edges, depth 3\n  Risk Score: 0.96 (Critical)\n  Blast Radius: Critical (16 modules, 910 callers)\n  Confidence-Weighted Impact: 653.500\n  Affected tests: 334\n    test_app (distance 2, path_confidence 0.90) — ./crates/server/src/handlers.rs\n    create_app_returns_router (distance 2, path_confidence 0.90) — ./crates/server/src/lib.rs\n    ... (more affected tests)\n```\n\n### Find dead-code candidates\n\n```bash\ncoregraph orphans --exclude-tests\n```\n\n```\nOrphan symbols (12): 7 likely dead, 5 library API surface, 0 test code\n  as_kebab [Method] — crates/cli/src/commands/query.rs\n  strip_api_path_prefix [Function] — crates/extractor/src/string_literal_extractor.rs [library API]\n  unregister [Method] — crates/graph/src/hooks.rs [library API]\n  outputChannel [Constant] — vscode-extension/src/extension.ts\n  ...\n```\n\nSymbols tagged `[library API]` are public surface — reachable from outside the\ncrate, so flagged with lower confidence than truly unreferenced symbols.\n\n### Detect cross-file inconsistencies\n\n```bash\ncoregraph inconsistencies\n```\n\n```\nInconsistencies (63):\n  [enum-mismatch] 'admin' appears in:\n    - Permission.ADMIN (./tests/e2e/golden/04-inconsistencies/src/permissions.ts)\n    - Role.ADMIN (./tests/e2e/golden/04-inconsistencies/src/roles.ts)\n  [api-path] /a.rs vs /b.rs\n    ...\n```\n\nNarrow the report with `--category \u003cenum-mismatch|api-path|config-key|doc-drift\u003e`.\nDetectors are tunable per project via the `[inconsistencies]` config section:\n`disable = [\"api-path\"]` turns a category off in run-everything mode (useful in\na frontend-only repo where route literals have no server counterpart — an\nexplicit `--category` still runs it), and `api_path_min_segments` (default `2`)\nfloors the near-miss segment count.\n\n### Get oriented in an unfamiliar codebase\n\n```bash\ncoregraph stats --breakdown\n```\n\n```\nsymbols: 4136\nedges:   24993\n\n## Symbol kinds\n  Function         1480\n  DocComment        709\n  Method            473\n  ...\n\n## Per-package symbol/edge counts\n  package                           symbols    edges\n  (no package)                         1391     8058\n  coregraph                             736     5634\n  coregraph-extractor                   510     3902\n  ...\n\n## Top 20 most-referenced symbols (in-degree; containers excluded)\n    250  SymbolId    [Struct] @ ./crates/core/src/symbol.rs\n    149  clone       [Method] @ ./crates/graph/src/bloom.rs\n    122  nodes       [Method] @ ./crates/graph/src/symbol_graph.rs\n    ...\n\n## Top 20 files by symbol count\n    133  ./crates/cli/src/dispatch.rs\n    116  ./crates/extractor/src/lib.rs\n    110  ./crates/graph/src/symbol_graph.rs\n    ...\n```\n\nPackages come from the project's own manifests (Cargo workspaces, npm/pnpm\nworkspaces, Maven/Gradle modules); the in-degree ranking counts only\nimpact-bearing edges between real symbols, so file containers and doc nodes\ndon't drown the actual hubs.\n\nStart here on a repo you don't know — the most-referenced symbols and densest\nfiles are where the architecture actually lives.\n\n### Look up a symbol by `file:line`\n\n```bash\ncoregraph inspect crates/query/src/impact.rs:33\n```\n\n```\n── inspect: crates/query/src/impact.rs:33 ──\n  compute_impact [Function] bytes 1128..3581\n  doc::compute_impact [DocComment] bytes 531..1128\n\n      32 /// depends on (outgoing) does not break when X changes.\n  →   33 pub fn compute_impact(graph: \u0026SymbolGraph, seed_id: SymbolId, max_depth: usize) -\u003e ImpactResult {\n      34     let mut visited: HashSet\u003cSymbolId\u003e = HashSet::new();\n```\n\nResolves whatever symbol sits at a cursor position — its name, kind, byte range,\nand surrounding source (default 5 lines, `--context-lines`). A `doc::…\n[DocComment]` line appears only when the queried position lands inside a doc\ncomment's own span (as in the example above); inspecting a line in a symbol's\nbody does not pull in that symbol's doc comment, and the JSON output and the\neditor/IPC `inspect` path carry no doc-comment data.\n\n### See what a function depends on\n\n```bash\ncoregraph query compute_impact \\\n  --direction outgoing --edge-kind calls --hop-limit 1\n```\n\n```\n── query: compute_impact ──────────────────────────────────\n\n✓ compute_impact [crates/query/src/impact.rs:27]\n  kind: Function | package: query (cargo)\n\n  Outgoing (3):\n  ├── calls → incident_edges [Method] @ crates/graph/src/symbol_graph.rs    [0.85] ✓\n  ├── calls → is_impact_bearing [Function] @ crates/query/src/impact.rs     [0.85] ✓\n  └── calls → clone [Method] @ crates/graph/src/bloom.rs                     [0.85] ✓\n  ✓ trust: all paths verified\n```\n\nSame query as \"who calls a function\", flipped: `--direction outgoing` walks to\ncallees/dependencies, `incoming` walks to callers.\n\n### Pipe results into scripts or your AI assistant\n\n```bash\ncoregraph query build_router --direction outgoing --edge-kind calls \\\n  --output-format json | jq -r '.edges[] | \"\\(.other_name)  [\\(.current_confidence)]\"'\n```\n\n```\nnew        [0.95]\nroute      [0.95]\npost       [0.95]\nclone      [0.95]\ndispatch   [0.95]\n... (22 total)\n```\n\nEvery analysis command (`query`, `impact`, `diff`, `orphans`,\n`inconsistencies`, `stats`, `inspect`, `index`) takes `--output-format json`, so\nresults drop straight into scripts and CI gates (`llm` is honored by the\ncommands that route through the LLM renderer; `stats`/`inspect`/`index` fall\nback to human text for it). For live editor/agent use, run `coregraph lsp` or\n`coregraph mcp` — see [Integrations](#integrations).\n\n---\n\n## Key features\n\n- **Token-budgeted, LLM-ready output.** `--output-format llm` emits compact\n  structured text, every result is paged against `--token-budget`, and\n  `--min-confidence` drops low-trust noise — so an agent spends a few hundred\n  tokens per answer instead of ingesting whole files.\n- **Multi-language, one graph.** Seven code languages plus config and Markdown,\n  unified into a single index — built for monorepos.\n- **Cross-file name resolution.** stack-graphs binds references to the\n  definitions they actually resolve to, across files.\n- **Confidence and trust on every edge.** Each relationship is scored and\n  origin-tagged; filter with `--min-confidence` (default `0.70`).\n- **Impact and risk analysis.** Transitive reachability plus a risk score,\n  blast radius, and the tests a change affects.\n- **Dead-code detection.** Orphan symbols, separating likely-dead from public\n  library surface.\n- **Cross-file inconsistency checks.** Enum-value mismatches, API path drift,\n  config-key drift, and doc-drift (`@param`/`:param` naming a parameter the\n  signature no longer has — with rename candidates suggested from the actual\n  signature). Categories are tunable per project via `[inconsistencies]` in\n  `config.toml`.\n- **Config self-tuning.** `coregraph config recommend` measures the indexed\n  graph and suggests `config.toml` tuning (exclude lists, string-match cap,\n  category disabling); `--write` applies it without clobbering comments.\n- **Background daemon.** Auto-spawns on first use, caches the graph, and\n  self-terminates when idle — fast repeat queries, no resident cost when unused.\n- **Built-in integrations.** MCP for LLM agents, LSP for editors, and an\n  optional HTTP API.\n- **3D visualization.** `coregraph viz` opens an interactive in-browser atlas\n  of the whole graph, fed live from the daemon.\n\n---\n\n## Visualize: coregraph atlas\n\n```bash\ncoregraph viz            # serves http://127.0.0.1:7321 and opens the browser\ncoregraph viz --detach   # same, in the background; logs to viz.log\ncoregraph viz --stop     # stop the detached server\n```\n\n`coregraph viz` starts a local server (127.0.0.1 only, token-guarded) with a\n3D force-directed view of the symbol graph, served straight from daemon\nmemory — no export step. If the daemon isn't running it is started for you,\nand a project picker lists everything already loaded. `--detach` runs the\nserver outside the terminal session (it survives the terminal closing) and\nreturns once the port answers; `--stop` terminates the instance recorded by\nthe last `--detach`.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/atlas-clusters.png\" alt=\"coregraph atlas — the symbol graph clustered by unit: each module/package/crate gathers inside a translucent labeled sphere, with cross-unit edges faded\" width=\"860\"\u003e\n\u003c/p\u003e\n\nWhat you can do in the viewer:\n\n- **Explore** — fuzzy symbol search, isolate a neighborhood (depth 1–3),\n  inspect any symbol with its incident edges and a source preview.\n- **Cluster by unit** — group nodes by module/package/crate (derived from the\n  path structure) inside translucent boundary spheres, as shown above.\n- **Run analyses on the graph** — impact paints the blast radius as a\n  hop-distance gradient with the risk score and affected tests; dead code,\n  cross-file inconsistencies, git-diff impact, and shortest path between two\n  symbols are one click away.\n- **Filter** — symbol/edge kinds, analysis origin, minimum confidence,\n  min-degree and hub trimming, color by kind / directory / unit.\n- **Share \u0026 export** — copy a link that restores the exact view, download a\n  PNG capture or the visible subgraph as json-graph.\n- **Stay fresh** — the viewer polls the daemon and offers a one-click reload\n  when the graph changes on disk; it never resets your camera behind your back.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/atlas-explore.png\" alt=\"coregraph atlas — exploring one symbol: its isolated neighborhood fills the canvas with labeled neighbors while the side panel shows the symbol's kind, file, source preview, and incident edges\" width=\"860\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/atlas-impact.png\" alt=\"coregraph atlas — impact analysis of one symbol: its transitive dependents glow against the dimmed graph while the side panel shows reachable/caller counts, a risk bar, and the affected tests\" width=\"860\"\u003e\n\u003c/p\u003e\n\n---\n\n## How it works\n\n```\nsource files\n     │\n     ▼\n tree-sitter ──► symbols (functions, structs, config keys, doc comments, …)\n     │\n     ▼\n stack-graphs ─► cross-file name resolution (calls, imports, references)\n     │\n     ▼\n symbol graph (in memory) ──► confidence/trust-tagged edges\n     │\n     ▼\n background daemon ──► IPC socket │ MCP │ LSP │ HTTP\n```\n\n`coregraph index` runs both analysis layers in one pass. The resulting graph is\nheld by a background daemon that:\n\n- **Auto-starts** on the first thin-client command (`query`, `stats`, `impact`,\n  `orphans`, `inconsistencies`, `lsp`, `mcp`). Use `--no-auto-start` (or\n  `COREGRAPH_NO_AUTO_START=1`) to build in-process instead.\n- **Self-terminates** after `server start --auto-stop-minutes \u003cN\u003e` (default 30)\n  of full idleness; `0` disables.\n- **Caches multiple projects** under an LRU (`server.max_loaded_projects`,\n  default 5), with an optional total-heap byte budget\n  (`server.max_loaded_bytes`, `0` = unlimited).\n- **Optionally serves HTTP** via `coregraph server start --http`.\n\n### In-memory graph management\n\nThe daemon keeps each project's graph in memory only as long as it is useful,\nso an idle workstation reclaims the memory automatically:\n\n- **Idle unload (persist-then-free).** A project idle for\n  `server.idle_unload_minutes` (default 10) is dropped from memory. Before it is\n  freed — and likewise when LRU or the byte budget evicts it — a graph that\n  changed since its last save is written to `.coregraph/snapshot.bin`. The write\n  happens off the cache lock, so it never blocks concurrent queries, and a clean\n  (unmodified) graph is skipped to avoid redundant disk churn.\n- **Warm restart.** The next query for an unloaded project **warm-loads** the\n  snapshot from disk instead of re-running tree-sitter extraction — *unless* any\n  source file is newer than the snapshot's recorded build time, in which case it\n  rebuilds from source. So a warm load is fast but never serves stale data.\n- **Tombstone GC.** Deleted symbols are tombstoned, then reaped from every\n  loaded graph by a background sweeper once they age past a 5-minute grace\n  window, reclaiming their nodes, edges, and index entries.\n- **Compact storage.** File paths are interned (`Arc\u003cPath\u003e`), so every symbol in\n  the same file shares one path allocation in memory instead of holding a private\n  copy. The snapshot itself stores the path per node/edge, so sharing is\n  re-established when a snapshot is loaded back into memory.\n\nEach project's graph moves through a simple lifecycle — loaded on demand,\nserved from memory, and unloaded (after persisting) once idle:\n\n```mermaid\ngraph LR\n  U[Unloaded] --\u003e|first query| A[Active]\n  A --\u003e|cache hit| A\n  A --\u003e|idle / evict| U\n  A --\u003e|all idle| S([Daemon stops])\n```\n\nWhere _first query_ warm-loads the snapshot (or rebuilds), _idle / evict_\npersists a changed graph before freeing it, and _all idle_ auto-stops the\ndaemon — as detailed above.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDetailed flows\u003c/b\u003e — load path, eviction, and the sweeper\u003c/summary\u003e\n\n**Load path** — what a single query resolves to:\n\n```mermaid\ngraph TD\n  Q[Query] --\u003e C{In cache?}\n  C --\u003e|hit| H[Serve from memory]\n  C --\u003e|quiescing| R[Revive]\n  C --\u003e|stale: source newer| E[Evict stale]\n  C --\u003e|miss| B{Snapshot fresh?}\n  R --\u003e H\n  E --\u003e B\n  B --\u003e|yes| W[Warm-load: skip extraction]\n  B --\u003e|no/missing| F[Rebuild: tree-sitter + stack-graphs]\n  W --\u003e H\n  F --\u003e H\n```\n\n\n**Eviction (persist-then-free)** — how a graph leaves memory without losing\nchanges or blocking concurrent queries:\n\n```mermaid\ngraph TD\n  T[Trigger: idle / LRU / byte budget] --\u003e M[Mark victims under lock]\n  M --\u003e P{Changed since save?}\n  P --\u003e|yes| W[Persist snapshot off-lock, atomic]\n  P --\u003e|no| K[Skip write]\n  W --\u003e RC{Still idle?}\n  K --\u003e RC\n  RC --\u003e|yes| D[Drop from cache, memory freed]\n  RC --\u003e|query arrived| RV[Revive, keep Active]\n```\n\n\n**Background sweeper** — one tick every 60s does three things:\n\n```mermaid\ngraph LR\n  S[Sweeper tick every 60s] --\u003e A[sweep_idle: unload idle projects]\n  S --\u003e G[gc_loaded: reap Gone nodes past 5min]\n  S --\u003e C{All idle past auto_stop?}\n  C --\u003e|yes| X[persist all dirty, then exit]\n  C --\u003e|no| N[wait next tick]\n```\n\n\n\u003c/details\u003e\n\nSnapshots are bincode binary blobs (schema v6, carrying the graph's build time).\nSave and reload the graph manually with `coregraph snapshot save --out \u003cPATH\u003e` /\n`coregraph snapshot load \u003cPATH\u003e`, or attach one to indexing with\n`index --snapshot \u003cPATH\u003e`.\n\n### Confidence and trust\n\nStored edge confidence is `base(edge_kind) × base(origin)`, clamped to `[0,1]`\n(computed once at edge creation). The live `current_confidence` shown in query\noutput is `base(origin)` decayed by ×0.7 per stale evidence item — the stale\ndecay applies to the origin base alone, not to the stored product. The five\nanalysis origins, highest to lowest base confidence:\n\n| Origin | Base | Meaning |\n|--------|------|---------|\n| CompilerDerived | 0.99 | Compiler-grade fact |\n| NameResolved | 0.95 | Resolved by stack-graphs |\n| SyntaxMatched | 0.85 | Matched syntactically (tree-sitter) |\n| PatternMatched | 0.60 | Matched by a known framework pattern |\n| ConventionInferred | 0.40 | Inferred from a naming/structure convention |\n\nEdges also carry one of four trust models — `SourceEvidenced`,\n`ContractDependent`, `Bidirectional`, `ExternallyMediated`. See\n[`docs/confidence.md`](docs/confidence.md) and\n[`docs/graph-model.md`](docs/graph-model.md) for the full schema.\n\n---\n\n## Languages\n\nAll seven code languages have **both** symbol extraction and cross-file name\nresolution. Resolution falls back to tree-sitter syntactic matching only for\nfiles in a language with no rules, or when resolution produces no binding.\n\n| Language | Symbol extraction (tree-sitter) | Name resolution (stack-graphs) |\n|----------|:-------------------------------:|:------------------------------:|\n| Java | ✓ | ✓ (upstream) |\n| TypeScript | ✓ | ✓ (upstream) |\n| JavaScript | ✓ | ✓ (upstream) |\n| Python | ✓ | ✓ (upstream) |\n| Go | ✓ | ✓ (hand-authored `.tsg`) |\n| Rust | ✓ | ✓ (hand-authored `.tsg`) |\n| Kotlin | ✓ | ✓ (hand-authored `.tsg`) |\n| YAML / TOML / JSON | ✓ (→ `ConfigKey` nodes) | — |\n| Markdown | ✓ (documentation layer) | — |\n\nCoreGraph's hand-authored rules live in `crates/stack/rules/{go,rust,kotlin}.tsg`.\n\n---\n\n## CLI overview\n\n`coregraph \u003ccommand\u003e` — run `coregraph \u003ccommand\u003e --help` for full flags.\n\n| Command | Purpose |\n|---------|---------|\n| `index` | Index source files and build the symbol graph |\n| `query` | Query symbols (neighbors, callers, callees) |\n| `inspect` | Inspect the symbol at `FILE:LINE` with source context |\n| `stats` | Graph statistics (`--breakdown` for histograms) |\n| `orphans` | List orphan symbols (dead-code candidates) |\n| `impact` | Impact analysis for a symbol (`--risk` adds scoring) |\n| `diff` | Impact of a git diff: which symbols a change reaches |\n| `review` | Auto-comment a GitHub PR with the diff impact summary |\n| `inconsistencies` | Detect enum / api-path / config-key / doc-drift issues |\n| `export` | Export the graph (`dot` \\| `cypher` \\| `json-graph`) |\n| `viz` | Serve the 3D graph viewer (atlas) on `127.0.0.1:7321` (`--detach` / `--stop`) |\n| `snapshot` | `save` / `load` a binary snapshot |\n| `config` | `init` / `show` / `unset` / `path` / `recommend` |\n| `server` | Daemon management: `start` / `stop` / `status` / `restart` / `install` / `uninstall` |\n| `lsp` | LSP stdio bridge |\n| `mcp` | MCP stdio bridge |\n| `watch` | Watch files and rebuild the graph |\n| `batch` | Run multiple queries from a JSON file |\n| `plugin` | Manage plugin hooks: `list` / `run` |\n\nCommon global options apply to every command: `--output-format \u003chuman|llm|json\u003e`,\n`--min-confidence \u003c0.0–1.0\u003e` (default `0.70`), `--hop-limit \u003cN\u003e` (default `3`),\n`--token-budget \u003cN\u003e` (default `8000`), `-C/--project \u003cPATH\u003e`, and the presets\n`--fast` / `--standard` / `--full`.\n\n\u003e Note: `impact` uses `--max-depth \u003cN\u003e` (default 5) for transitive depth. The\n\u003e `--depth \u003cN\u003e` flag belongs to `query`.\n\nSee [`docs/cli.md`](docs/cli.md) for the complete reference.\n\n---\n\n## Use with AI coding agents\n\nCoreGraph ships a ready-made kit so any AI coding agent can use it — and prefer it over a\nraw grep/read sweep for structural questions (callers, change impact, dead code, cross-file\ninconsistencies). Everything lives under [`agents/`](agents/README.md): the Claude Code\nplugin, an `AGENTS.md` you can drop into your own project, and copy-paste MCP config for\nCodex, Gemini CLI, and opencode. All of it points at one source of guidance — the bundled\nskill.\n\n**Claude Code** — install the plugin (registers the skill and the `coregraph mcp` server).\nAdding the marketplace by its `marketplace.json` URL downloads only the small catalog — no\nrepo clone — and the plugin is sparse-fetched (only `agents/coregraph`):\n\n```text\n/plugin marketplace add https://raw.githubusercontent.com/simplecore-inc/coregraph/main/.claude-plugin/marketplace.json\n/plugin install coregraph@coregraph\n```\n\n**Codex / Gemini CLI / opencode** — register `coregraph mcp` and use the `AGENTS.md`. See\n[`agents/README.md`](agents/README.md) for the exact per-agent setup.\n\n## Integrations\n\nCoreGraph speaks three machine protocols in addition to the terminal. Details in\n[`docs/integrations.md`](docs/integrations.md).\n\n### MCP — `coregraph mcp`\n\nA stdio JSON-RPC bridge for LLM agents, exposing six tools (plain names, no\nprefix):\n\n| Tool | Input | Returns |\n|------|-------|---------|\n| `query` | `{name}` | Symbols matching a name across the project |\n| `impact` | `{name, transitive? = false, depth = 5}` | Transitive dependents of a symbol (who breaks if it changes) up to `depth` (default 5); `transitive` only changes the output label, so pass `depth: 1` to get just direct dependents |\n| `orphans` | `{}` | Dead-code candidates: code symbols with no incoming or outgoing edges |\n| `inconsistencies` | `{}` | Cross-file inconsistencies: enum / api-path / config-key (doc-drift is CLI-only) |\n| `stats` | `{}` | Graph summary: symbol count and edge count |\n| `recommend` | `{}` | Recommended `.coregraph/config.toml` tuning derived from the indexed graph: `[index]`/`[analysis]` exclude candidates, a string-match cap, api-path category disabling (suggestion-only — nothing is written) |\n\nRegister it with an MCP client (Claude Code `.mcp.json` or\n`claude_desktop_config.json`):\n\n```json\n{ \"mcpServers\": { \"coregraph\": { \"command\": \"coregraph\", \"args\": [\"mcp\"] } } }\n```\n\n### LSP — `coregraph lsp`\n\nA stdio LSP bridge for editors. Provides three methods:\n\n- `textDocument/definition`\n- `textDocument/references`\n- `workspace/symbol`\n\n\u003e ⚠ **VS Code extension — in development, not yet tested.** A companion VS Code\n\u003e extension that surfaces reach, impact, and confidence in the editor lives under\n\u003e [`vscode-extension/`](vscode-extension/README.md). It is a work in progress,\n\u003e has not been verified end to end, and is not recommended for daily use yet.\n\n### HTTP — `coregraph server start --http`\n\nAn optional REST API bound to `127.0.0.1:27787` by default (use\n`--allow-external` to bind a non-localhost address).\n\n| Method | Route | Purpose |\n|--------|-------|---------|\n| GET | `/health` | Liveness + version + symbol count |\n| POST | `/query` | Look up symbols by name |\n| POST | `/batch` | Run several name queries at once |\n| GET | `/api/query` | Paginated symbol query (`page`/`page_size`); the `budget` param is echoed back as metadata but does not truncate the response |\n| GET | `/api/expand` | Expand a node's incoming/outgoing edges (returns all of them; its `budget` param is likewise echo-only) |\n| GET | `/api/impact` | Transitive impact for a symbol |\n| GET | `/api/source` | Source snippet around `FILE:LINE` |\n\n---\n\n## Configuration\n\nA per-project config file is created at `\u003cproject\u003e/.coregraph/config.toml` on\nfirst index. View the effective config with `coregraph config show`:\n\n```\n  limits.token_budget            = 8000          [project]\n  limits.hop_limit               = 3             [project]\n  limits.min_confidence          = 0.7           [project]\n  server.max_loaded_projects     = 5             [project]\n  server.graceful_shutdown_sec   = 30            [project]\n  server.idle_unload_minutes     = 10            [project]\n  server.max_loaded_bytes        = 0             [project]\n```\n\nAll `server.*` keys are read by the daemon at start (project-local config\noverrides global). Example `config.toml`:\n\n```toml\n[limits]\nhop_limit = 3          # query traversal depth\nmin_confidence = 0.7   # minimum edge confidence to report\ntoken_budget = 8000    # LLM-mode page size\n\n[server]\nmax_loaded_projects = 5      # daemon LRU cache size (project count)\nmax_loaded_bytes = 0         # total heap budget across loaded graphs; 0 = unlimited\nidle_unload_minutes = 10     # unload (and snapshot) a project after this idle time\ngraceful_shutdown_sec = 30   # in-flight grace before hard-exit\n\n[index]\nexclude = []                 # gitignore-syntax patterns to skip during indexing\nstring_match_max_files = 8   # skip cross-file StringMatch pairing for a string\n                             # found in more than N distinct files (convention\n                             # strings would otherwise emit O(k²) edges); 0 = unlimited\n\n[analysis]\nexclude = []   # files still parsed (their edges survive) but hidden from\n               # dead-code (orphans) reports — for generated consumers\n\n[inconsistencies]\ndisable = []                 # categories to skip when running without --category,\n                             # e.g. [\"api-path\"] in a frontend-only repo\napi_path_min_segments = 2    # minimum non-empty path segments for an api-path\n                             # near-miss report\n```\n\nThe config is linted: `coregraph index` warns on stderr (and `config show`\nflags inline) about TOML syntax errors, unknown sections, and unknown keys\ninstead of silently ignoring them, and a malformed `exclude` pattern is\nskipped with a warning rather than disabling the other patterns. After\nindexing, files dominated by data symbols (i18n bundles, generated docs) are\nsuggested as `[index].exclude` candidates in the human output.\n\nYou can also have the tuning measured for you: `coregraph config recommend`\nderives suggested values for `[index].exclude`, `string_match_max_files`,\n`[inconsistencies].disable`, and `[analysis].exclude` from the indexed graph\nand prints them as a paste-ready TOML block with one reason per suggestion.\n`coregraph config recommend --write` merges them into `config.toml` in place —\ncomments and existing entries are preserved, arrays are appended without\nduplicates, and the merge aborts (writing nothing) if the file doesn't parse.\n\nAny limit can be overridden per invocation with `--hop-limit`,\n`--min-confidence`, or `--token-budget`. A global config also lives at the\nplatform config directory (`dirs::config_dir()`) — on Linux this honors\n`$XDG_CONFIG_HOME/coregraph/config.toml`, on macOS it is\n`~/Library/Application Support/coregraph/config.toml` (run `coregraph config\npath` to print the exact location).\n\n\u003e Note: project-local `[limits]` values are shown by `config show` (tagged\n\u003e `[project]`) but are **not** applied at runtime — only `[limits]` from the\n\u003e global config or a `--config` file are merged into the effective limits. Use\n\u003e the per-invocation flags above for project-specific limits. The `[server.*]`\n\u003e keys are read from the project-local config as documented.\n\n---\n\n## Troubleshooting\n\n- **Stale results after editing files.** Re-run `coregraph index` — it always\n  rebuilds the graph from source and never reuses an existing snapshot, so a\n  plain reindex is already a fully fresh build. For continuous updates,\n  `coregraph watch` (incremental by default; `--no-incremental` forces full\n  rebuilds).\n- **Don't want a background daemon.** Pass `--no-auto-start`, or set\n  `COREGRAPH_NO_AUTO_START=1`, to build and answer in-process.\n- **Daemon won't stop / is stale.** `coregraph server stop`, then re-run your\n  command to respawn a fresh daemon. Check `coregraph server status`.\n- **Noisy `inconsistencies` output.** A repo's own test fixtures can produce\n  fixture-only noise. Narrow with `--category \u003cenum-mismatch|api-path|config-key|doc-drift\u003e`,\n  add `exclude` patterns under `[index]` in `config.toml`, or disable a\n  structurally irrelevant category for the project with\n  `[inconsistencies] disable = [\"api-path\"]` (raise `api_path_min_segments`\n  for a milder filter). `coregraph index` also prints exclude-candidate\n  suggestions when a few data files dominate the symbol count.\n- **`orphans` lists public API as dead.** Symbols tagged `[library API]` are\n  public surface; use `--public-only=false` to also include private symbols, or\n  `--exclude-tests` to drop test code.\n- **HTTP API not reachable from another host.** It binds localhost by default;\n  add `--allow-external` (and review [`docs/security.md`](docs/security.md)).\n\n---\n\n## Documentation\n\n- [`docs/overview.md`](docs/overview.md) — Project intent and design philosophy\n- [`docs/architecture.md`](docs/architecture.md) — Crate layout and runtime\n- [`docs/cli.md`](docs/cli.md) — Full CLI reference\n- [`docs/graph-model.md`](docs/graph-model.md) — Node/edge schema and trust tiers\n- [`docs/confidence.md`](docs/confidence.md) — Confidence and trust math\n- [`docs/change-tracking.md`](docs/change-tracking.md) — File watching and incremental updates\n- [`docs/integrations.md`](docs/integrations.md) — MCP / LSP / HTTP details\n- [`docs/security.md`](docs/security.md) — Threat model and binding controls\n- [`docs/contributing/development.md`](docs/contributing/development.md) — Building from source, local install, and the dev workflow\n- [`docs/contributing/testing.md`](docs/contributing/testing.md) — Test strategy, fixtures, and the e2e suites\n- [`docs/roadmap.md`](docs/roadmap.md) — Status and what's planned\n- [`CHANGELOG.md`](CHANGELOG.md) — User-visible changes\n\n---\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplecore-inc%2Fcoregraph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimplecore-inc%2Fcoregraph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplecore-inc%2Fcoregraph/lists"}