ctxgraph-code 0.3.0

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 Python codebase so Claude Code understands imports, class hierarchies, function calls, and cross-file dependencies without reading every file.

pip install ctxgraph-code
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
pip install ctxgraph-code

# Navigate to your Python 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

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

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.

---

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 parses every .py file with Python's ast module. It extracts imports, class/function definitions, function calls, and docstrings. The result is a graph of nodes (files, classes, functions) and edges (imports, defines, extends, 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
class	class:src/api/routes.py::UserAPI	Name, path, parent file, docstring, line number
function	func:src/models.py::get_user	Name, path, parent, docstring, 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

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

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
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 before AST parse for files with no imports/classes/functions
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

---

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 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+	12 (init, build, query, deps, usedby, overview, symbols, context, setup, view, info, install-slash, build-status)
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)

---

License

MIT