dekko

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/aahlijia/dekko/main/assets/logo-full-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/aahlijia/dekko/main/assets/logo-full-light.svg">
    <img src="https://raw.githubusercontent.com/aahlijia/dekko/main/assets/logo-full-light.svg" alt="dekko" width="460">
  </picture>
</p>

<p align="center">
  <a href="https://github.com/aahlijia/dekko/actions/workflows/ci.yml"><img src="https://github.com/aahlijia/dekko/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/dekko/"><img src="https://img.shields.io/pypi/v/dekko" alt="PyPI"></a>
  <a href="https://pepy.tech/project/dekko"><img src="https://static.pepy.tech/badge/dekko" alt="Downloads"></a>
  <a href="https://pypi.org/project/dekko/"><img src="https://img.shields.io/pypi/pyversions/dekko" alt="Python"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
</p>

<!-- mcp-name: io.github.aahlijia/dekko -->

Ever watched your coding agent grep blind through a repo, open three
files it didn't need, and burn fifteen thousand tokens just to answer
"who calls this function"? That's the problem dekko exists to fix.

<p align="center">
  <img src="https://raw.githubusercontent.com/aahlijia/dekko/main/assets/demo.gif" alt="dekko demo: mapping a repo and querying a symbol in seconds" width="720">
</p>
<p align="center">
  <sub>This demo runs on dekko's own repo (commit <code>835733c</code>) — clone it and run the same three commands yourself.</sub>
</p>

**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.

**The result: 10x-300x fewer tokens** than a plain Read/Grep workflow
on the everyday tasks (orientation, outlining a large file, a symbol's
callers), measured across 7 real, unmodified open-source repos on dekko
0.43.77. The floor, a small grep-friendly local symbol, is about 2.5x.
The full breakdown is right below.

## 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, 172k
symbols) on dekko 0.43.77, dekko's structured queries used **10x–300x
fewer tokens** than the equivalent `Read`/`Grep` workflow for the same
task (repo orientation, outlining a large file, tracing a symbol's
callers).

| Task | Example repo (scale) | dekko | Read/Grep | Savings |
|---|---|---:|---:|---:|
| Repo orientation (`summary`) | awesome-go (10 files) | 359 tok | ~16,328 tok | ~45x |
| Repo orientation (`summary`) | claude-buddy (57 files) | ~349 tok | ~113,514 tok (every source file) | ~325x |
| Outline a large file | claude-code `REPL.tsx` (5,005 lines) | ~1,154 tok | ~223,963 tok | ~194x |
| Outline a large file | cline `SdkController.ts` (84 KB) | 1,803 tok | ~21,023 tok | ~11.7x |
| Outline a directory | zed `crates/git_ui/src` (32 files) | ~35,778 tok | ~418,520 tok | ~11.7x |
| Callers of a symbol | claude-code `errorMessage` | ~602 tok | ~18,521 tok (323+ grep hits) | ~31x |
| Callers of a symbol | zed `MultiWorkspace.new` (22 sites, 8 files) | ~809 tok | ~381,446 tok (read the caller files) | ~471x |
| External-API usage | claude-code `chalk` | ~798 tok | ~8,099 tok | ~10x |
| Bundled context (`workset`) | awesome-go `ToHTML` | 263 tok | 4,104 tok | ~16x |

dekko's cost stays roughly flat per query while `Read`/`Grep` scales
with file/repo size, so the ratio grows with scale. It's fast in
wall-clock terms too: mapping dekko's own ~4,300-symbol codebase from a
cold cache takes about 5 seconds on all cores, an incremental remap
after an edit is well under a second, and queries against the resulting
map return instantly. The win isn't universal — small, self-contained
files and already-grep-friendly local symbols see little benefit (the
floor measured was about 2.5x). See
[`benchmarks/real-world-repos/`](benchmarks/real-world-repos/README.md)
for the full per-task breakdown, methodology, the original 2026-08
study, and the correctness caveats it raised and how they were closed.

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.

## Install

```sh
uv tool install dekko      # or: pip install dekko / pipx install dekko
dekko --claude-install     # add the /map command + MCP server to Claude Code, then restart
```

Extras (`dekko[all]` for ~55 more languages, `dekko[search]` for
embedding search), installing from a local clone, and uninstalling are
in [docs/install.md](docs/install.md).

## 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. If your repo has
languages outside the default Tier-1 set (Python, C, C++, JS/TS, Go,
Java, Rust), `dekko map` will say so per file; install `dekko[all]` for
~55 more languages (see [Install](#install)) and re-run.

## Documentation

- [docs/install.md](docs/install.md) — installation, extras, local
  clone, uninstall
- [docs/cli.md](docs/cli.md) — every CLI command, symbol targets,
  excluding files, notes, daemon mode, language support
- [docs/claude-code.md](docs/claude-code.md) — the `/map` plugin, push
  hooks, Claude Code skills, the MCP server, and Cline

## 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