ArcticFox2029 Set up chamnan here
Do these in order. Report the numbers as you go; the user should see what changed, not just "done".
1. Build the index
chamnan-map
Read what it printed. The important line is the described percentage.
2. If coverage is under 70%, offer to fix it — do not just report it
A low number is not a complaint about the user, it is the single biggest lever on whether any of this works. The index is built from each file's opening comment; without them it degrades to a list of filenames, which is worth little.
Say plainly what the number means and what you can do about it, then — with the user's go-ahead —
dispatch the chamnan:commenter agent over the files that lack one (the plugin-scoped name, so a second installed plugin that also ships a commenter cannot be picked instead). That agent runs on a cheap model
because "read this file, write one line about it" does not need an expensive one; this is the
routing principle the plugin ships with, applied to its own onboarding.
Give the agent the specific file list, not the whole repo, and tell it which language to write
in — read language from .chamnan/config.json (default en). The agent writes English unless
you name something else, so this has to be passed explicitly.
Get that list from chamnan-map --undocumented, which prints every one of them, one path per
line. The names the rebuild itself prints are capped at eight and labelled "for example" — acting
on those alone fixes eight files and reports a before/after as though the gap were handled. On a
repository with forty undocumented files that leaves 80% of them untouched and unmentioned.
Mention to the user that the setting exists and that changing it is one sentence: "use Thai for the
comments" is enough, and you edit .chamnan/config.json for them. English costs fewer tokens on
every session, but that is a default worth overriding for a team that will not read English
comments — say the trade-off once and let them choose.
Then run chamnan-map again and show the before/after coverage.
Never edit files for this without asking first. It touches every undocumented file in the repo.
3. Record where things stand
chamnan-report
On a repo with history this prints a weekly trend and marks today. On a fresh one it will say there is not enough history yet — that is correct, not a failure. Say so rather than hiding it.
4. Write the first STATE.md
Create .chamnan/STATE.md with what the user is actually working on right now. Keep it short —
this file is injected into every future session, so it is paid for repeatedly.
Write it at milestones only: a test suite passing, a commit landing, a decision being made, or the session ending. Not after every edit. A state file rewritten every few turns costs output tokens continuously and buries the one line that mattered in a history of near-identical versions.
5. Offer to keep it fresh
chamnan-map --install-git-hook
Offer this, do not run it unprompted — it writes into .git/hooks/, which is the user's. It appends
to an existing hook rather than replacing it, and never fails a commit. Explain the reason rather
than the mechanism: an index that drifts out of step with the code is worse than none, because the
next session trusts it and opens the wrong file.
6. Tell the user what they got, honestly
- how many tokens the index is versus the source it indexes
- that the full detail is grepped, never read whole
- that the effect compounds: this repo gets cheaper to work in the more it is revisited, and gives back nothing on a repo touched once