cgh MCP server
Commit Nov 14, 2026Provides a shared project memory and code graph for coding agents to enable faster navigation and persistent context across sessions.
Also known as altikva/cgh
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is cgh MCP?
cgh provides a shared project memory and code graph for coding agents to enable faster navigation and persistent context across sessions.
Summary generated from the project's README
About cgh MCP server
cgh acts as a shared project memory and code graph for coding agents like Claude Code, Cursor, Gemini, or IBM Bob. It functions as an MCP server that stores knowledge, decisions, and session digests per repository, allowing agents to maintain context even after a context clear. By indexing files, functions, classes, and imports locally, it enables agents to navigate complex codebases using precise file and line references rather than reading entire files.
Developers use this tool to reduce the number of turns and tokens required for multi-file navigation tasks. The system supports various languages including Python, TypeScript, Java, Go, Rust, and Vue, while also indexing Markdown, Terraform, and various document formats like PDF and Excel. It operates locally using a DuckDB or SQLite backend, ensuring that sensitive information like PII or secrets can be scanned and gated before any data leaves the machine.
What you can do with it
- 1Navigate complex code structuresAn agent can find the exact definition and callers of a specific function without reading every file in the repository.
- 2Maintain session continuityA developer can resume a coding task with an agent that already understands the recent plans and project decisions.
- 3Automate boilerplate generationUse the codegen plugin to create predictable code like tests or stubs by mirroring existing patterns without bloating the primary model context.
- 4Search through project documentationAn AI client can quickly locate specific information hidden within Markdown files or Office documents.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablealtikva/cgh is public and reachablegithub.com/altikva/cgh ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/altikva/cgh ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcgh, the context graph hub: the project memory of your coding agents.
cgh is not a coding agent. It is an MCP server and a CLI that the agent you already use plugs into: Claude Code, Codex, Cursor, Gemini or IBM Bob. It keeps what those agents learn about a project, and it answers their questions about the code from a graph, so they find the code in fewer turns and pick up where the last session stopped.
- Shared project memory. Knowledge, decisions, gotchas and session digests are stored per repo, with where each one came from (session, branch, commit, PR, files). Every connected agent reads the same store, it survives a
/clearor a compaction, and it can be exported to another repo. - A code and document graph. Files, functions, classes, calls, imports, Terraform resources and Markdown sections are indexed locally. Lookups return an exact
file:line, so the agent reads those lines instead of whole files. Sibling repos can be federated into one view. - Faster navigation and continuity. Fewer turns and fewer tokens per code question, measured below, and a resume bundle that hands the next session the standing instructions, recent digests and open plans.
- Gates on what leaves the machine. Scanner findings (PII, secrets, confidentiality labels) are recorded in the graph, and plugins check them before a file goes to a cloud model.
Result: code questions answered in fewer turns and fewer tokens, learnings that survive context clears, and nothing leaving the machine without a gate. On a whole ticket the bill stays the same: both figures are below.
pip install cgh && cgh init && cgh serve
Why cgh: the measured gains
cgh answers code questions from the graph, returning exact file:line, instead of the agent reading whole files or grepping. Two benchmarks measure what that buys, at two scales. Both compare cost only across runs that every arm got right, so a cheap wrong answer never reads as a saving.
Per code question: fewer turns, fewer tokens. A two-arm benchmark asks the same navigation questions (where is X defined, who calls Y, what breaks if Z changes) twice against the same repo, once with cgh and once with Read/Grep only, over five runs of 5 to 8 tasks:
| with cgh, against Read/Grep only | |
|---|---|
| turns | 18 to 40% fewer |
| wall time | 19 to 36% faster |
| billed tokens, cache included | 12 to 31% fewer in four runs, 5% more in one |
| non-cached tokens (input and output, under 1% of the bill) | 33 to 61% fewer |
| correct answers | unchanged (all correct in both arms) |
The gap is widest on multi-file questions, where a graph beats text search. For "what breaks if I change _backend?", the agent has to follow call edges across a module:
| turns | non-cached tokens | |
|---|---|---|
| Read / Grep | 13 | 2607 |
| cgh | 6 | 886 |
That question is one command:
Per ticket: the same bill, a faster agent. A second benchmark replays already-merged tickets (API, front end, a Python service) from their parent commit: 78 runs, up to three per ticket and setup, judged blind against the merged pull request, with CI required. There, navigation is a small part of the work, and the per-question saving does not show in dollars:
| Claude Code alone, cgh as installed, cgh with a full ticket setup | |
|---|---|
| cost per ticket, every token type priced | the same: all three within x0.96 to x1.04 of each other |
| quality (blind judge, CI, the merged PR's own tests) | the same, within the run-to-run noise |
| wall time | about 2x faster with the full ticket setup, which hands the agent the file locations at the start and routes its searches to cgh. That setup is not yet part of cgh init |
So cgh makes finding code cheaper and quicker, and with the full ticket setup a ticket quicker, but not cheaper. Large token savings claimed for code graphs measure a single question against reading raw files, not a full piece of work.
Delegating writes. The cgh-codegen plugin does the same for writes: predictable, pattern-following code (tests, stubs, config, boilerplate) is handed to a cheap or local model that mirrors an existing file, and the reference never enters the primary model's context. cgh picks the file to mirror from the graph, so selecting it costs zero model tokens.
| task | reference size | primary-model tokens (without -> with) |
|---|---|---|
| generate an auth-stripping test suite | 108KB test file | ~27,980 -> ~100 (99.6%) |
generate a models.pyi type stub |
41KB module | ~14,000 -> ~100 (99.3%) |
Per task, what the agent does instead of reading files:
| Task | Without cgh | With cgh |
|---|---|---|
Find where process_data is defined |
Read 3-5 files (~2,000 tokens) | symbol_lookup (< 50 tokens) |
Find all callers of save_record |
Read every candidate file | find_callers (< 50 tokens) |
Understand blast radius of utils.py |
Read imports manually | subgraph (< 100 tokens) |
| Find docs about reconciliation | Read all .md files |
search_docs (< 50 tokens) |
| Build context for a task | 5-10 file reads (~5,000 tokens) | context_for_task (< 200 tokens) |
What this is not. The billed cost, once the model's prompt cache is counted, is roughly a wash on the read side: the cache dominates the invoice, so fewer turns do not cut it much. cgh's gain there is a smaller working context and fewer turns, not a smaller bill. On a trivial one-file edit cgh adds nothing. Run-to-run variance is real (around 20%), so read these as ratios over a task set rather than a single guaranteed number.
Install
pip install cgh # or: pipx install cgh / uv tool install cgh
pip install "cgh[docs]" # parse pdf, docx, xlsx and pptx
pip install "cgh[full]" # docs, plugins, extra language parsers, precise Python calls
cgh[plugins] and cgh[full] bring cgh-codegen and cgh-bugreport. CSV
parsing is built in; pdf, Word, Excel and PowerPoint parsing is opt-in with
cgh[docs] (it pulls the Office and pdf readers and their native wheels,
kept out of the core so a minimal install stays lean). Without the extra,
those files are skipped with a one-line hint.
cgh-pii (on-demand secret scanning, PII redaction) and cgh-vision (image
understanding) install by name; see docs/PLUGINS.md.
Upgrading from 0.14 or older? Read
docs/UPGRADING-0.15.md first: cgh no longer blocks
agent file access, the default plugin set is smaller, and the upgrade
command needs -U.
No Python? Run the standalone binary through npm, or download it from the latest release:
npx @altikva/cgh serve # fetches the binary for your OS, verifies it, runs it
npx @altikva/cgh --egress serve # the egress build, with the model-calling plugins
The binary uses the SQLite backend; uvx cgh bundles DuckDB and every plugin.
One-line installers for macOS, Linux, WSL, Git Bash and Windows PowerShell, corporate mirror
settings, optional extras and the cgh: command not found fix are in
docs/INSTALL.md. Python 3.11 through 3.14.
Quick start
# 1. Initialize (interactive wizard)
cgh init
# 2. Build the graph
cgh index
# 3. Check what was indexed
cgh stats
# 4. Start the MCP server for your AI tool
cgh serve --watch --reindex
cgh status tells you what the graph holds and whether it still matches the working tree:
How it works
AI Assistant (Claude / Cursor / Codex / Gemini / IBM Bob)
| symbol_lookup("process_data")
| search_docs("reconciliation")
| context_for_task("fix auth bug")
v
MCP server (cgh) <-- stdio, no network
| SQL graph query + BM25 FTS
v
DuckDB graph DB (.cgh/graph.duckdb) <-- embedded, file-based
SQLite FTS5 (.cgh/fts.db) <-- BM25 full-text search
| indexed from
v
Your source files (.py / .ts / .java / .go / .rs / .vue / .tf / .md)
^
File watcher (watchdog) <-- live incremental updates on save
Instead of reading services.py (800 tokens) to find where verify_token is defined, your AI calls symbol_lookup("verify_token") and gets back the file, the line range, the kind and the docstring, then reads only those lines.
Languages
Six languages get a full symbol graph, functions and classes and the calls
between them, with their imports resolved into File -> File edges:
| imports resolved | ||
|---|---|---|
| Python | .py .pyw |
yes |
| TypeScript, JavaScript | .ts .tsx .js .jsx .mjs .cjs |
yes |
| Java | .java |
yes |
| Go | .go |
yes |
| Rust | .rs |
yes |
| Vue SFC | .vue |
yes |
C# and Ruby parse too, behind pip install "cgh[langs]".
Alongside them, Markdown becomes a heading tree with its links and code references, Terraform yields resources, variables and outputs, and JSON, TOML, YAML and SQL expose their structure as sections. Every one of them is searchable and reachable from the graph.
Documents are read out of the box, no plugin needed: PDF pages, Word
headings and tables, Excel sheets, PowerPoint slides with their speaker
notes, and CSV / TSV summaries (header, size, first rows) all land in the
index as sections, so search_docs and cgh search --text find what is
inside them. Big files stay cheap: the size cap applies first and each
format bounds its own work (see docs/PARSERS.md).
Documentation
| Guide | What it covers |
|---|---|
| Install | one-line installers, extras, corporate mirrors, PATH |
| Upgrading to 0.15 | what changed for your agent, the upgrade command, old findings, rollback |
| Upgrading to 0.16 | the one-time re-parse, what refuses until then, federation and seeds, removed plugins, rollback |
| CLI reference | every verb and flag |
| Configuration | config.toml, environment variables, .cghignore |
| MCP tools | the tools your agent calls, by category |
| Integrations | Claude Code, Cursor, Codex, Gemini, IBM Bob |
| Federation | one parent repo querying its sub-repos read-only |
| Session memory | knowledge and plans that survive a context clear |
| Security | what can leave the machine, findings, the egress gate, the MCP auth key |
| Plugins | installing them, disabling them, writing one |
| Parsers | the parser interface and how to add a language |
| Graph schema | the nodes and edges the index holds |
| Embedding (SDK) | using cgh as a library |
Limitations
- CALLS resolution is name-based by default, guided by imports. For Python and TS/JS a call follows its shape: a same-file definition wins, then the file an import names (
from lib import f,import * as m),self.f()the class and its bases,obj.f()on a local or attribute whose class is known (built, annotated or returned by an annotated factory) that class, andobj.f()on an object of unknown type only the few methods of that name (or one in a file the caller imports). Calls into third-party modules and from production code into test files get no edge. Other languages link to a same-file function of that name, else to every function with that name outside test files. Cross-file edges stay best-effort: without types,obj.f()can miss its target or pick a look-alike. For Python you can opt into precise resolution withpip install cgh[lsp]andprecise_calls = true(jedi-backed). - Terraform is read file by file, not evaluated. Blocks, references, module inputs and
moved/import/removedare parsed with a real HCL grammar, but nothing is planned:count/for_eachinstances, dynamic blocks and computed addresses stay unexpanded, and a remote module is only read when[terraform] module_sourcesmaps it to a local checkout. - Imports resolve to files in your repo, never to dependencies. Python, JS/TS, Vue, Java, Go and Rust each map an import onto the file it names, following that language's own layout rules. Anything outside the repo stays unresolved on purpose: the standard library, a Go module you do not own, an external crate or npm package gets no node and no edge, because inventing one would be a lie about your code. Cross-repo edges are not inferred either, each federated scope is canonical for its own files.
- Markdown code refs are heuristic. PascalCase and snake_case patterns are matched, so a ref can be a false positive.
- Large repos take minutes to index. Incremental updates stay fast (well under a second per changed file), and a pull or merge reindexes only the changed files via the git hooks.
License
Licensed under the Apache License, Version 2.0, from version 0.19 on. That covers cgh itself, the first-party plugins under plugins/, the SDK and the npx wrapper. Copyright 2026 ALTIKVA; see NOTICE.
Versions 0.18.x and earlier were published under MIT and CC BY-NC-SA 4.0 and keep that license.
cgh MCP questions
What is cgh?
cgh is a context graph hub that acts as the project memory for coding agents like Claude Code, Cursor, and Gemini, providing a code and document graph.
Does cgh support multiple programming languages?
Yes, it provides full symbol graphs for Python, TypeScript, JavaScript, Java, Go, Rust, and Vue SFC, with additional support for C# and Ruby via plugins.
How does cgh improve agent performance?
It reduces the number of turns and tokens required by returning exact file:line locations from a graph instead of requiring the agent to read entire files.