cartographing-kitties

Cartographing Kittens

AST-powered codebase intelligence for AI coding agents.

Cartographing Kittens parses your code with tree-sitter, builds a structural graph in SQLite, and exposes it as an MCP 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 Cartographing Kittens-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 kitty

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

Manual installation (MCP server only)

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

pip install cartographing-kittens
# or
uvx cartographing-kittens

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

{
  "mcpServers": {
    "kitty": {
      "command": "uvx",
      "args": ["cartographing-kittens"],
      "env": {
        "KITTY_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
kitty	Any structural/relational question about code	Routes to the right sub-skill based on your question
kitty:explore	"What's in this file?", "How is this organized?"	Browse definitions, imports, relationships through graph traversal
kitty:impact	"What depends on X?", "What breaks if I change Y?"	Blast radius analysis with transitive dependency walking
kitty: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 Cartographing Kittens-powered agent swarms.

Skill	Trigger	What it does
kitty:brainstorm	"Let's brainstorm", "What should we build?"	Requirements gathering with parallel research agents exploring the codebase
kitty:plan	"Plan this", "How should we build this?"	Technical planning with 4 research agents analyzing patterns, dependencies, and impact
kitty:work	"Build this", "Implement the plan"	Execute plans with Cartographing Kittens-first worker swarms — each worker understands code structure before implementing
kitty:review	"Review this", "Check my code"	Multi-agent review with structural impact analysis, correctness checks, and test coverage validation
kitty: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 kitty router skill picks the right approach:

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

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

You: Find all authentication-related code
→ Cartographing Kittens 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)

/kitty:brainstorm Add rate limiting to the API

Dispatches librarian-kitten-researcher and librarian-kitten-pattern in parallel to understand your codebase, then asks targeted questions to refine requirements. Produces a requirements document.

Step 2: Plan

/kitty:plan Add rate limiting to the API

Dispatches 4 research agents in parallel:

• librarian-kitten-researcher — understands architecture and technology
• librarian-kitten-pattern — finds existing patterns to follow
• librarian-kitten-flow — traces call chains in the affected area
• librarian-kitten-impact — assesses blast radius of proposed changes

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

Step 3: Work

/kitty:work

Executes the plan with Cartographing Kittens-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