Kitzune

AI-powered documentation generator that helps AI assistants understand your codebase.

Kitzune scans your JS/TS project, extracts business logic, gotchas, and function relationships using Claude, and serves them via MCP (Model Context Protocol) so AI coding assistants actually understand your code.

Why Kitzune?

Regular code search (grep) tells you where things are. Kitzune tells you why they exist and what can go wrong.

# Without Kitzune
AI: "executeTransfer is in src/server/services/transfer.ts"

# With Kitzune
AI: "executeTransfer uses two-phase commit with optimistic locking.
     Watch out: version conflicts fail silently - callers must implement retry logic.
     Fee tiers must be sorted highest-to-lowest or calculations break."

Quick Start

# Install
npm install -g kitzune

# Set your Anthropic API key
export ANTHROPIC_API_KEY=your-key-here

# Generate documentation for your project
cd your-project
kitzune setup

# Start MCP server for AI assistants
kitzune serve

Commands

kitzune setup

Scans and documents all JS/TS files in your project.

kitzune setup [options]

Options:
  -t, --target <path>    Target directory (default: current directory)
  -s, --skip-unchanged   Skip files that haven't changed since last run
  -v, --verbose          Show detailed progress
  --estimate             Show cost estimate without running
  --dry-run              List files that would be indexed
  --yes                  Skip confirmation prompt

Output:

• .kitzune/docs/ - JSON documentation for each source file
• .kitzune/manifest.json - Hash tracking for change detection

kitzune serve

Starts an MCP server to serve documentation to AI assistants.

kitzune serve [options]

Options:
  -t, --target <path>    Target directory with .kitzune docs
  -v, --verbose          Enable debug logging

MCP Integration

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "kitzune": {
      "command": "npx",
      "args": ["kitzune", "serve"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "kitzune": {
      "command": "npx",
      "args": ["kitzune", "serve", "--target", "/path/to/your/project"]
    }
  }
}

MCP Tools

Once connected, AI assistants can use these tools:

| Tool | Description | |------|-------------| | get_file_doc | Get full documentation for a file | | search_functions | Search functions by name or purpose | | get_dependencies | See what a file imports and what imports it | | find_callers | Find all functions that call a specific function | | list_files | List all documented files with summaries | | get_business_logic | Get gotchas, edge cases, and business rules |

Configuration

Create kitzune.config.json in your project root:

{
  "ignore": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/__mocks__/**",
    "**/fixtures/**"
  ],
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx"
  ],
  "model": "claude-sonnet-4-20250514"
}

Options

| Option | Default | Description | |--------|---------|-------------| | ignore | [] | Glob patterns to exclude | | include | ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"] | Glob patterns to include | | model | claude-sonnet-4-20250514 | Claude model to use |

Cost

Kitzune uses the Claude API to generate documentation. Estimated costs:

| Model | Cost per file | 100 files | 500 files | |-------|--------------|-----------|-----------| | claude-sonnet-4-20250514 | ~$0.02 | ~$2 | ~$10 | | claude-3-haiku-20240307 | ~$0.002 | ~$0.20 | ~$1 |

Use --estimate to see cost before running:

kitzune setup --estimate
# Found 150 files to document
# Estimated cost: $3.00 - $4.50

Documentation Format

Each source file gets a JSON doc with:

{
  "file": "src/server/services/transfer.ts",
  "overview": "Implements atomic money transfers...",
  "runtime": "server",
  "functions": [
    {
      "name": "executeTransfer",
      "purpose": "Executes atomic transfer using two-phase commit...",
      "businessLogic": "Uses sorted lock acquisition to prevent deadlocks...",
      "calls": ["validateTransfer", "acquireLock"],
      "calledBy": ["handleCreateTransfer"]
    }
  ],
  "businessConsiderations": [
    "Version conflicts fail silently - callers must implement retry logic",
    "Fee tiers must be sorted highest-to-lowest"
  ]
}

How It Works

1. Scan - Find all JS/TS files using glob patterns
2. Parse - Extract AST structure with ts-morph (functions, classes, imports)
3. Analyze - Build dependency graph and detect runtime (client/server/shared)
4. Document - Send to Claude with structured prompt, get JSON documentation
5. Serve - MCP server provides tools for AI assistants to query docs

Requirements

• Node.js >= 18
• Anthropic API key

Contributing

Contributions welcome! Please read the contributing guidelines first.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT - see LICENSE for details.