ctxgraph-code 0.6.0__py3-none-any.whl → 0.6.2__py3-none-any.whl

ctxgraph_code/cli.py

@@ -254,29 +254,22 @@ def _write_slash_command(slash_path: Path, path: Path):
 
 SLASH_COMMAND_TEMPLATE = """# ctxgraph-code: Code Relationship Graph
 
-**First time in this project?** Tell the user to run `ctxgraph-code setup` in their terminal.
-
-**Graph needs refresh?** Tell the user to run `ctxgraph-code build`.
-
 **Available graphs:** {available}
 
 **Commands:**
-- `ctxgraph-code query "terms"` -- Find relevant files, classes, and functions
-- `ctxgraph-code probe "question"` -- Search graph and read matching source code 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 subgraph "task"` -- Extract a focused subgraph with inline source for a task
-- `ctxgraph-code diff` -- Compare graph with filesystem to find new/removed/changed files
-- `ctxgraph-code mermaid --type classDiagram` -- Export graph as Mermaid diagram
-- `ctxgraph-code view --dir <name>` -- Visualize a graph interactively
-- `ctxgraph-code build-status` -- Show last build status and timing
-- `ctxgraph-code install-slash` -- (Re)install this slash command
-
-**Tip:** Use `--dir <name>` to scope queries to a per-directory graph.
-When passing a file path like `auth/login.py`, the correct graph is auto-detected.
+- `ctxgraph-code query "terms"` -- Files, classes, functions
+- `ctxgraph-code probe "question"` -- Search + read source inline
+- `ctxgraph-code deps <path>` -- Dependencies of a file
+- `ctxgraph-code usedby <path>` -- What depends on a file
+- `ctxgraph-code overview --dir <name>` -- Project structure
+- `ctxgraph-code symbols <path>` -- Classes/functions in a file
+- `ctxgraph-code context "task"` -- Focused context summary
+- `ctxgraph-code subgraph "task"` -- Focused subgraph with source
+- `ctxgraph-code diff` -- Files changed since build
+- `ctxgraph-code mermaid --type classDiagram` -- Mermaid diagram
+- `ctxgraph-code view --dir <name>` -- Interactive D3.js graph
+
+Use `--dir <name>` to scope queries. File paths auto-detect the graph dir.
 """
 
 
@@ -1110,7 +1103,7 @@ def version():
     try:
         ver = _v("ctxgraph-code")
     except Exception:
-        ver = "0.6.0"
+        ver = "0.6.2"
     console.print(f"ctxgraph-code version [bold]{ver}[/bold]")
 
 

ctxgraph_code/config/hooks.py

@@ -79,8 +79,6 @@ def uninstall_hooks(project_path: Path, local: bool = False) -> bool:
 
 
 def compute_hint_summary(repo_path: Path) -> Optional[str]:
-    import hashlib
-
     avail = get_available_graphs(repo_path)
     if not avail["_combined"] and not avail["dirs"]:
         return None
@@ -100,8 +98,6 @@ def compute_hint_summary(repo_path: Path) -> Optional[str]:
         total_edges = stats.get("edges", 0)
         types = stats.get("types", {})
 
-        top_files = _get_top_files(storage, 5)
-
         file_count = types.get("file", 0)
         class_count = types.get("class", 0)
         func_count = types.get("function", 0)
@@ -112,55 +108,11 @@ def compute_hint_summary(repo_path: Path) -> Optional[str]:
         ]
         if file_count:
             lines.append(f"Files: {file_count} | Classes: {class_count} | Functions: {func_count}.")
-        if top_files:
-            lines.append(f"Key files: {', '.join(top_files)}.")
-
-        # ── Tamper detection ──────────────────────────────────────
-        hashes_json = storage.get_metadata("content_hashes")
-        tampered: int = 0
-        if hashes_json:
-            try:
-                stored_hashes = json.loads(hashes_json)
-                for rel_path, stored_hash in stored_hashes.items():
-                    fp = repo_path / rel_path
-                    if not fp.is_file():
-                        tampered += 1
-                        continue
-                    try:
-                        actual = hashlib.sha256(
-                            fp.read_text(encoding="utf-8", errors="replace")
-                            .encode("utf-8")
-                        ).hexdigest()
-                        if actual != stored_hash:
-                            tampered += 1
-                    except OSError:
-                        tampered += 1
-            except (json.JSONDecodeError, OSError):
-                pass
-        if tampered:
-            lines.append(
-                f"Warning: {tampered} file(s) have changed since graph was built. "
-                "Run `ctxgraph-code build --incremental` to update."
-            )
 
         lines.append(
-            "Use `ctxgraph-code probe \"<question>\"`, "
-            "`ctxgraph-code subgraph \"<task>\"`, or "
-            "`/ctxgraph-code` for help."
+            "Use `ctxgraph-code probe` or `/ctxgraph-code` for help."
         )
 
         return "\n".join(lines)
     finally:
         storage.close()
-
-
-def _get_top_files(storage, limit: int = 5) -> list[str]:
-    try:
-        rows = storage.conn.execute(
-            "SELECT path FROM nodes WHERE type = 'file' AND path IS NOT NULL "
-            "ORDER BY size_bytes DESC LIMIT ?",
-            (limit,),
-        ).fetchall()
-        return [r[0] for r in rows if r[0]]
-    except Exception:
-        return []

{ctxgraph_code-0.6.0.dist-info → ctxgraph_code-0.6.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxgraph-code
-Version: 0.6.0
+Version: 0.6.2
 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
@@ -26,7 +26,13 @@ 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.
+**How do we give AI the right context without sending the entire codebase every time?**
+
+`ctxgraph-code` answers that question. Instead of dumping files into the context window, it builds a **relationship graph** of your codebase using static AST analysis, stores it in a local SQLite database, and retrieves only the relevant symbols and dependencies when Claude Code needs to understand your code.
+
+**Result:** One codebase question drops from ~25,000 tokens to ~800 tokens — a **95% reduction** in context usage. A full 30-question benchmark showed **90% fewer tokens** than traditional file reading, and **16% fewer than graph-based alternatives**.
+
+![Product Overview](https://raw.githubusercontent.com/shashi3070/ctxgraph-code/master/docs/benchmark2.jpg)
 
 ```bash
 pip install ctxgraph-code
@@ -67,6 +73,29 @@ ctxgraph-code setup
 #   /ctxgraph-code
 ```
 
+## How It Works (At a Glance)
+
+```
+Your Codebase
+     │
+     ▼
+1. Static AST Analysis ──► Extract imports, classes, functions, calls, relationships
+     │
+     ▼
+2. Knowledge Graph ──► Store everything in local SQLite (files, symbols, edges)
+     │
+     ▼
+3. Query Engine ──► Search graph by relevance, expand to neighbors via BFS
+     │
+     ▼
+4. Context Retrieval ──► Only the relevant snippets, not whole files
+     │
+     ▼
+5. Claude Code ──► Receives focused context → Better answers, fewer tokens, less noise
+```
+
+No huge graph-building prompts sent to the LLM. The graph is built locally with Python's AST parser — zero LLM calls, zero API costs.
+
 ## Commands
 
 ### `setup` (recommended)
@@ -113,6 +142,37 @@ ctxgraph-code init
 
 Creates the `.ctxgraph/` directory with a default `config.toml`.
 
+### `subgraph`
+
+```bash
+ctxgraph-code subgraph "add pagination to the users endpoint"
+```
+
+Extracts a **focused subgraph** relevant to a task description — returns matching nodes, their relationships, and inline source code in a single compact response. Saves 1-2 tool calls by combining graph search, dependency resolution, and file reading.
+
+- `--max-nodes` / `-n` — max nodes in subgraph (default: 10)
+
+### `diff`
+
+```bash
+ctxgraph-code diff
+ctxgraph-code diff --ref main
+```
+
+Compares the graph with the filesystem. Shows files that have been **added, removed, or changed** since the graph was built. Use `--ref` for a git-aware diff against a branch. Essential for knowing when to run `ctxgraph-code build --incremental`.
+
+### `mermaid`
+
+```bash
+ctxgraph-code mermaid classDiagram
+ctxgraph-code mermaid flowchart --output diagram.md
+```
+
+Exports the graph as a **Mermaid diagram** for embedding in documentation or PRs. Supported types: `classDiagram`, `flowchart`, `sequence`.
+
+- `--output` / `-o` — save to file instead of stdout
+- `--max-nodes` / `-n` — maximum nodes in diagram (default: 50)
+
 ### `build`
 
 ```bash
@@ -348,6 +408,105 @@ This catches the common case where you edit a file after building the graph and
 
 ---
 
+## Benchmark Results
+
+Real-world benchmarks against a production Python/UI codebase. Three approaches compared across 30 code understanding questions.
+
+### Repository Profile
+
+| Metric | Value |
+|---|---|
+| Backend Python LOC | 45,570 |
+| UI Source LOC | 37,317 |
+| Documentation LOC | 9,120 |
+| Source Files | 143 |
+| Raw Tokens | ~140,000 |
+
+### Three Retrieval Methods Compared
+
+| Approach | How It Works |
+|---|---|
+| **Baseline** (File Reading) | `grep` → read entire files → answer. Every question repeatedly loads large source files. |
+| **Graphify** (Knowledge Graph) | Build full graph → compressed node summaries → answer. Incurs large upfront graph-building cost. |
+| **CtxGraph-Code** (Symbol Graph) | Local AST → SQLite symbol graph → retrieve only relevant files → answer. Only targeted files opened. |
+
+### Combined Results (30 Questions)
+
+| Approach | Total Tokens | Avg/Question | Reduction |
+|---|---|---|---|
+| Baseline (File Reading) | 203,590 | 6,786 | — |
+| Graphify | 25,100 | 837 | 88% |
+| **CtxGraph-Code** | **21,120** | **704** | **90%** |
+
+CtxGraph-Code is **9.6× more efficient** than reading raw files, and uses **16% fewer tokens** than Graphify.
+
+![Benchmark Comparison](https://raw.githubusercontent.com/shashi3070/ctxgraph-code/master/docs/Benchmark%20Vs%20Graphify.jpg)
+
+### Per-Suite Breakdown
+
+| Suite | Baseline | Graphify | CtxGraph-Code | Winner |
+|---|---|---|---|---|
+| BM1: Architecture | 73,500 | 12,100 | 10,150 | CtxGraph-Code |
+| BM2: Data Flow & UI Logic | 130,090 | 13,000 | 10,970 | CtxGraph-Code |
+| **Combined** | **203,590** | **25,100** | **21,120** | **CtxGraph-Code** |
+
+### Biggest Win: File Comparison
+
+Question: *"How does tasks_fixed.py differ from tasks.py?"*
+
+- `tasks.py`: 2,372 lines
+- `tasks_fixed.py`: 1,512 lines
+
+| Approach | Tokens |
+|---|---|
+| Baseline | 31,070 |
+| Graphify | 1,400 |
+| **CtxGraph-Code** | **1,150 (96% savings)** |
+
+Instead of reading both files completely, CtxGraph-Code compares symbols and retrieves only relevant differences.
+
+### Context Window Longevity
+
+With a 200K token context window:
+
+| Approach | Tokens/Question | Questions Before Exhaustion |
+|---|---|---|
+| Baseline | 6,786 | ~29 |
+| Graphify | 837 | ~239 |
+| **CtxGraph-Code** | **704** | **~284 (10× longer sessions)** |
+
+### Graphify vs CtxGraph-Code: Detailed Comparison
+
+![Phase-by-Phase Comparison](https://raw.githubusercontent.com/shashi3070/ctxgraph-code/master/docs/Benchmark%20Vs%20Graphify.jpg)
+
+| Metric | Graphify | CtxGraph-Code |
+|---|---|---|
+| **Build approach** | Full knowledge graph first | Local symbol graph via AST + SQLite |
+| **Upfront LLM cost** | ~141,728 input tokens | ~0 tokens (local AST parse, ~246s) |
+| **Total input tokens** | ~157,728 | ~22,500 (**85.7% fewer**) |
+| **Output tokens** | ~12,000 | ~3,500 (**70.8% fewer**) |
+| **Query speed** | Moderate (BFS/DFS traversal) | Fast (SQLite indexed lookup) |
+| **Strengths** | Architecture visualization, community detection, cross-file relationship discovery | Inline source retrieval, indexed search, symbol resolution, implementation-focused answers |
+| **Weaknesses** | No implementation snippets; often requires opening source files after | Less visualization; relationship discovery less deep |
+| **Best for** | Architecture discovery, planning, cross-cutting concerns | Code navigation, execution flow, symbol lookup, implementation questions |
+
+**Bottom line:** Use CtxGraph-Code for fast code search and implementation answers. Use Graphify when you need architecture visualization and cross-file relationship discovery.
+
+### Real-World Example Results
+
+| Question | Without | With CtxGraph-Code | Savings |
+|---|---|---|---|
+| Learning Mode | 9,498 | 3,267 | 66% |
+| Planner Node | 13,166 | 7,043 | 47% |
+| Dashboard Embedding | 5,180 | 2,840 | 45% |
+| Authentication | 9,498 | 3,267 | 66% |
+| Deep Learning Mode | 25,000 | 800 | 95% |
+| **Overall (30 questions)** | **203,590** | **21,120** | **90%** |
+
+![Detailed Benchmark Results](https://raw.githubusercontent.com/shashi3070/ctxgraph-code/master/docs/benchmark1.jpg)
+
+---
+
 ## 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:
@@ -367,6 +526,9 @@ After `ctxgraph-code setup`, the `/ctxgraph-code` slash command is installed glo
 - `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 subgraph "task"` -- Focused subgraph with inline source
+- `ctxgraph-code diff` -- Files changed since build
+- `ctxgraph-code mermaid --type classDiagram` -- Export as Mermaid diagram
 - `ctxgraph-code view --dir <name>` -- Visualize a graph interactively
 ```
 
@@ -404,13 +566,30 @@ Built-in default exclusion patterns (always applied): `__pycache__`, `*.pyc`, `.
 
 ---
 
+## Where It Helps
+
+`ctxgraph-code` delivers the most value when working with **existing codebases built over months or years**:
+
+| Helps Most | Helps Less |
+|---|---|
+| 🐛 Debugging production issues | Tiny projects (2–3 files) |
+| 🏗 Understanding architecture | Throwaway scripts |
+| 🔍 Tracing dependencies | Greenfield projects created entirely in the same Claude session |
+| 🔄 Safe refactoring | Short experiments |
+| 📚 Onboarding into large existing codebases | |
+| 🧩 Multi-module repositories | |
+
+The biggest gains come when AI needs to understand **existing code written over months or years**, not when starting from scratch.
+
+---
+
 ## 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) |
+| CLI commands | 9+ | 20 (init, build, query, deps, usedby, overview, symbols, context, subgraph, diff, mermaid, 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) |

{ctxgraph_code-0.6.0.dist-info → ctxgraph_code-0.6.2.dist-info}/RECORD

@@ -1,6 +1,6 @@
 ctxgraph_code/__init__.py,sha256=8Bo3TpyB49uJs6QpQMTWpUR2hJhqEpbkK_E_GW7tYpU,5
 ctxgraph_code/__main__.py,sha256=AfV3Onj_9FoL9W8B5jOWOeIyYF2MwX6S4-wyF9U90wM,41
-ctxgraph_code/cli.py,sha256=N2-39jCTs_P3yRVhWTN6jRFbTaQ68c5QTpYpPfAGEB4,52164
+ctxgraph_code/cli.py,sha256=Tlx5FWctV_fPtzQ5lXXWx75lE5CrchvIiDFcNotK9fk,51574
 ctxgraph_code/analyzers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ctxgraph_code/analyzers/python/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ctxgraph_code/analyzers/python/importer.py,sha256=_5WV-RHK9IzbjCaVi_-1rWCYSuJIu0jHj5bW4uPQViY,4688
@@ -12,7 +12,7 @@ ctxgraph_code/analyzers/treesitter/languages.py,sha256=fnX9KEXYQUfHZcmW46Fi6Y4jL
 ctxgraph_code/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ctxgraph_code/config/build_status.py,sha256=e2tdNc34oJd-iDAi4aFEi-TkY9lIhkicCjmSj6VpvHY,2754
 ctxgraph_code/config/global_paths.py,sha256=amCTdTiaNcB-0P4LHtl6yaHv84ReXpOtCsb2ofIR-9M,183
-ctxgraph_code/config/hooks.py,sha256=hqQKCexlXsmXa_MOXJZoJEpbwmsJNo0_cOJ0-sQJsro,5198
+ctxgraph_code/config/hooks.py,sha256=vvPMztr5heNY4haLj386yq1tNE7A9wX8JHpIuY6BWis,3354
 ctxgraph_code/config/init.py,sha256=tXVcDTPAJGVbzPavABRfnCXUsf9Pt-VzDUgV5YX09Tc,501
 ctxgraph_code/config/settings.py,sha256=H_-8UtIX2GwN-BCpg-fusoghhaZHFjkE1HSe2AcwxkM,5302
 ctxgraph_code/exclude/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -27,8 +27,8 @@ ctxgraph_code/render/_text.py,sha256=zic5X5gKfuqZSL0sAxsAOCkZcHnac0eta2FXO_DNaHQ
 ctxgraph_code/render/mermaid.py,sha256=5TE4wdBBBgK_GRHri48Z0k6_17jtnMKKvyKXGLC0L8M,4719
 ctxgraph_code/view/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ctxgraph_code/view/visualizer.py,sha256=xvPn9eSDYAk_HICpL6Nt7CQ_5FOKX0EXpZGM6wwyv9s,10555
-ctxgraph_code-0.6.0.dist-info/METADATA,sha256=DGgXYp6Uu5L44pQTT1NG1MyA4_Gu5awGEQ9jW16KbhM,18040
-ctxgraph_code-0.6.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-ctxgraph_code-0.6.0.dist-info/entry_points.txt,sha256=Q6poS8LApu1uGl_T9hjoZ7VMC8-iXZFCMslDx6OjlRo,56
-ctxgraph_code-0.6.0.dist-info/top_level.txt,sha256=ZOmow7lPtFHkcRJhLFOP5DVbt_SVaFrzsgXsawzMsq8,14
-ctxgraph_code-0.6.0.dist-info/RECORD,,
+ctxgraph_code-0.6.2.dist-info/METADATA,sha256=Pf50A0tVNBznh3DVaVphbwRMSzYXEy3vwVs283-CmfI,25511
+ctxgraph_code-0.6.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ctxgraph_code-0.6.2.dist-info/entry_points.txt,sha256=Q6poS8LApu1uGl_T9hjoZ7VMC8-iXZFCMslDx6OjlRo,56
+ctxgraph_code-0.6.2.dist-info/top_level.txt,sha256=ZOmow7lPtFHkcRJhLFOP5DVbt_SVaFrzsgXsawzMsq8,14
+ctxgraph_code-0.6.2.dist-info/RECORD,,