dekko: Instructions file for Claude Code

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/.
• test-repos/ holds real, unmodified open-source repos (awesome-go, claude-buddy, claude-code, cline, spring-boot, tensorflow, zed) used as realistic targets for manual/agent evaluation of dekko itself — not part of the pytest suite. It's gitignored (test-repos/ in .gitignore), so nothing under it is tracked; test-repos/reports/ (see below) is where evaluation write-ups accumulate locally.
• test-repos/TESTING-GUIDE.md is the checklist an agent dispatched to test dekko should work from: every CLI command/flag, the MCP tools, the daemon, install/uninstall flows, hooks, and the known-hard cross-cutting correctness cases (overload disambiguation, search relevance, call-graph resolution on trait/interface-heavy code, vendored-dir exclusion, budget capping, staleness). Update it whenever a feature is added or an existing one's behavior changes — a new subcommand, flag, MCP tool, or behavior change isn't done until this guide reflects it; don't leave it to whoever tests next to discover the gap.
• .dekko/MAP.md / .dekko/map.json at the repo root are dekko's own generated map of itself, regenerated on demand — expect them to show as modified after running dekko map; they're git-ignored by default but this repo tracks its own for dogfooding, so check whether a given change is worth including before committing it alongside unrelated work.
• Follow the branch/PR conventions in CONTRIBUTING.md: one conceptual change per PR, feat:/fix:/perf:/docs:/chore:-style commit prefixes (see git log for the house style), releases cut by pushing a v* tag.