{
  "markdown": "# distill\n[![Anthropic Published](https://img.shields.io/badge/Anthropic-Officially%20Published-ff6b35?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMTIgMkw0IDIwaDQuNUwxMiA4bDMuNSAxMkgyMEwxMiAyeiIgZmlsbD0id2hpdGUiLz48L3N2Zz4=)](https://claude.com/plugins)\n[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blue)](https://claude.com/plugins)\n\n<img width=\"3584\" height=\"1184\" alt=\"Gemini_Generated_Image_3n1r983n1r983n1r (1)\" src=\"https://github.com/user-attachments/assets/aaefdcc5-1a18-4802-ab2f-4e9a8fa30d7a\" />\n\n\nA Claude Code plugin that distills your codebase into context files. Invest tokens once, save them on every future session.\n\n## Why\n\nOn large codebases, Claude Code spends significant tokens reading source files just to orient itself before starting real work. This cost is paid every session, by every team member.\n\n`distill` analyzes your codebase once and produces structured documentation files in `.claude/docs/`. Future sessions reference these files on demand — Claude reads `testing.md` when working on tests, `api.md` when working on endpoints, and nothing when the task doesn't require it.\n\nThis also solves onboarding: a new team member (or a new Claude session) gets instant project context without reading hundreds of source files.\n\n## Installation\n\n```bash\n/plugin marketplace add utkarsh-jain/distill\n/plugin install distill\n```\n\n## Quick Start\n\n```bash\n# Generate project orientation + architecture overview\n/distill:generate\n\n# Generate everything\n/distill:generate --all\n\n# Quick, minimal summaries (30-50 lines each)\n/distill:generate --lean --all\n\n# Exhaustive docs with extra sections\n/distill:generate --deep --all\n\n# Update only stale docs after making changes\n/distill:generate --update\n\n# Check which docs need updating (no changes made)\n/distill:generate --status\n```\n\n## Flags\n\n| Flag | Generates | Description |\n|---|---|---|\n| *(none)* | `onboard.md`, `architecture.md` | Project orientation + system design |\n| `--structure` | `structure.md` | Per-module breakdown with file inventories |\n| `--api` | `api.md` | Endpoints, auth, request/response shapes, middleware |\n| `--data` | `data.md` | Models, schemas, relationships, migrations |\n| `--internals` | `internals.md` | Core logic, key abstractions, state management |\n| `--config` | `config.md` | Env vars, config files, feature flags, deploy config |\n| `--testing` | `testing.md` | Test stack, how to run, patterns, fixtures, CI pipeline |\n| `--all` | all of the above | Full documentation suite |\n| `--update` | *(varies)* | Regenerate only files affected by changes since last run |\n| `--status` | *(nothing)* | Report which docs are current vs stale |\n| `--lean` | *(varies)* | Minimal 30–50 line summaries, reduced analysis |\n| `--deep` | *(varies)* | Richer docs with extra sections and deeper analysis |\n| `--sequential` | *(varies)* | Force sequential generation (useful behind rate limits or proxies) |\n| `--install-hook` | *(nothing)* | Install a git pre-push hook that warns when docs are stale |\n\nFlags combine: `/distill:generate --api --testing` generates both.\n\n`--update` combines with specific flags: `/distill:generate --update --api` updates only `api.md` if stale.\n\n## Depth Profiles\n\nControl how much detail is generated per doc:\n\n| Depth | Lines per doc | Reading budget | Use when |\n|---|---|---|---|\n| `--lean` | 30–50 | 5–8 files | Quick orientation, token-constrained environments |\n| *(default)* | 60–200 | 15–20 files | Standard usage (varies by doc type) |\n| `--deep` | 120–500 | 25–35 files | Comprehensive reference, complex codebases |\n\n`--lean` generates only the most critical sections per doc (e.g., onboard gets \"What This Is\" + \"Tech Stack\" + \"Quick Start\" only). `--deep` adds extra sections like \"Cross-cutting Concerns\" in architecture and \"Coverage Map\" in testing.\n\nThe depth is recorded in each doc's frontmatter, so `--update` preserves it automatically.\n\nSet a team default in `.distill.yml`:\n\n```yaml\ndefault_depth: lean\n```\n\n## Output\n\n```\nyour-project/\n├── CLAUDE.md                     ← index section added between markers\n└── .claude/\n    └── docs/\n        ├── onboard.md            — what this is, tech stack, quick start, directory map\n        ├── architecture.md       — system design, components, data flow, entry points\n        ├── structure.md          — per-module breakdown\n        ├── api.md                — API surface\n        ├── data.md               — data layer\n        ├── internals.md          — core business logic\n        ├── config.md             — configuration\n        └── testing.md            — test infrastructure\n```\n\n**How Claude uses these files:**\n\n1. `CLAUDE.md` is loaded every session. It contains a small index listing available docs.\n2. Claude sees the index and reads only the files relevant to the current task.\n3. Each doc links to related docs via a \"See also\" section, so Claude can follow references across topics.\n4. A session about fixing a test reads `testing.md`. A session about a new endpoint reads `api.md`. A quick bug fix might read nothing beyond the index.\n\nToken cost is proportional to task relevance, not project size.\n\n## The `--update` Workflow\n\nEach generated file records the git commit it was generated from and which source paths it covers. When you run `--update`:\n\n1. For each existing doc, diffs the current HEAD against its source commit\n2. Maps changed files to their covering doc using recorded scope paths\n3. Regenerates only stale docs — current ones are skipped with a status report\n\nRecommended workflow:\n\n```bash\n# Before pushing, update any stale docs\n/distill:generate --update\n```\n\nThis keeps docs current with minimal token cost — only changed areas are re-analyzed.\n\n## Automatic Staleness Checks\n\nInstall a git hook that warns when docs are stale before pushing:\n\n```bash\n/distill:generate --install-hook\n```\n\nThis adds a lightweight pre-push hook that checks doc freshness by comparing git commit hashes in frontmatter against HEAD. If any docs are stale, the push is blocked with a reminder to run `--update`. The hook does not invoke Claude or spend tokens. Use `git push --no-verify` to bypass.\n\n## Team Configuration\n\nCreate `.distill.yml` in your project root to customize behavior for your team:\n\n```yaml\n# Default depth profile (lean, default, deep)\ndefault_depth: default\n\n# Default flags when none are provided\ndefault_flags:\n  - --api\n  - --testing\n\n# Extra directories to ignore during analysis\nignore:\n  - generated/\n  - third_party/\n\n# Override line targets per file\nmax_lines:\n  onboard: 120\n  api: 300\n\n# Custom path mappings for --update staleness detection\n# Use when your project doesn't follow standard directory conventions\nscope_overrides:\n  api:\n    - server/routes/\n    - server/handlers/\n  data:\n    - server/db/\n    - prisma/\n\n# Patterns to exclude from secret scanning (regex)\n# Use when test fixtures or docs legitimately contain token-like strings\nsecret_scan_allowlist:\n  - \"sk-test-fake-key-\\\\w+\"\n  - \"AKIA_EXAMPLE_\\\\w+\"\n```\n\nCommit this file so the whole team gets consistent behavior.\n\n## Monorepo Support\n\n`distill` detects monorepo configurations (npm/yarn/pnpm workspaces, Lerna, Nx, Turborepo, Cargo workspaces, Gradle multi-project). When detected:\n\n- `onboard.md` includes a package index with one-line descriptions\n- Other docs clearly delineate which package each section covers\n- For large monorepos (>20 packages), the plugin suggests running from individual package directories for more focused output\n\n## Preserving Hand-Written Content\n\nThe plugin manages content between `<!-- distill:start -->` and `<!-- distill:end -->` markers in `CLAUDE.md`. Everything outside the markers is untouched.\n\nFiles in `.claude/docs/` are fully managed by the plugin and are overwritten on regeneration. Add custom context in separate files or in `CLAUDE.md` outside the markers.\n\n## How It Works\n\nThe plugin is a Claude Code skill — a structured prompt that instructs Claude to:\n\n1. Identify the project type, language, and framework\n2. Map the directory structure and detect monorepo layouts\n3. Read strategically: entry points, type definitions, config files, and structural files (not every source file)\n4. When generating 3+ docs, spawn parallel agents — one per doc — for faster execution\n5. Generate concise, accurate documentation with verified file paths\n6. Scan generated output for accidentally included secrets before writing files\n7. Record source commit and scope paths in frontmatter for incremental updates\n8. Update the root `CLAUDE.md` index\n\nThe analysis is thorough but targeted — it reads the minimum files needed to produce accurate docs, using language-specific strategies (e.g., reading barrel files in TypeScript, `__init__.py` in Python, interface definitions in Go).\n\n## License\n\nMIT\n",
  "bytes": 8915,
  "sha": "fe61a70f8d399df237776469a8b8f834d760e9642dbae62613c6ee7a82a33bd9",
  "repo_slug": "utkarshjain98/distill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_utkarshjain98_distill_distill_98ab4afd/readme"
}