# CLAUDE.md

Project context for Claude Code (and other agents) working in this repo.

## What this project is

**dekko** is a fast, offline, dependency-free static code map generator and
codebase indexer for LLM coding agents. It parses a repo once with
tree-sitter (no model tokens spent parsing) into `MAP.md` (human-readable)
and `map.json` (machine-readable), then answers targeted structural
questions — "who calls this function," "what does this file contain,"
"what tests does this change impact" — without an agent reading whole
files or grepping blind. It ships three ways: a CLI (`dekko`), a Claude
Code `/map` plugin + MCP server, and Cline MCP support.

Source lives under `src/dekko/`, split into subpackages by role:
`core/` (parsing primitives — model, extractor, grammars, languages,
walker, resolver), `render/` (MAP.md/JSON/HTML/lean/export
rendering), `analysis/` (read-side commands — query, outline, search,
affected, trace, unused, stats, summary, workset, contextpack, diff,
relevance, ambiguous, deps, sanity), `daemon/` (the daemon process and
its transport), `integrations/` (cli, server, hooks, cline, orient,
claude_md, doctor), `storage/` (on-disk caches/locks/notes/ledger under
`.dekko/`), and a handful of modules with no subpackage-specific home
(`classify.py`, `textutil.py`, `source.py`, `repo_ops.py`) staying
directly under `src/dekko/`. `dekko outline src/dekko/<subpackage>/<file>.py` or
`dekko query symbol <name>` are cheaper ways to get oriented in this
codebase than reading whole files — dekko is a good tool for exploring
its own source. See `README.md` and `docs/` (`docs/install.md`,
`docs/cli.md`, `docs/claude-code.md`) for user-facing docs, and
`CONTRIBUTING.md` for the dev-setup/test/lint/release commands.

## Working in this repo

- `uv run pytest` / `uv run ruff check .` / `uv run ruff format --check .`
  — this is what CI runs; match it locally before considering something
  done. A project `.venv` exists (`.venv/bin/python -m pytest -q` works
  equivalently if `uv run` isn't available).
- Tests live in `tests/`, mirroring `src/dekko/`'s subpackages
  (`tests/core/`, `tests/render/`, `tests/analysis/`, `tests/daemon/`,
  `tests/integrations/`, `tests/storage/`) for tests that map cleanly
  to a single moved module; cross-cutting/behavioral tests (exercising
  several modules or the CLI end-to-end) and tests for the top-level
  modules stay flat directly under `tests/`. Test fixtures (tiny
  sample-language files) live in `tests/fixtures/`.
- `.dekko/MAP.md` / `.dekko/map.json` at the repo root are dekko's own
  generated map of itself; the map is git-ignored by default but this
  repo tracks its own for dogfooding. **Always regenerate the map before
  committing and commit the refreshed `.dekko/` files with the change:**
  run `dekko map` (or `uv run dekko map`) after your last source edit,
  then `git add .dekko/`. A checkout's map must match its source, so a
  source commit with a stale map is a bug. The `dekko-map` pre-commit
  hook runs `dekko map --if-stale` but only when hooks are installed and
  it does not stage the result, so it is not a substitute for doing this
  yourself.
- Follow the branch/PR conventions in `CONTRIBUTING.md`: one conceptual
  change per PR, Conventional-Commits-style commit prefixes (`feat`/
  `fix`/`docs`/`style`/`refactor`/`perf`/`test`/`chore`/`build`/`ci`/
  `revert` — CONTRIBUTING.md's "Commit messages" section has the full
  table and what each one means here), dekko's versioning rules
  (CONTRIBUTING.md's "Versioning" section: major is maintainer-only,
  minor closes out a testing round's fix cycle or ships a new
  top-level capability, patch is everything else; each fix track from
  an evaluation round is its own commit with its own patch bump),
  releases cut by pushing a `v*` tag.