Metadata-Version: 2.4
Name: cgh
Version: 0.12.0
Summary: Local code graph for AI coding agents. Indexes your repo into an embedded graph DB (DuckDB by default, Kuzu opt-in) plus SQLite FTS, exposes 50 MCP tools to Claude Code, Cursor, Codex, and Gemini. Federates across sibling repos.
Author-email: Joy Ndjama <joy.ndjama@altikva.com>
Maintainer-email: ALTIKVA <dev@altikva.com>
License: ALTIKVA Dual License v1.0
        =========================
        
        Copyright (c) 2026 ALTIKVA
        
        This software is dual-licensed under the terms of BOTH of the
        following licenses at once. This is not a choice between them: you
        must comply with both simultaneously.
        
          - The MIT License (full text below), AND
          - The Creative Commons Attribution-NonCommercial-ShareAlike 4.0
            International License (CC BY-NC-SA 4.0), full text at:
            https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode
        
        Because both licenses apply together, the more restrictive terms
        control where they overlap. In practice: use is non-commercial
        only, derivative works must be shared under these same terms,
        attribution is required, and the software is provided "as is"
        without warranty of any kind.
        
        The canonical version of this dual license notice is published at
        https://www.altikva.com/licenses/LICENSE-1.0
        
        
        ----------------------------------------------------------------------
        Additional permission: SDK embedding exception
        ----------------------------------------------------------------------
        
        As an additional permission granted by the copyright holder, use of
        this software solely through its documented embedding surface, the
        "codegraph.sdk" module and the public data types it exchanges, as
        documented in docs/EMBEDDING.md, may be made under the terms of the
        MIT license alone, without the CC BY-NC-SA 4.0 terms, including in
        commercial products.
        
        This permission is scoped to the surface: it covers calling the
        functions and types exported by "codegraph.sdk" and whatever this
        software executes on the caller's behalf as a result of those calls.
        It does NOT extend to:
        
          - importing or invoking any other module of this software directly;
          - copying or modifying this software's source beyond the surface
            imports described above;
          - the code graph index, MCP server, federation, shared memory and
            CLI features, which the SDK surface does not expose and which
            remain governed by the dual license above.
        
        Versions of this software published with this exception keep it for
        those versions irrevocably; the copyright holder may widen but not
        narrow the surface for already-published versions.
        
        ----------------------------------------------------------------------
        Additional permission: plugin exception
        ----------------------------------------------------------------------
        
        As an additional permission granted by the copyright holder, a "cgh
        plugin" is not considered an adaptation, a derivative work, or a work
        based on this software for the purposes of either license above.
        
        A cgh plugin is a separate work that interacts with this software
        solely through its documented plugin interfaces: the "cgh" entry-point
        group, the public plugin API module, and the public data types those
        interfaces exchange, as documented by the project. Importing those
        interfaces does not, by itself, subject the plugin to the terms above.
        
        Authors of cgh plugins may therefore license and distribute their
        plugins under any terms of their choosing, including proprietary or
        commercial terms.
        
        This exception does NOT apply to:
        
          - copies of, or modifications to, this software itself, in whole or
            in part, beyond the interface imports described above;
          - distributing this software, alone or bundled with a plugin;
          - the use of this software itself, which remains governed by the
            licenses above (including the NonCommercial term) regardless of
            which plugins are installed alongside it.
        
        
        ----------------------------------------------------------------------
        MIT License
        ----------------------------------------------------------------------
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        
        ----------------------------------------------------------------------
        CC BY-NC-SA 4.0 (summary, not a substitute for the canonical text)
        ----------------------------------------------------------------------
        
        You are free to:
          - Share: copy and redistribute the material in any medium or format
          - Adapt: remix, transform, and build upon the material
        
        Under the following terms:
          - Attribution: you must give appropriate credit, provide a link to
            the license, and indicate if changes were made.
          - NonCommercial: you may not use the material for commercial purposes.
          - ShareAlike: if you remix, transform, or build upon the material,
            you must distribute your contributions under the same license.
        
        Full legal text:
          https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode
        
Project-URL: Homepage, https://github.com/altikva/cgh
Project-URL: Repository, https://github.com/altikva/cgh
Project-URL: Issues, https://github.com/altikva/cgh/issues
Project-URL: Changelog, https://github.com/altikva/cgh/blob/main/CHANGELOG.md
Keywords: code-graph,mcp,mcp-server,claude,claude-code,cursor,code-index,symbol-lookup,call-graph,ai-agents
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: Free for non-commercial use
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: duckdb>=1.2
Requires-Dist: tree-sitter>=0.23
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter-go>=0.23
Requires-Dist: tree-sitter-rust>=0.23
Requires-Dist: tree-sitter-java>=0.23
Requires-Dist: watchdog>=4.0
Requires-Dist: fastmcp<5,>=2.0
Requires-Dist: rank-bm25>=0.2
Requires-Dist: rich>=13.0
Requires-Dist: questionary>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: kuzu
Requires-Dist: kuzu>=0.7; extra == "kuzu"
Provides-Extra: plugins
Requires-Dist: cgh-docs>=0.2; extra == "plugins"
Requires-Dist: cgh-pii>=0.3.1; extra == "plugins"
Requires-Dist: cgh-summarize>=0.2.4; extra == "plugins"
Requires-Dist: cgh-classify>=0.1.3; extra == "plugins"
Requires-Dist: cgh-bugreport>=0.1.1; extra == "plugins"
Requires-Dist: cgh-vision[pdf]>=0.5; extra == "plugins"
Provides-Extra: full
Requires-Dist: cgh-docs>=0.2; extra == "full"
Requires-Dist: cgh-pii>=0.3.1; extra == "full"
Requires-Dist: cgh-summarize>=0.2.4; extra == "full"
Requires-Dist: cgh-classify>=0.1.3; extra == "full"
Requires-Dist: cgh-bugreport>=0.1.1; extra == "full"
Requires-Dist: cgh-vision[pdf]>=0.5; extra == "full"
Requires-Dist: tree-sitter-c-sharp>=0.23; extra == "full"
Requires-Dist: tree-sitter-ruby>=0.23; extra == "full"
Requires-Dist: jedi>=0.19; extra == "full"
Provides-Extra: langs
Requires-Dist: tree-sitter-c-sharp>=0.23; extra == "langs"
Requires-Dist: tree-sitter-ruby>=0.23; extra == "langs"
Provides-Extra: lsp
Requires-Dist: jedi>=0.19; extra == "lsp"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/altikva/cgh/main/assets/img/cgh-cli.svg" alt="The cgh CLI landing screen: banner, command list, and examples" width="820">
</p>

**Local code graph, shared memory and guardrails for AI coding assistants.**

Parses your repo into a graph of files, functions, classes, Terraform resources, and Markdown documentation -- then exposes it as an MCP server so Claude Code, Cursor, Codex, Gemini, and IBM Bob can do symbol-level lookups instead of reading entire files. On top of the graph: a knowledge and session memory every connected agent shares, and a confidentiality layer (findings, egress gate, per-agent guard hooks) that decides what an agent may read and what may reach a cloud model.

**Result:** 40-60% fewer context tokens on typical navigation tasks, learnings that survive context clears, and nothing leaving the machine without a gate.

```bash
pip install cgh && cgh init && cgh serve
```

---

## Why cgh: the measured gains

cgh's job is to keep an agent's working context small and its round-trips few. It answers code questions from the graph, returning exact `file:line`, instead of the agent reading whole files or grepping. That shows up as fewer context tokens and fewer turns, at equal correctness.

The figures below come from a two-arm benchmark: the same tasks run twice against the same repo, once with cgh available and once with Read/Grep only, scored on each session's token usage, turn count, and answer correctness. Cost is compared only across tasks both arms got right, so a cheap wrong answer never reads as a saving.

**On code-navigation tasks: about 40 to 60% fewer context tokens and 20 to 40% fewer turns, correctness unchanged.**

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 | context tokens |
|---|---|---|
| Read / Grep | 13 | 2607 |
| cgh | 6 | 886 |

That question is one command:

<p align="center">
  <img src="https://raw.githubusercontent.com/altikva/cgh/main/assets/img/cgh-callers.svg" alt="cgh callers: the call graph of resolve_import rendered as a tree with exact file and line" width="820">
</p>

**Delegating writes.** The [`cgh-codegen`](plugins/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

```bash
pip install cgh                 # or: pipx install cgh / uv tool install cgh
pip install "cgh[full]"         # plugins, extra language parsers, precise Python calls
```

No Python? Run the standalone binary through npm, or download it from the
[latest release](https://github.com/altikva/cgh/releases/latest):

```bash
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](docs/INSTALL.md)**. Python 3.11 through 3.14.

## Quick start

```bash
# 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:

<p align="center">
  <img src="https://raw.githubusercontent.com/altikva/cgh/main/assets/img/cgh-status.svg" alt="cgh status: backend, owner, scan freshness, import coverage and file count" width="820">
</p>

## 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 (codegraph)          <-- stdio, no network
    |  SQL graph query + BM25 FTS
    v
DuckDB graph DB (.codegraph/graph.duckdb)   <-- embedded, file-based (default)
                                            -- or Kuzu graph.db via CGH_DB=kuzu
SQLite FTS5 (.codegraph/fts.db)       <-- BM25 full-text search
    |  indexed from
    v
Your source files (.py / .ts / .tf / .md / .vue)
    ^
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.

---

## Documentation

| Guide | What it covers |
|---|---|
| [Install](docs/INSTALL.md) | one-line installers, extras, corporate mirrors, PATH |
| [CLI reference](docs/CLI_REFERENCE.md) | every verb and flag |
| [Configuration](docs/CONFIGURATION.md) | `config.toml`, environment variables, `.cghignore` |
| [MCP tools](docs/MCP_TOOLS.md) | the tools your agent calls, by category |
| [Integrations](docs/INTEGRATIONS.md) | Claude Code, Cursor, Codex, Gemini, IBM Bob |
| [Federation](docs/FEDERATION.md) | one parent repo querying its sub-repos read-only |
| [Session memory](docs/MEMORY.md) | knowledge and plans that survive a context clear |
| [Security](docs/SECURITY.md) | findings, secure mode, the guard, the MCP auth key |
| [Plugins](docs/PLUGINS.md) | installing them, disabling them, writing one |
| [Parsers](docs/PARSERS.md) | the parser interface and how to add a language |
| [Graph schema](docs/SCHEMA.md) | the nodes and edges the index holds |
| [Embedding (SDK)](docs/EMBEDDING.md) | using cgh as a library |

---

## Limitations

- **CALLS resolution is name-based by default.** A call is linked to a same-file function of that name, falling back to all repo functions with that name only when there is no same-file match, so cross-file call edges are best-effort. For Python you can opt into precise cross-file resolution with `pip install cgh[lsp]` and `precise_calls = true` (jedi-backed); other languages stay name-based.
- **Terraform HCL uses regex, not a full grammar.** Complex meta-arguments may be missed.
- **JS/TS imports resolve to local files only.** Relative imports, tsconfig `paths` aliases, `~/` and `@/` conventions, and workspace packages do create a `File -> File` IMPORTS edge. Bare external packages are not resolved to a node, and cross-repo edges are not inferred.
- **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

Dual-licensed under MIT **and** CC BY-NC-SA 4.0: both licenses apply together and you must comply with both. In practice that means non-commercial use, share-alike derivatives, attribution, and no warranty. Copyright (c) 2026 ALTIKVA. See [LICENSE](./LICENSE) or the canonical notice at https://www.altikva.com/licenses/LICENSE-1.0.

**Plugin exception**: a plugin that talks to cgh only through the documented plugin interfaces (the `cgh` entry-point group and the public plugin API) is not treated as a derivative work and may be licensed under any terms its author chooses, including commercial ones. Using cgh itself stays under the dual license whatever plugins are installed. Full wording in [LICENSE](./LICENSE).
