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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxgraph-code
-Version: 0.2.1
+Version: 0.3.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
@@ -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,28 @@ 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.
+
 ---
 
 ## How It Works
@@ -192,7 +222,7 @@ 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.
@@ -226,25 +256,43 @@ Edge weights: `imports=1.0`, `defines=1.0`, `extends=0.8`, `calls=0.7`
 
 ---
 
-## Using with Claude Code
+## Performance
 
-After `ctxgraph-code setup`, Claude Code in the project directory will have the `/ctxgraph-code` slash command available.
+`ctxgraph-code` includes several optimizations for large codebases:
 
-When you type `/ctxgraph-code`, Claude sees:
+| 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
 
-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 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 +335,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+ | 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) |

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

@@ -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,28 @@ 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.
+
 ---
 
 ## How It Works
@@ -169,7 +199,7 @@ 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.
@@ -203,25 +233,43 @@ Edge weights: `imports=1.0`, `defines=1.0`, `extends=0.8`, `calls=0.7`
 
 ---
 
-## Using with Claude Code
+## Performance
 
-After `ctxgraph-code setup`, Claude Code in the project directory will have the `/ctxgraph-code` slash command available.
+`ctxgraph-code` includes several optimizations for large codebases:
 
-When you type `/ctxgraph-code`, Claude sees:
+| 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
 
-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 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 +312,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+ | 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) |

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ctxgraph-code"
-version = "0.2.1"
+version = "0.3.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"}