ctxgraph-code 0.2.1__tar.gz → 0.4.0__tar.gz

{ctxgraph_code-0.2.1 → ctxgraph_code-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxgraph-code
-Version: 0.2.1
+Version: 0.4.0
 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
@@ -23,7 +23,7 @@ Requires-Dist: pytest>=7.0; extra == "dev"
 
 # 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.
+**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
@@ -76,15 +76,23 @@ Interactive walkthrough — prompts for:
 
 Does everything in one step:
 1. Creates `.ctxgraph/config.toml` with your chosen extensions and excludes
-2. Builds the knowledge graph from all matching files
-3. Creates `.claude/commands/ctxgraph-code.md` with instructions for Claude Code
+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 (skip prompts):
+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
@@ -103,24 +111,27 @@ 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`).
 
-- **Imports**: which files import other files
-- **Class definitions**: class names, base classes, methods
-- **Function definitions**: function names, arguments
-- **Function calls**: which functions call which (within the project)
-- **Docstrings**: extracted as node summaries
+**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 the result in `.ctxgraph/graph.db`.
+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. Claude Code will also rebuild when it detects the graph is stale.
+> 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.
+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`
 
@@ -128,7 +139,7 @@ Searches the graph by relevance scoring (name matches > summary matches > path m
 ctxgraph-code deps src/api/routes.py
 ```
 
-Shows all relationships for a file: imports, imported-by, function calls, class definitions.
+Shows all relationships for a file: imports, imported-by, function calls, class definitions. Auto-detects the per-directory graph from the file path.
 
 ### `usedby`
 
@@ -142,9 +153,10 @@ Shows every file that imports or calls something in the given file. Useful to un
 
 ```bash
 ctxgraph-code overview
+ctxgraph-code overview --dir src
 ```
 
-Prints the project structure: every file with its summary and top-level symbols.
+Prints the project structure: every file with its summary and top-level symbols. Use `--dir` to scope to a per-directory graph.
 
 ### `symbols`
 
@@ -181,10 +193,59 @@ Use `--tree` for a terminal-friendly text view of the directory hierarchy with s
 
 ```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 40 lines of matched files with syntax highlighting.
+
+- `--max` / `-m` — max files to probe (default: 5)
+- `--context` / `-c` — lines of context around matches (default: 3)
+
+### `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
@@ -192,10 +253,10 @@ Shows graph statistics: node/edge counts, type distribution, build time.
 ```
 Python files  ──AST──>  Import/Symbol/Call analysis  ──>  SQLite graph.db
                                                                │
-Claude Code  ──/ctxgraph-code──>  CLI query/deps/overview  <────┘
+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.
+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.
 
@@ -204,8 +265,13 @@ Claude Code  ──/ctxgraph-code──>  CLI query/deps/overview  <────
 | 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 |
+| `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 |
 |--------------|---------|
@@ -213,8 +279,19 @@ Claude Code  ──/ctxgraph-code──>  CLI query/deps/overview  <────
 | `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`
+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
 
@@ -226,25 +303,47 @@ Edge weights: `imports=1.0`, `defines=1.0`, `extends=0.8`, `calls=0.7`
 
 ---
 
-## Using with Claude Code
+## 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 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 |
+| **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 |
 
-After `ctxgraph-code setup`, Claude Code in the project directory will have the `/ctxgraph-code` slash command available.
+---
+
+## Using with Claude Code
 
-When you type `/ctxgraph-code`, Claude sees:
+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
 
-This project has a knowledge graph at `.ctxgraph/graph.db`.
-The graph knows about imports, class hierarchies, and function calls.
-
-Available commands:
-- ctxgraph-code query "search 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              -- Show the full project structure
-- ctxgraph-code symbols <path>        -- List classes/functions defined in a file
-- ctxgraph-code context "task"        -- Generate a focused context summary
+**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.
@@ -287,7 +386,7 @@ Built-in default exclusion patterns (always applied): `__pycache__`, `*.pyc`, `.
 
 | Feature | ctxgraph | ctxgraph-code |
 |---------|----------|---------------|
-| CLI commands | 9 (build, capsule, query, view, serve, info, init, ask, chat, history, skill) | 9 (init, build, query, deps, usedby, overview, symbols, context, setup, view, info) |
+| CLI commands | 9+ | 16 (init, build, query, deps, usedby, overview, symbols, context, setup, view, info, install-slash, build-status, probe, install-hooks, uninstall-hooks) |
 | 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) |

{ctxgraph_code-0.2.1 → ctxgraph_code-0.4.0}/README.md

@@ -1,6 +1,6 @@
 # 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.
+**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
@@ -53,15 +53,23 @@ Interactive walkthrough — prompts for:
 
 Does everything in one step:
 1. Creates `.ctxgraph/config.toml` with your chosen extensions and excludes
-2. Builds the knowledge graph from all matching files
-3. Creates `.claude/commands/ctxgraph-code.md` with instructions for Claude Code
+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 (skip prompts):
+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
@@ -80,24 +88,27 @@ 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`).
 
-- **Imports**: which files import other files
-- **Class definitions**: class names, base classes, methods
-- **Function definitions**: function names, arguments
-- **Function calls**: which functions call which (within the project)
-- **Docstrings**: extracted as node summaries
+**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 the result in `.ctxgraph/graph.db`.
+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. Claude Code will also rebuild when it detects the graph is stale.
+> 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.
+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`
 
@@ -105,7 +116,7 @@ Searches the graph by relevance scoring (name matches > summary matches > path m
 ctxgraph-code deps src/api/routes.py
 ```
 
-Shows all relationships for a file: imports, imported-by, function calls, class definitions.
+Shows all relationships for a file: imports, imported-by, function calls, class definitions. Auto-detects the per-directory graph from the file path.
 
 ### `usedby`
 
@@ -119,9 +130,10 @@ Shows every file that imports or calls something in the given file. Useful to un
 
 ```bash
 ctxgraph-code overview
+ctxgraph-code overview --dir src
 ```
 
-Prints the project structure: every file with its summary and top-level symbols.
+Prints the project structure: every file with its summary and top-level symbols. Use `--dir` to scope to a per-directory graph.
 
 ### `symbols`
 
@@ -158,10 +170,59 @@ Use `--tree` for a terminal-friendly text view of the directory hierarchy with s
 
 ```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 40 lines of matched files with syntax highlighting.
+
+- `--max` / `-m` — max files to probe (default: 5)
+- `--context` / `-c` — lines of context around matches (default: 3)
+
+### `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
@@ -169,10 +230,10 @@ Shows graph statistics: node/edge counts, type distribution, build time.
 ```
 Python files  ──AST──>  Import/Symbol/Call analysis  ──>  SQLite graph.db
                                                                │
-Claude Code  ──/ctxgraph-code──>  CLI query/deps/overview  <────┘
+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.
+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.
 
@@ -181,8 +242,13 @@ Claude Code  ──/ctxgraph-code──>  CLI query/deps/overview  <────
 | 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 |
+| `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 |
 |--------------|---------|
@@ -190,8 +256,19 @@ Claude Code  ──/ctxgraph-code──>  CLI query/deps/overview  <────
 | `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`
+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
 
@@ -203,25 +280,47 @@ Edge weights: `imports=1.0`, `defines=1.0`, `extends=0.8`, `calls=0.7`
 
 ---
 
-## Using with Claude Code
+## 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 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 |
+| **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 |
 
-After `ctxgraph-code setup`, Claude Code in the project directory will have the `/ctxgraph-code` slash command available.
+---
+
+## Using with Claude Code
 
-When you type `/ctxgraph-code`, Claude sees:
+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
 
-This project has a knowledge graph at `.ctxgraph/graph.db`.
-The graph knows about imports, class hierarchies, and function calls.
-
-Available commands:
-- ctxgraph-code query "search 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              -- Show the full project structure
-- ctxgraph-code symbols <path>        -- List classes/functions defined in a file
-- ctxgraph-code context "task"        -- Generate a focused context summary
+**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.
@@ -264,7 +363,7 @@ Built-in default exclusion patterns (always applied): `__pycache__`, `*.pyc`, `.
 
 | Feature | ctxgraph | ctxgraph-code |
 |---------|----------|---------------|
-| CLI commands | 9 (build, capsule, query, view, serve, info, init, ask, chat, history, skill) | 9 (init, build, query, deps, usedby, overview, symbols, context, setup, view, info) |
+| CLI commands | 9+ | 16 (init, build, query, deps, usedby, overview, symbols, context, setup, view, info, install-slash, build-status, probe, install-hooks, uninstall-hooks) |
 | 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) |

{ctxgraph_code-0.2.1 → ctxgraph_code-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ctxgraph-code"
-version = "0.2.1"
+version = "0.4.0"
 description = "Code knowledge graph for Claude Code. Build a relationship graph of your Python codebase and query it during coding sessions."
 readme = "README.md"
 license = {text = "MIT"}

ctxgraph_code-0.4.0/src/ctxgraph_code/__init__.py

@@ -0,0 +1 @@
+

ctxgraph_code-0.4.0/src/ctxgraph_code/analyzers/treesitter/__init__.py

@@ -0,0 +1,4 @@
+from __future__ import annotations
+
+from .languages import EXTENSION_LANG, LANG_QUERIES  # noqa: F401
+from .analyzer import TSAnalyzer, TSAnalyzerResult  # noqa: F401