Metadata-Version: 2.4
Name: cartographing-kittens
Version: 0.1.0
Summary: AST-powered codebase intelligence framework for AI coding agents
Project-URL: Repository, https://github.com/Kakise/cartographing-kittens
Author-email: Kakise <cartographing-kittens@a-smol-cat.fr>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.11
Requires-Dist: mcp>=1.0.0
Requires-Dist: tree-sitter-javascript>=0.25.0
Requires-Dist: tree-sitter-python>=0.25.0
Requires-Dist: tree-sitter-typescript>=0.23.0
Requires-Dist: tree-sitter>=0.25.0
Description-Content-Type: text/markdown

# Cartographing Kittens

AST-powered codebase intelligence for AI coding agents.

Cartograph parses your code with [tree-sitter](https://tree-sitter.github.io/tree-sitter/), builds a structural graph in SQLite, and exposes it as an [MCP](https://modelcontextprotocol.io/) server. It answers questions that grep can't: *what depends on this function?*, *what breaks if I change this class?*, *show me all the auth-related code*.

It is also a **Claude Code plugin** with a complete engineering workflow framework — brainstorm, plan, implement, and review code using Cartograph-powered agent swarms.

## Install as Claude Code Plugin

**Step 1 — Add the marketplace:**

```
/plugin marketplace add Kakise/cartographing-kitties-plugin
```

**Step 2 — Install the plugin:**

```
/plugin install cartograph
```

This installs the MCP server, all 9 skills, and all 9 agents. Cartograph tools become available immediately.

### Manual installation (MCP server only)

If you only want the MCP server without the plugin framework:

```bash
pip install cartographing-kittens
# or
uvx cartographing-kittens
```

Then add to your MCP client config (`.mcp.json`):

```json
{
  "mcpServers": {
    "cartograph": {
      "command": "uvx",
      "args": ["cartographing-kittens"],
      "env": {
        "CARTOGRAPH_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}
```

## Supported Languages

| Language   | Extensions         |
| ---------- | ------------------ |
| Python     | `.py`              |
| TypeScript | `.ts`, `.tsx`      |
| JavaScript | `.js`, `.jsx`      |

## Skills

### Tool Skills — Direct Codebase Intelligence

Use these skills when you need specific structural information from the codebase.

| Skill | Trigger | What it does |
|-------|---------|--------------|
| `cartograph` | Any structural/relational question about code | Routes to the right sub-skill based on your question |
| `cartograph:explore` | "What's in this file?", "How is this organized?" | Browse definitions, imports, relationships through graph traversal |
| `cartograph:impact` | "What depends on X?", "What breaks if I change Y?" | Blast radius analysis with transitive dependency walking |
| `cartograph:annotate` | "Enable semantic search", "Annotate the codebase" | Enrich graph nodes with summaries and domain tags |

### Workflow Skills — Engineering Pipeline

Use these skills to go from idea to shipped code with Cartograph-powered agent swarms.

| Skill | Trigger | What it does |
|-------|---------|--------------|
| `cartograph:brainstorm` | "Let's brainstorm", "What should we build?" | Requirements gathering with parallel research agents exploring the codebase |
| `cartograph:plan` | "Plan this", "How should we build this?" | Technical planning with 4 research agents analyzing patterns, dependencies, and impact |
| `cartograph:work` | "Build this", "Implement the plan" | Execute plans with Cartograph-first worker swarms — each worker understands code structure before implementing |
| `cartograph:review` | "Review this", "Check my code" | Multi-agent review with structural impact analysis, correctness checks, and test coverage validation |
| `cartograph:lfg` | Full autonomous mode | Chains plan, work, and review without interaction |

## How to Use the Framework

### Quick start — Explore a codebase

Just ask a structural question. The `cartograph` router skill picks the right approach:

```
You: What depends on the UserService class?
→ Cartograph uses find_dependents to show all callers, importers, and subclasses

You: How is the API module organized?
→ Cartograph uses get_file_structure to show all definitions and relationships

You: Find all authentication-related code
→ Cartograph uses search (after annotation) for semantic discovery
```

### Build a feature — Full pipeline

The recommended workflow for building features:

**Step 1: Brainstorm** (optional but recommended for ambiguous features)
```
/cartograph:brainstorm Add rate limiting to the API
```
Dispatches `cartograph-researcher` and `cartograph-pattern-analyst` in parallel to understand your codebase, then asks targeted questions to refine requirements. Produces a requirements document.

**Step 2: Plan**
```
/cartograph:plan Add rate limiting to the API
```
Dispatches 4 research agents in parallel:
- **cartograph-researcher** — understands architecture and technology
- **cartograph-pattern-analyst** — finds existing patterns to follow
- **cartograph-flow-analyzer** — traces call chains in the affected area
- **cartograph-impact-analyst** — assesses blast radius of proposed changes

Produces an implementation plan with ordered units, test scenarios, and file paths.

**Step 3: Work**
```
/cartograph:work
```
Executes the plan with Cartograph-first worker agents. Each worker:
1. Calls `get_file_structure` and `query_node` on target files
2. Reads existing patterns
3. Implements following codebase conventions
4. Writes tests and verifies

For 3+ independent tasks, workers run as a **parallel swarm**.

**Step 4: Review**
```
/cartograph:review
```
Dispatches review agents in parallel:
- **cartograph-correctness-reviewer** (always-on) — logic errors, edge cases
- **cartograph-testing-reviewer** (always-on) — test coverage via dependency graph
- **cartograph-impact-reviewer** (conditional) — blast radius of changes
- **cartograph-structure-reviewer** (conditional) — architectural consistency

Findings are merged, deduplicated, and presented by severity (P0-P3).

### Full autonomous mode

Skip all interaction and let Cartograph handle everything:

```
/cartograph:lfg Add rate limiting to the API
```

This chains plan, work, and review automatically with agent swarms at every step.

### Best Practices

1. **Index first** — Run `index_codebase` at the start of a conversation if you're unsure about graph freshness. All workflow skills do this automatically.

2. **Annotate for semantic search** — `search` works on node names by default. Run `cartograph:annotate` to add summaries and tags for domain queries like "find auth code".

3. **Use impact analysis before changes** — Before modifying shared code, run `cartograph:impact` or ask "what depends on X?" to understand the blast radius.

4. **Let swarms do the work** — Workflow skills dispatch agents in parallel automatically. For large features, `cartograph:work` runs independent implementation units simultaneously.

5. **Review with structure** — `cartograph:review` finds issues that text-based reviews miss: unupdated dependents, broken contracts, circular dependencies, test coverage gaps.

## Agents

### Research Agents

Dispatched by `cartograph:brainstorm` and `cartograph:plan` for codebase understanding.

| Agent | Purpose |
|-------|---------|
| `cartograph-researcher` | General codebase exploration — architecture, stack, modules, relationships |
| `cartograph-pattern-analyst` | Find existing patterns and conventions to follow |
| `cartograph-impact-analyst` | Blast radius and dependency chain analysis |
| `cartograph-flow-analyzer` | Trace call chains and data flow through the graph |

### Review Agents

Dispatched by `cartograph:review` for structural code review.

| Agent | When | Purpose |
|-------|------|---------|
| `cartograph-correctness-reviewer` | Always | Logic errors, edge cases, state bugs |
| `cartograph-testing-reviewer` | Always | Test coverage gaps via dependency graph |
| `cartograph-impact-reviewer` | 3+ files changed | Blast radius — unreviewed downstream effects |
| `cartograph-structure-reviewer` | New files created | Naming, architecture, import hygiene |

### Annotation Agent

| Agent | Purpose |
|-------|---------|
| `cartograph-annotator` | Batch annotation specialist — processes nodes with summaries, tags, and roles |

## MCP Tools

### Indexing

| Tool | Description |
|------|-------------|
| `index_codebase` | Parse code and build/update the graph. `full=true` for complete reindex, `full=false` for incremental. |
| `annotation_status` | Returns counts of pending, annotated, and failed nodes. |

### Search & Exploration

| Tool | Description |
|------|-------------|
| `query_node` | Look up a symbol by name. Returns the node with immediate neighbors. |
| `search` | Full-text search across names and summaries. Filter by `kind`. |
| `get_file_structure` | List all definitions in a file with relationships. |

### Dependency Analysis

| Tool | Description |
|------|-------------|
| `find_dependencies` | What does X depend on? Transitive traversal up to `max_depth` hops. |
| `find_dependents` | What depends on X? Impact analysis for change planning. |

### Annotation

| Tool | Description |
|------|-------------|
| `get_pending_annotations` | Get nodes needing annotation, with source code context. |
| `submit_annotations` | Write summaries, tags, and roles back to the graph. |

## MCP Prompts

Guided workflows that MCP clients can invoke directly:

| Prompt | Purpose |
|--------|---------|
| `explore_codebase(focus?)` | Step-by-step codebase exploration |
| `plan_refactor(target)` | Guided refactoring with blast radius analysis |
| `annotate_batch(batch_size?)` | Batch annotation workflow |

## How It Works

Cartograph builds a knowledge graph in three phases:

**Phase 1 — Parse.** Each source file is parsed with tree-sitter. The extractor walks the AST and emits `Definition`, `Import`, and `CallSite` objects.

**Phase 2 — Resolve imports.** Import statements are resolved to target files and definitions. Python module paths are converted to file paths; TypeScript/JS relative imports are resolved with extension fallback.

**Phase 3 — Resolve calls.** Call sites are matched to definitions using four strategies: `self.method()`, `imported_name()`, `qualifier.method()`, and `local_function()`.

### Graph conventions

- **Qualified names** use `::` separator: `module.path::ClassName::method_name`
- **Edge kinds**: `imports`, `calls`, `inherits`, `contains`, `depends_on`
- **Node kinds**: `module`, `class`, `function`, `method`, `variable`
- Graph stored at `.cartograph/graph.db` in the project root

## Development

```bash
git clone https://github.com/Kakise/cartographing-kittens.git
cd cartographing-kittens
uv sync
```

```bash
uv run pytest              # Tests
uv run ruff check .        # Lint
uv run ruff format --check # Format check
uv run basedpyright        # Type check
uv run codespell src tests # Spell check
```

## License

MIT
