Metadata-Version: 2.4
Name: dekko
Version: 0.20.0
Summary: Static code map generator: MAP.md + map.json for any repo, plus a Claude Code /map plugin
Project-URL: Homepage, https://github.com/aahlijia/dekko
Project-URL: Documentation, https://github.com/aahlijia/dekko#readme
Project-URL: Repository, https://github.com/aahlijia/dekko
Project-URL: Issues, https://github.com/aahlijia/dekko/issues
Project-URL: Changelog, https://github.com/aahlijia/dekko/blob/main/CHANGELOG.md
Author-email: Austin Ahlijian <aahlijia@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-coding,call-graph,claude-code,claude-code-plugin,code-analysis,code-map,code-navigation,codebase-indexing,dead-code-detection,developer-tools,llm-agents,mcp-server,model-context-protocol,repository-map,static-analysis,tree-sitter
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: pathspec>=0.12
Requires-Dist: tree-sitter-c>=0.23
Requires-Dist: tree-sitter-cpp>=0.23
Requires-Dist: tree-sitter-go>=0.23
Requires-Dist: tree-sitter-java>=0.23
Requires-Dist: tree-sitter-javascript>=0.23
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-rust>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter>=0.23
Provides-Extra: all
Requires-Dist: tree-sitter-language-pack>=0.6; extra == 'all'
Provides-Extra: tokenizer
Requires-Dist: tiktoken>=0.7; extra == 'tokenizer'
Description-Content-Type: text/markdown

# dekko

[![CI](https://github.com/aahlijia/dekko/actions/workflows/ci.yml/badge.svg)](https://github.com/aahlijia/dekko/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/dekko)](https://pypi.org/project/dekko/)
[![Downloads](https://static.pepy.tech/badge/dekko)](https://pepy.tech/project/dekko)
[![Python](https://img.shields.io/pypi/pyversions/dekko)](https://pypi.org/project/dekko/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

**dekko** is a fast, offline, dependency-free **static code map
generator** and **codebase indexer for LLM coding agents**. It scans a
repository with [tree-sitter](https://tree-sitter.github.io/) (no model
tokens spent parsing) and writes:

- **`MAP.md`** — a human-readable map: a per-directory overview, an
  embedded architecture diagram, load-bearing/orchestrator rankings,
  then every file's functions/methods with signatures, doc lines, and
  who calls and is called by whom.
- **`map.json`** — the same graph in machine-readable form.

On top of the map, dekko gives an agent a token-cheap way to answer
questions like "what does this file contain," "who calls this function,"
and "what do I need to safely change this" — without reading whole files.
It ships as a **CLI**, a **Claude Code `/map` plugin + MCP server**
([Model Context Protocol](https://modelcontextprotocol.io/)), and
works with **Cline** too.

## Why dekko?

Most agent workflows gather context by reading whole files or grepping
across a repo — expensive, and it throws away structure (who calls
what, what a function's fan-in/fan-out looks like). dekko instead
parses the repo once into a call graph and answers targeted questions
against it. Measured across 7 real, unmodified open-source repos
(Go, TypeScript, Java, Rust, Python/C++ — up to 14k files), dekko's
structured queries used **3x–200x fewer tokens** than the equivalent
`Read`/`Grep` workflow for the same task (repo orientation, outlining a
large file, tracing a symbol's callers/callees). See
[`benchmarks/real-world-repos/`](benchmarks/real-world-repos/README.md)
for the full per-task breakdown and methodology.

Compared to tag-index tools like `ctags`/`gtags`, dekko resolves actual
call edges (not just definitions), ranks files by load-bearing-ness,
and speaks directly to agents over MCP or the CLI — no editor plugin
required.

## Installation

```sh
uv tool install dekko     # or: pip install dekko / pipx install dekko
```

The default install bundles nine Tier-1 languages (Python, Rust, C, C++,
JavaScript, TypeScript/TSX, Go, Java) as offline grammar packages — no
network call at parse time. For ~55 additional languages (parsed
generically), add the extra:

```sh
pip install dekko[all]
```

Then add the `/map` command + MCP server to Claude Code:

```sh
dekko --claude-install     # restart Claude Code afterward
```

### From a local clone

```sh
git clone https://github.com/aahlijia/dekko.git
cd dekko
./install.sh               # installs the CLI and registers the plugin
```

### Uninstall

```sh
dekko --claude-uninstall   # remove the /map plugin (and its MCP server)
uv tool uninstall dekko    # or: pip uninstall dekko / pipx uninstall dekko
```

## Quick start

```sh
cd my-project
dekko map                  # writes .dekko/MAP.md + .dekko/map.json
dekko summary               # ~40-line digest: dirs, hotspots, entry points
```

`.dekko/` is git-ignored by default; the map regenerates on demand, so
you rarely need to run `dekko map` again by hand.

## Core CLI commands

```sh
dekko map                            # (re)generate the map
dekko map src                        # ...restricted to a subtree
dekko summary                        # repo digest: dirs, hotspots, entry points
dekko outline src/server.py          # a file's signatures + docs, no bodies
dekko query symbol run_map           # signature card: doc, location, fan-in/out
dekko query callers resolve --sites  # who calls resolve, with call sites
dekko query callees main             # what does main call?
dekko query uses Path                # who references the external name Path?
dekko context run_map --budget 1500  # minimal context pack for an edit
dekko workset                        # one bundle for your current change
dekko affected                       # test files impacted by your changes
dekko diff                           # symbols changed since the map's commit
dekko unused                         # symbols nothing calls (dead-code leads)
dekko export --format html           # interactive single-file browser
dekko status                         # is the map still fresh? (exit 0/1)
```

Symbol targets accept a bare `name`, `Class.method`, or a qualified
`file.py:name` — ambiguous names list their candidates instead of
guessing. Every read command takes `--json` for structured output and
regenerates a stale map automatically (`--no-regen` to fail instead).

Run `dekko <command> --help` for the full flag list, or see
`dekko --help` for every subcommand (`trace`, `stats`, `lean`, `note`,
`ledger`, `hooks`, `orient` cover more specialized workflows).

### Notes

Anchor a durable, committed note to a symbol — it shows up in
`query symbol` and `context` automatically:

```sh
dekko note add resolver.py:resolve "ambiguous calls are marked, never guessed"
dekko note list resolver.py:resolve
```

## Using the Claude Code plugin

```sh
/map            # map the whole repository
/map src/       # map a subtree only
```

`dekko --claude-install` wires up both the `/map` command and the MCP
server (see below); the plugin just runs the installed `dekko` CLI, so
install the package first.

## Using the MCP server

`dekko serve --mcp` speaks the Model Context Protocol over stdio
(newline-delimited JSON-RPC, no SDK dependency), so an agent can ask
"who calls X?" with a tool call instead of reading `MAP.md`. It exposes
13 tools:

| Tool | Backs |
| --- | --- |
| `query_symbol` | signature, doc, fan-in/out, notes |
| `get_callers` / `get_callees` | callers/callees, with call sites |
| `find_usages` | references to an external name |
| `get_context_pack` | a symbol's neighborhood, budget-capped |
| `outline` | a file's structure without bodies |
| `workset` | one bundle for a change (`rev` or `symbol`) |
| `summary` | repo digest |
| `impacted_tests` | test files impacted by changes |
| `add_note` / `list_notes` | symbol-anchored notes |
| `map_status` / `refresh_map` | freshness check / regenerate |

`dekko --claude-install` registers this automatically for Claude Code.
For a standalone registration: `dekko --mcp-install` (runs
`claude mcp add dekko -- dekko serve --mcp`).

**Note:** a running `dekko serve --mcp` process holds its code in memory
for its whole lifetime — restart it after any dekko upgrade or source
change, or its output can silently disagree with the CLI.

### Cline

```sh
dekko --cline-install      # merge dekko into cline_mcp_settings.json
dekko --cline-uninstall    # remove just the dekko entry
```

Cline has no plugin system, so only the MCP tools are available (no
`/map`-equivalent slash command). See `dekko --cline-install --help`
for scope/config overrides if auto-detection picks the wrong file.

## Language support

Tier 1 (full fidelity, offline): Python, Rust, C, C++, JavaScript,
TypeScript/TSX, Go, Java. Tier 2 (generic fallback — names and calls,
no types): everything else `tree-sitter-language-pack` supports (Ruby,
PHP, C#, Kotlin, Swift, Lua, and more), via `pip install dekko[all]`.

## Learn more

- [CHANGELOG.md](CHANGELOG.md) — per-version history
- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, testing, releasing
- [benchmarks/](benchmarks/) — token-efficiency measurements, including
  a 7-repo real-world comparison against a plain Read/Grep workflow
