ctxgraph-code 0.1.0__py3-none-any.whl

ctxgraph_code-0.1.0.dist-info/METADATA

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: ctxgraph-code
+Version: 0.1.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
+Keywords: code-graph,knowledge-graph,claude-code,code-analysis,ctx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.9
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+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.
+
+```bash
+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
+
+```bash
+# 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)
+
+```bash
+ctxgraph-code setup
+```
+
+Does everything in one step:
+1. Creates `.ctxgraph/config.toml` with defaults
+2. Builds the knowledge graph from all Python files
+3. Creates `.claude/commands/ctxgraph-code.md` with instructions for Claude Code
+
+### `init`
+
+```bash
+ctxgraph-code init
+```
+
+Creates the `.ctxgraph/` directory with a default `config.toml`.
+
+### `build`
+
+```bash
+ctxgraph-code build
+ctxgraph-code build --exclude "tests/" --exclude "*.generated.py"
+```
+
+Scans all `*.py` files in the project, runs AST analysis:
+- **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
+
+Stores the result in `.ctxgraph/graph.db`.
+
+### `query`
+
+```bash
+ctxgraph-code query "user authentication"
+ctxgraph-code query "database connection" --max 20
+```
+
+Searches the graph by relevance scoring (name matches > summary matches > path matches) and expands to neighboring nodes via BFS up to depth 2.
+
+### `deps`
+
+```bash
+ctxgraph-code deps src/api/routes.py
+```
+
+Shows all relationships for a file: imports, imported-by, function calls, class definitions.
+
+### `usedby`
+
+```bash
+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`
+
+```bash
+ctxgraph-code overview
+```
+
+Prints the project structure: every file with its summary and top-level symbols.
+
+### `symbols`
+
+```bash
+ctxgraph-code symbols src/main.py
+```
+
+Lists all classes and functions defined in a file, with line numbers and docstring summaries.
+
+### `context`
+
+```bash
+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.
+
+### `info`
+
+```bash
+ctxgraph-code info
+```
+
+Shows graph statistics: node/edge counts, type distribution, build time.
+
+---
+
+## 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
+
+---
+
+## Using with Claude Code
+
+After `ctxgraph-code setup`, Claude Code in the project directory will have the `/ctxgraph-code` slash command available.
+
+When you type `/ctxgraph-code`, 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
+```
+
+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 by `init` or `setup`):
+
+```toml
+[graph]
+# Additional exclude patterns beyond defaults
+exclude = ["tests/", "examples/"]
+# Follow symlinks when scanning
+follow_symlinks = false
+# Skip files larger than this (MB)
+max_file_size_mb = 5
+```
+
+Default exclusion patterns: `__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](https://github.com/shashi3070/ctxgraph) designed specifically for Claude Code.
+
+| Feature | ctxgraph | ctxgraph-code |
+|---------|----------|---------------|
+| CLI commands | 9 (build, capsule, query, view, serve, info, init, ask, chat, history, skill) | 8 (init, build, query, deps, usedby, overview, symbols, context, setup, info) |
+| LLM integration | Built-in (Ollama, Claude, OpenAI, Azure) | None (delegates to Claude Code) |
+| Chat sessions | Yes | No |
+| Visualizer | D3.js HTML + SVG | No |
+| 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

ctxgraph_code-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+ctxgraph_code/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ctxgraph_code/__main__.py,sha256=AfV3Onj_9FoL9W8B5jOWOeIyYF2MwX6S4-wyF9U90wM,41
+ctxgraph_code/cli.py,sha256=Lkh_zqsHH24m_JDs2z-Fz9O3QvC6AybZuDitoMrncws,11265
+ctxgraph_code/render.py,sha256=iqJMzFzPxLoTINrO2qqqAisoOoP_f5p0wl1kZ9rDs7s,8477
+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=e7uGvszNqfGmvDc4wacYjoZq_KQsZ8FdYNF1-yU1NOM,4129
+ctxgraph_code/analyzers/python/semantic.py,sha256=i9SvvJ2u4QfoKk6vVFjj0H6xItTsxKgO1-w202ve5oM,2332
+ctxgraph_code/analyzers/python/symbols.py,sha256=Ny6IF3AgmFUChLNHZSVGaIc_vN_bLuaWxB85loC7ZMk,6027
+ctxgraph_code/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ctxgraph_code/config/init.py,sha256=Qzx0bEDDdkNjaB4NnKwzsw4BexPxuY5Zfm9DULnOCxE,314
+ctxgraph_code/config/settings.py,sha256=JXNKiiuXXrf9DVvW-jUIhkuXgQu1a5_Pn8A8V4m7okc,3484
+ctxgraph_code/exclude/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ctxgraph_code/exclude/patterns.py,sha256=_XOjELhH3f6M1WGswVvYzbio9oT_dqAhG6DmnCOpAEU,1597
+ctxgraph_code/graph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ctxgraph_code/graph/builder.py,sha256=JFrD6EV-o_rwXJ9nWtpj9QM4so1mBarAVxAP9sO1gj8,2453
+ctxgraph_code/graph/models.py,sha256=JTgvfK8K2-F-7RPmdQrCq1RP0E4bBVeI2jRFqHqyiTI,2296
+ctxgraph_code/graph/query.py,sha256=qwGIdmTZ7-csL_FMkIdABfwpUCQ1ph9TbDeE3eY_YSU,3414
+ctxgraph_code/graph/storage.py,sha256=BMhcbybFP_hZv58WQTgR1SBldgFPWTuvk6im70MBMpU,7007
+ctxgraph_code-0.1.0.dist-info/METADATA,sha256=_dcW2swrhbKvlfwi9bfOlPA1h5H6xSTvP9tsETKwBnk,9530
+ctxgraph_code-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ctxgraph_code-0.1.0.dist-info/entry_points.txt,sha256=Q6poS8LApu1uGl_T9hjoZ7VMC8-iXZFCMslDx6OjlRo,56
+ctxgraph_code-0.1.0.dist-info/top_level.txt,sha256=ZOmow7lPtFHkcRJhLFOP5DVbt_SVaFrzsgXsawzMsq8,14
+ctxgraph_code-0.1.0.dist-info/RECORD,,

ctxgraph_code-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ctxgraph_code-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ctxgraph-code = ctxgraph_code.cli:app

ctxgraph_code-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ctxgraph_code