Claude Code plugin · v0.1

filetree.

A one-line description per file, with a content hash on every entry. FILETREE.md lives in your repo, ships in your PRs, and lets the LLM grasp the layout in a few hundred tokens — before it touches code.

View source
01 The waste

Every session, the same archaeology.

Open Claude Code, get a new context window, watch the assistant ls · grep · cat its way to a vague picture of your repo. Tomorrow it starts over. The dig is expensive, and the artifacts get thrown out.

01
LLM rediscovers your layout, session after session.
Persist it once as FILETREE.md. Commit to git. Share with collaborators.
02
Hand-written summary docs go stale silently.
Each entry carries an 8-char content hash. Mismatch is the drift signal.
03
Rewriting every description on small refactors wastes tokens.
UNCHANGED bias — purpose intact, only the hash refreshes. ~100× cheaper.
04
Other "code index" tools spin up sqlite, a daemon, a file watcher.
One markdown file. Change detection delegated to git. Zero background process.
02 Mechanism

≈ 80% of changed files emit one word: UNCHANGED.

A refactor doesn't change what a file does. Renaming a variable, adding tests, fixing a bug — purpose stays intact. The LLM reads, judges, replies UNCHANGED. The script refreshes the hash and keeps the old summary. The manifest itself is the cache — no SQLite, no daemon, no separate "I already saw this" memory.

naive rewrite
~120 tokens
read · understand · summarize
unchanged path
~4 bytes
read · judge · UNCHANGED
03 Flow

A loop, not a build step.

todo
git ls-files · hash-object · diff against manifest.
Produces added / changed / removed / renamed.
LLM
Per added file: write a one-line summary.
Per changed: UNCHANGED or a fresh line.
apply
Refresh hashes · overwrite changed entries · move renames · sort.
Writes FILETREE.md.
You
Skim the diff. git add · commit if it reads right.
The tool never commits for you.
04 Surface

Three commands. Each self-contained.

Namespaced slash commands, designed to be readable end-to-end from a single file. No dispatch indirection, no hidden state, no magic.

/filetree:init
Generate FILETREE.md from scratch. Refuses to overwrite without confirmation. Every tracked file becomes an entry.
first run
/filetree:update
Sync the manifest with current repo state. Added · changed · removed · renamed — handled in one pass. UNCHANGED bias keeps it cheap.
daily
/filetree:lint
Read-only drift check. Exits non-zero if anything is stale. Does not call the LLM — safe in CI, pre-commit hooks, anything tight.
ci-friendly
05 Restraint

What it refuses to do.

Scope creep kills small tools. The non-goal list is part of the design.

declined responsibilities reason
  • no. function- or class-level tracking File-level is the resolution. grep covers the rest.
  • no. semantic search / vector index Not this tool's job. Use grep + the LLM.
  • no. watcher · daemon · background process Explicit slash command, at moments you choose.
  • no. auto-commit Review is the last quality gate. Stays with you.
  • no. dependency / call-graph mapping Manifest says what, not who calls whom.
06 Install

Stop digging.
Start reading.

Two lines in Claude Code and the plugin is live. Run /filetree:init once; from then on it's /filetree:update when the layout shifts.

step 01 /plugin marketplace add nekocode/filetree-skill
step 02 /plugin install filetree
step 03 /filetree:init — it offers to wire CLAUDE.md / AGENTS.md first, then maps the repo. Review the diff, commit.