CseGraph

CseGraph is a local-first context system for coding agents. It indexes a repository into SQLite, retrieves the smallest useful code slices for a task, and exposes focused graph expansion only when structural evidence is needed.

CseGraph 2.0 is a hard compatibility cutoff:

• the index schema is csegraph-sqlite-v12;
• an index created by another schema must be rebuilt with csegraph index;
• there is no schema migration path;
• indexed source languages are Python, JavaScript, and TypeScript;
• the public surface is nine CLI commands and six strict MCP tools.

Install

CseGraph requires Python 3.10 or newer.

python -m pip install csegraph

Create a fresh index:

csegraph index /path/to/repository

Retrieve task-specific context:

csegraph context "Fix stale cache invalidation" \
  --repo /path/to/repository \
  --target Cache.invalidate \
  --token-budget 800 \
  --format markdown

Register the MCP server for a supported coding client:

csegraph install /path/to/repository --platform codex

CLI

The CLI has exactly nine commands:

Run csegraph --help or csegraph <command> --help for accepted arguments.

Agent workflow

Call csegraph_context directly for ordinary coding tasks. Use csegraph_minimal only for explicit index-health or repository-orientation requests. Escalate to csegraph_graph or csegraph_path only when the compact response recommends that focused structural operation.

The MCP server exposes exactly six tools:

Every MCP input schema rejects unknown properties.

Compact context v5

csegraph_context accepts task, repo, target, task_kind, token_budget, source_mode, and diagnostic. The first two are required. diagnostic is a boolean and defaults to false.

The only context response contract is csegraph-context-v5:

{
  "schema_version": "csegraph-context-v5",
  "status": "ready",
  "slices": [
    {
      "path": "package/cache.py",
      "lines": [42, 61],
      "symbol": "Cache.invalidate",
      "role": "target",
      "code": "..."
    }
  ]
}

Depending on status and request, the response may also contain candidates, missing, next, warnings, or diagnostics. Diagnostics are included only when requested and remain inside the same whole-response token budget.

Every continuation has one shape:

{
  "tool": "csegraph_graph",
  "arguments": {"repo": "/path/to/repository", "node": "Cache.invalidate"},
  "reason": "Inspect direct dependents."
}

tool is required; arguments and reason are optional.

Index lifecycle

The repository index is stored at .csegraph/index.db. csegraph index builds and validates a new database beside the active database, then replaces the active database atomically. A failed build leaves the active database intact. Successful replacement leaves no backup or migration artifact.

Commands that encounter a missing or non-v12 index report index_required and direct the caller to csegraph_index or csegraph index.

Benchmarks

Benchmark runners are maintainer tools under tools/; benchmarking is not a product CLI or MCP operation. Benchmark evidence is tracked in benchmark_results/ and summarized in Benchmark Evidence.

Development

python -m pip install -e ".[test,dev]"
python -m pytest -q
python -m ruff check .
python -m ruff format --check .
python -m mypy

Local indexes, caches, build outputs, benchmark reports, cloned sandbox repositories, and editor dependencies are disposable. They are ignored by git and should be removed before sharing a clean checkout.

Privacy

Indexing, retrieval, refresh, and MCP operation run locally. CseGraph does not execute indexed code and normal operation requires no network request.

License

MIT