ctxgraph-code 0.5.1

Code knowledge graph for Claude Code. Build a relationship graph of your Python codebase and query it during coding sessions.

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.

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

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

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:

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

ctxgraph-code init

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

build

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

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

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

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

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

ctxgraph-code symbols src/main.py

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

context

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

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

ctxgraph-code info
ctxgraph-code info --dir src

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

install-slash

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

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

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

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

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

[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 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