Metadata-Version: 2.4
Name: csegraph
Version: 2.0.1
Summary: Repository context engine for coding agents with CLI, MCP server, and Python facade.
Author: Rishabh Shah, Hitanshu Oza
License-Expression: MIT
Project-URL: Repository, https://github.com/RishiiShah/CseGraph
Project-URL: Issues, https://github.com/RishiiShah/CseGraph/issues
Project-URL: Documentation, https://github.com/RishiiShah/CseGraph#readme
Project-URL: Changelog, https://github.com/RishiiShah/CseGraph/blob/main/CHANGELOG.md
Keywords: code graph,context,coding agents,mcp,tree-sitter
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
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 :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.0.0
Requires-Dist: tiktoken<1,>=0.13
Requires-Dist: tree-sitter>=0.23
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter-javascript>=0.23
Provides-Extra: test
Requires-Dist: pytest>=9.0.3; extra == "test"
Requires-Dist: setuptools>=68; extra == "test"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "test"
Provides-Extra: benchmark
Requires-Dist: tiktoken<1,>=0.13; extra == "benchmark"
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.6; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Dynamic: license-file

# 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.

```bash
python -m pip install csegraph
```

Create a fresh index:

```bash
csegraph index /path/to/repository
```

Retrieve task-specific context:

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

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

## CLI

The CLI has exactly nine commands:

| Command | Purpose |
|---|---|
| `csegraph index` | Build and atomically install a fresh v12 index. |
| `csegraph refresh` | Apply changed and deleted files to an existing v12 index. |
| `csegraph context` | Retrieve compact, budgeted task context. |
| `csegraph graph` | Inspect a focused graph neighborhood. |
| `csegraph path` | Find a focused dependency path. |
| `csegraph status` | Report index health and freshness. |
| `csegraph doctor` | Diagnose MCP client setup. |
| `csegraph install` | Register CseGraph with an MCP client. |
| `csegraph serve` | Start the MCP stdio server. |

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:

| Tool | Purpose |
|---|---|
| `csegraph_index` | Build a fresh repository index. |
| `csegraph_refresh` | Refresh changed and deleted files. |
| `csegraph_minimal` | Return a small health or orientation summary. |
| `csegraph_context` | Return compact task-specific code slices. |
| `csegraph_graph` | Return a focused neighborhood. |
| `csegraph_path` | Return a focused dependency path. |

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

```json
{
  "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:

```json
{
  "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](docs/benchmarks.md).

## Development

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