Metadata-Version: 2.4
Name: ctxgraph-code
Version: 0.6.1
Summary: Code knowledge graph for Claude Code. Build a relationship graph of your Python codebase and query it during coding sessions.
Author: ctxgraph-code contributors
License: MIT
Keywords: code-graph,knowledge-graph,claude-code,code-analysis,ctx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.0
Provides-Extra: full
Requires-Dist: tree-sitter>=0.22; extra == "full"
Requires-Dist: tree-sitter-language-pack>=0.13; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# ctxgraph-code

**Code knowledge graph for Claude Code.** Build a relationship graph of your codebase (Python, JavaScript, TypeScript, C, Go, Rust, and more) so Claude Code understands imports, class hierarchies, function calls, and cross-file dependencies without reading every file.

```bash
pip install ctxgraph-code
# For multi-language support (C, Go, Rust, JS, TS, Java, etc.):
pip install 'ctxgraph-code[full]'
cd my-project
ctxgraph-code setup
```

Then in Claude Code, type `/ctxgraph-code` and Claude will use the graph.

---

## Why?

Claude Code already reads files, searches code, and understands syntax. But it can't see **relationships** between files without manual exploration:

- *What does this file import?*
- *What depends on this function?*
- *Where is this class defined?*
- *What calls this API endpoint?*

These questions require running multiple `grep` commands or reading dependency chains file by file. `ctxgraph-code` pre-computes all of this via static AST analysis and stores it in a queryable SQLite graph — so Claude can answer relationship questions in one command.

## Quick Start

```bash
# Install (add [full] for multi-language support)
pip install 'ctxgraph-code[full]'

# Navigate to your project
cd my-project

# One-command setup: init + build + configure Claude Code
ctxgraph-code setup

# Open Claude Code and type:
#   /ctxgraph-code
```

## Commands

### `setup` (recommended)

```bash
ctxgraph-code setup
```

Interactive walkthrough — prompts for:
- **File extensions** to scan (`.py`, `.js`, `.ts`, etc.)
- **Exclude patterns** (folders like `tests/`, globs like `*.generated.py`)

Does everything in one step:
1. Creates `.ctxgraph/config.toml` with your chosen extensions and excludes
2. Installs the `/ctxgraph-code` slash command globally (works in every Claude Code session)
3. Builds the knowledge graph from all matching files — shows live per-graph progress:
   ```
   Building 5 graphs with 8 workers...
     ✔ src/ (42 files, 156 nodes, 34 edges, 0.8s)
     ✔ api/ (18 files, 73 nodes, 12 edges, 0.4s)
     ✔ tests/ (31 files, 89 nodes, 0 edges, 0.6s)
   Built all 5 graphs in 2.1s
   ```

Non-interactive mode:
```bash
ctxgraph-code setup --extensions .py,.js,.ts --exclude tests/,examples/
ctxgraph-code setup -y                                 # all defaults
```

Options:
- `--project-slash` — install slash command in project's `.claude/` instead of globally
- `--background` / `-b` — launch build in background and exit immediately (check with `build-status`)
- `--jobs` / `-j` — number of parallel workers (default: CPU count)
- `--incremental` / `-i` — only rebuild files that changed since last build
- `--verbose` / `-v` — show per-file progress
- `--no-summary` — skip docstring extraction for faster builds

### `init`

```bash
ctxgraph-code init
```

Creates the `.ctxgraph/` directory with a default `config.toml`.

### `build`

```bash
ctxgraph-code build
ctxgraph-code build --extensions .py,.js,.ts
ctxgraph-code build --exclude tests/ --exclude *.generated.py
```

Scans all matching files in the project, runs AST analysis. Extensions are read from config (`.py` by default, or whatever was set in `setup`).

**By default, builds a separate graph per top-level directory** (e.g., `src/`, `api/`, `tests/`) in parallel. This keeps each graph small and fast to query. Use `--dir <name>` on query commands to select one, or let it auto-detect from file paths.

- `--all` / `-a` — build a single combined graph instead of per-directory
- `--jobs` / `-j` — number of parallel workers (default: CPU count)
- `--incremental` / `-i` — only rebuild files that changed since last build
- `--verbose` / `-v` — show per-file progress
- `--no-summary` — skip docstring extraction for faster builds

Shows live per-graph progress as each completes:
```
Building 5 graphs with 8 workers...
  ✔ src/ (42 files, 156 nodes, 34 edges, 0.8s)
  ✔ api/ (18 files, 73 nodes, 12 edges, 0.4s)
  ✔ tests/ (31 files, 89 nodes, 0 edges, 0.6s)
Built all 5 graphs in 2.1s
```

Stores graphs in `.ctxgraph/graphs/<dir>.db` (per-directory) or `.ctxgraph/graph.db` (combined).

> The graph is a **static snapshot**. If code changes, run `ctxgraph-code build` again to refresh. Use `--incremental` to only reprocess changed files.

### `query`

```bash
ctxgraph-code query "user authentication"
ctxgraph-code query "database connection" --max 20
ctxgraph-code query "api routes" --dir src
```

Searches the graph by relevance scoring (name matches > summary matches > path matches) and expands to neighboring nodes via BFS up to depth 2. Use `--dir` to scope to a specific per-directory graph.

### `deps`

```bash
ctxgraph-code deps src/api/routes.py
```

Shows all relationships for a file: imports, imported-by, function calls, class definitions. Auto-detects the per-directory graph from the file path.

### `usedby`

```bash
ctxgraph-code usedby src/utils/helpers.py
```

Shows every file that imports or calls something in the given file. Useful to understand **ripple effects** before making changes.

### `overview`

```bash
ctxgraph-code overview
ctxgraph-code overview --dir src
```

Prints the project structure: every file with its summary and top-level symbols. Use `--dir` to scope to a per-directory graph.

### `symbols`

```bash
ctxgraph-code symbols src/main.py
```

Lists all classes and functions defined in a file, with line numbers and docstring summaries.

### `context`

```bash
ctxgraph-code context "add pagination to the users endpoint"
```

Generates a focused context summary: relevant files, their symbols, and dependency/call edges between them. This is the closest equivalent to `ctxgraph`'s capsule format.

### `view`

```bash
ctxgraph-code view                 # generates interactive D3.js HTML and opens browser
ctxgraph-code view --no-open       # generate HTML without opening browser
ctxgraph-code view --tree          # show text tree instead (useful in terminal)
ctxgraph-code view --output graph.html  # save to custom path
```

Opens an **interactive D3.js force-directed graph** in the browser. Drag nodes, zoom/pan, search by name, filter by type (File/Class/Function). Hover to highlight connected nodes and see summaries.

The HTML is self-contained (loads D3.js from CDN) and saved to `.ctxgraph/graph.html`.

Use `--tree` for a terminal-friendly text view of the directory hierarchy with symbols and edges.

### `info`

```bash
ctxgraph-code info
ctxgraph-code info --dir src
```

Shows graph statistics: node/edge counts, type distribution, build time.

### `install-slash`

```bash
ctxgraph-code install-slash
ctxgraph-code install-slash --project-slash   # project-local instead of global
```

Install or update the `/ctxgraph-code` slash command for Claude Code. By default installs globally so it works in every Claude Code session. Use `--project-slash` to install in the project's `.claude/commands/` directory instead.

### `build-status`

```bash
ctxgraph-code build-status
```

Check whether a background build (`ctxgraph-code setup --background` or `ctxgraph-code build`) completed, failed, or is still running. Shows PID and start time for in-progress builds.

### `probe`

```bash
ctxgraph-code probe "database connection pool"
ctxgraph-code probe "user authentication" --max 3
```

Searches the graph for relevant nodes **and reads the actual source code** inline. Claude gets paths + source in one command, saving 1–2 tool calls. Shows the first N lines of matched files with automatic syntax highlighting per language.

- `--max` / `-m` — max files to probe (default: 5)
- `--context` / `-c` — lines to show per file (default: 40, use 0 for full file)

### `install-hooks`

```bash
ctxgraph-code install-hooks
ctxgraph-code install-hooks --local
```

Installs a **PreToolUse hook** in `.claude/settings.json` (global) or `.claude/settings.local.json` (project-local). On every `Bash|Glob|Grep` tool call, Claude Code automatically runs `ctxgraph-code hook-check` and injects graph context into the conversation — letting it know the graph exists, key files, and whether anything is stale.

Also prompted during `ctxgraph-code setup`.

### `uninstall-hooks`

```bash
ctxgraph-code uninstall-hooks
```

Removes the PreToolUse hooks installed by `install-hooks`.

---

## How It Works

```
Python files  ──AST──>  Import/Symbol/Call analysis  ──>  SQLite graph.db
                                                               │
Claude Code  ──/ctxgraph-code──>  CLI query/deps/overview  <───┘
```

1. **Build phase**: `ctxgraph-code build` scans every matching file. Python files are analyzed with Python's `ast` module (fast, rich analysis with docstrings). All other languages (C, C++, JavaScript, TypeScript, Go, Rust, Java, Ruby, and more) are analyzed with **tree-sitter** via `tree-sitter-language-pack`. The result is a graph of **nodes** (files, functions, classes, structs, imports, calls) and **edges** (imports, defines, calls) stored in SQLite.

2. **Query phase**: In Claude Code, the `/ctxgraph-code` slash command injects instructions into the conversation. Claude then runs `ctxgraph-code` commands as shell commands to query the graph. Claude reads the text output and reasons about it alongside its own file-reading capabilities.

### What's in the graph

| Node type | Example ID | Stored |
|-----------|-----------|--------|
| `file` | `file:src/api/routes.py` | Name, path, size, summary |
| `function` | `func:src/models.py::get_user` | Name, path, parent, summary, line number |
| `class` | `class:src/api/routes.py::UserAPI` | Name, path, parent file, summary, line number |
| `struct` | `struct:src/types.c::Point` | Name, path, parent file, line number |
| `interface` | `interface:src/types.ts::IUser` | Name, path, parent file, line number |
| `trait` | `trait:src/main.rs::Drawable` | Name, path, parent file, line number |
| `import` | `import:src/main.c::stdio.h` | Import path, parent file |
| `call` | `call:src/index.js::parse` | Function name, parent file, line number |

| Edge relation | Meaning |
|--------------|---------|
| `imports` | File A imports file B (or a symbol from it) |
| `defines` | A file/class defines a class/function |
| `extends` | Class A extends class B |
| `calls` | Function A calls function B |
| `includes` | C/C++ file includes a header |

Edge weights: `imports=1.0`, `defines=1.0`, `extends=0.8`, `calls=0.7`, `includes=0.6`

### Tamper Detection

Every build stores **SHA256 content hashes** for every analyzed file in the graph metadata. On every query, `ctxgraph-code` re-reads the file content, recomputes the hash, and compares:

- **No match → tamper warning** shown at the bottom of every command output
- PreToolUse hook also warns inside Claude Code before any search/grep tool runs
- Use `ctxgraph-code build --incremental` to refresh only tampered files

This catches the common case where you edit a file after building the graph and Claude would otherwise see stale data.

### Query relevance scoring

1. Tokenize query (lowercase, split on word boundaries, remove stopwords)
2. For each matching node: name match → +2.0 per token, text match → +0.5 per occurrence
3. Multiply by `0.5 + importance` (files=0.5, classes=0.6, functions=0.5)
4. BFS expansion: neighbor nodes get `0.1 × number_of_matched_neighbors`
5. Return top-N results sorted by score

---

## Performance

`ctxgraph-code` includes several optimizations for large codebases:

| Optimization | Details |
|---|---|
| **Multi-language** | Uses Python `ast` for `.py` (fast + docstrings) and **tree-sitter** for 25+ languages (C, C++, JS, TS, Go, Rust, Java, Ruby, Kotlin, Swift, and more) |
| **Parallel builds** | Per-directory graphs build concurrently via `ThreadPoolExecutor` |
| **Multiprocessing** | Combined graphs split files across CPU cores via `multiprocessing.Pool` |
| **`--jobs`** | Control parallelism level (default: CPU count) |
| **Incremental builds** | `--incremental` caches file mtimes, only reprocesses changed files |
| **Trivial file skip** | `_quick_scan()` pre-checks all files (Python and non-Python) — skips full parse for files with no code |
| **`follow_symlinks` config** | Respects `follow_symlinks = false` setting to avoid duplicate/broken symlinks |
| **`max_file_size_mb` config** | Skips files exceeding the configured size limit before reading |
| **Live build progress** | Per-graph status + timing as each completes during parallel builds |
| **Cached excludes** | `lru_cache` on `should_exclude()` during `os.walk` |
| **Batch SQLite inserts** | `executemany` instead of per-row `INSERT` statements |
| **`--no-summary`** | Skips docstring extraction (fastest rebuilds) |
| **`--background`** | Detach build process and continue working immediately |
| **Tamper detection** | SHA256 content hashes per file; warns on tampered data in every command output |
| **PreToolUse hook** | Claude Code auto-injects graph context before Bash/Glob/Grep, saving 1-3 exploratory tool calls |

---

## Using with Claude Code

After `ctxgraph-code setup`, the `/ctxgraph-code` slash command is installed globally by default — it works in every Claude Code session. Claude sees:

```
# ctxgraph-code: Code Relationship Graph

**First time in this project?** Tell the user to run `ctxgraph-code setup`.
**Graph needs refresh?** Tell the user to run `ctxgraph-code build`.
**Available graphs:** src api tests

**Commands:**
- `ctxgraph-code query "terms"` -- Find relevant files, classes, and functions
- `ctxgraph-code probe "question"` -- Search graph and read matching source inline
- `ctxgraph-code deps <path>` -- Show what a file imports and what calls it
- `ctxgraph-code usedby <path>` -- Show what depends on a file
- `ctxgraph-code overview --dir <name>` -- Show project structure for a specific graph
- `ctxgraph-code symbols <path>` -- List classes/functions defined in a file
- `ctxgraph-code context "task"` -- Generate a focused context summary
- `ctxgraph-code view --dir <name>` -- Visualize a graph interactively
```

Claude then uses these commands as needed during the conversation.

### Example workflow

**You:** "Add rate limiting to the user API endpoints"

**Claude does:**
1. `ctxgraph-code query "user api endpoint rate limit"` → finds relevant files
2. `ctxgraph-code deps src/api/users.py` → sees what it imports and what calls it
3. Reads actual source via built-in `read` tool
4. Writes the rate-limiting code, knowing the full dependency context

---

## Configuration

Configure via `.ctxgraph/config.toml` (created interactively by `setup` or manually):

```toml
[graph]
# File extensions to scan
extensions = [".py", ".js", ".ts"]
# Exclude patterns beyond built-in defaults
exclude = ["tests/", "examples/"]
# Follow symlinks when scanning
follow_symlinks = false
# Skip files larger than this (MB)
max_file_size_mb = 5
```

Built-in default exclusion patterns (always applied): `__pycache__`, `*.pyc`, `.git`, `node_modules`, `venv`, `.venv`, `dist`, `build`, `*.egg-info`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, `.tox`, `migrations`, `*.min.js`, `*.min.css`.

---

## Differences from `ctxgraph`

`ctxgraph-code` is a **focused subset** of [ctxgraph](https://github.com/shashi3070/ctxgraph) designed specifically for Claude Code.

| Feature | ctxgraph | ctxgraph-code |
|---------|----------|---------------|
| CLI commands | 9+ | 17 (init, build, query, deps, usedby, overview, symbols, context, setup, view, info, install-slash, build-status, probe, install-hooks, uninstall-hooks, version) |
| LLM integration | Built-in (Ollama, Claude, OpenAI, Azure) | None (delegates to Claude Code) |
| Chat sessions | Yes | No |
| Visualizer | D3.js HTML + SVG | D3.js HTML (`view` opens in browser, `--tree` for text) |
| Skills system | Yes (customizable skill TOML files) | No |
| MCP server | Yes | No |
| Token savings | Yes (capsule DSL compression) | No |
| Dependency | `mcp` optional, `anyio` optional | `typer`, `rich` only |
| Claude integration | MCP protocol (Claude Desktop) | Slash command (Claude Code) |
| Windows compatibility | Blocked by `pywintypes.dll` with mcp≥1.27.2 | No issues |

## Requirements

- Python 3.10+
- A Claude Code subscription (for the `/ctxgraph-code` slash command — the graph itself works standalone)
- For multi-language analysis (C, Go, Rust, JS, TS, Java, etc.): `pip install 'ctxgraph-code[full]'` to install tree-sitter support

---

## License

MIT
