Cstfu setup
Build a personal tic blocklist for the cstfu Stop hook by mining the reader's own Claude transcripts, boarding the results for a keep-or-block verdict, and writing the word list the hook enforces. Use when setting cstfu up for the first time, when the hook is installed but blocks on length only, when someone asks to stop a habitual phrase, or when an existing blocklist needs re-mining against fresh transcripts. Triggers on "cstfu-setup", "set up cstfu", "block my tic words", "stop saying X", "what words do I overuse", "mine my transcripts", "refresh my blocklist".From its SKILL.md
npx -y skills add eighteyes/cstfu --skill cstfu-setupAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
6.9 KB, as published. Nobody here has run it
cstfu-setup
Length limits catch bloat. They do not catch a word used a thousand times until it means nothing. This builds the second half: a blocklist mined from the reader's own output, not from a list of words someone else finds annoying.
The blocklist is personal by construction. Mine first, judge second, install third. Never hand-author it — the phrases a writer overuses are exactly the ones they cannot see.
Prerequisite
cstfu-hook.py installed and registered as a Stop hook. Set $CSTFU to the
directory holding bin/, then confirm it is there:
CSTFU=$(dirname "$(fd -HI cstfu-hook.py ~/.claude ~/projects | head -1)")/..
ls -l "$CSTFU/bin/cstfu-hook.py"
Installed as a plugin, that path is ~/.claude/plugins/marketplaces/cstfu.
Installed by hand, it is wherever the repo was cloned.
If it is absent, install cstfu first. A blocklist with no hook enforces nothing.
1. Mine
python3 $CSTFU/bin/cstfu-mine.py --top 50
Walks every Claude Code transcript under ~/.claude/projects, keeps assistant
text only, strips code fences, inline code, paths and URLs, then counts each
phrase in bin/cstfu-candidates.txt. Reports an occurrence count and a rate per
10,000 prose words.
Read the rate, not the count. Count scales with how much the reader has written; rate is comparable across corpora and is what makes a phrase a tic.
Extend the candidate list before mining if the reader names a suspect. A phrase that never appears scores zero and drops off the board.
2. Sample before judging
A high count is not proof of a tic. Some words are load-bearing vocabulary in the reader's domain and will rank high while being entirely legitimate.
python3 $CSTFU/bin/cstfu-mine.py --sample "harness" --sample-n 6
Do this for every phrase in the top ten, and for any phrase whose verdict is not obvious. Report the sampled verdict on the board so the human judges on evidence rather than on the ranking alone.
The distinction that matters: does the phrase carry meaning here, or is it
filler that survived because nothing pushed back? One mining run found harness
at 1.23 per 10k and every sampled use was a technical noun. The same run found
let me at 80.28 per 10k and every sampled use was self-narration.
3. Board the verdicts
Every phrase takes the same three-value answer, so this is a grid-board, not a question card each.
python3 $CSTFU/bin/cstfu-mine.py --top 50 --format board > /tmp/tics.json
Add each phrase's sampled verdict as a note on its row before serving. Then:
WK_BOARD_TEMPLATE=grid-board.html WK_BOARD_SESSION=cstfu-tics \
node ~/.claude/skills/shape-board/serve.mjs /tmp/tics.json \
> /tmp/tics.result.json.partial && mv /tmp/tics.result.json.partial /tmp/tics.result.json
Serve it in the background; the submit is the wake signal. Write through the temp and move on success — the redirect truncates the result file the moment the server starts, so a relaunch destroys the previous round's verdicts.
Columns are BLOCK, WARN and KEEP. WARN exists so a phrase can be watched without forcing rewrites; nothing consumes it yet, so treat a WARN as "not blocked" and say so rather than implying it is enforced.
4. Install the list
Write one phrase per line to ~/.claude/hooks/cstfu-tics.txt, keeping the
mined count and rate as a trailing comment so the next re-mine has a baseline.
jq -r '.by_choice.block[]' /tmp/tics.result.json > ~/.claude/hooks/cstfu-tics.txt
The hook reads that path, or $CSTFU_TICS if set. An absent file disables tic
checking entirely — the length limits still apply.
5. Set the limits
Defaults are 25-word sentences, a 15-word average, a 200-word turn and a 25-word
question line. Change any of them in ~/.claude/hooks/cstfu-limits.json, or
point $CSTFU_LIMITS elsewhere. Write only the keys that change:
{ "turn": 120, "sentence": 20 }
Keys are sentence, avg_sentence, turn, question_line. A bad file, an
unknown key or a non-positive value falls back to that key's default in silence,
so a typo enforces the default rather than announcing itself. Confirm what the
hook actually reads before trusting a config:
python3 $CSTFU/bin/cstfu-hook.py --limits
Anything not marked overridden did not take. Tighten one limit at a time — every limit lowered is a rewrite forced on more turns.
6. Prove it fires
python3 $CSTFU/bin/test-cstfu-hook.py
Twenty-eight cases against a throwaway list and a throwaway config, both directions. Then check one real phrase from the reader's own list, because the test uses its own:
printf '%s\n' '{"type":"assistant","message":{"content":[{"type":"text","text":"Let me check that."}]}}' > /tmp/t.jsonl
echo '{"transcript_path":"/tmp/t.jsonl"}' | python3 $CSTFU/bin/cstfu-hook.py; echo "rc=$?"
rc=2 with the phrase named on stderr means it is enforcing. rc=0 means the
list is not being read — check the path and that the phrase survived the board.
What the hook will and will not catch
case caught
tic in ordinary prose yes
tic inside `code spans` no, stripped before counting
tic in a fenced block no, stripped before counting
tic in a path or URL no, stripped before counting
tic on a `>` quoted line no, exempt line
tic in a heading or table no, exempt line
tic on a line starting `!` no, exec fragment
tic as part of a longer word no, word boundaries are asserted
tic in a bare technical noun yes — this is the false-positive surface
That last row is the one to warn about. critical inside a risk table is prose
to the hook. If a domain word ranks high and reads legitimately in samples, KEEP
it; a blocklist that fights the reader's vocabulary gets deleted within a week.
Cost of blocking a frequent phrase
A phrase at 80 per 10,000 words appears in most turns. Blocking it forces a rewrite on most turns until the habit changes. That is the mechanism working, not a fault — but say the number out loud before installing, so the choice is made with it rather than discovered afterward.
The hook honours stop_hook_active, so it never blocks twice in a row. Worst
case is one forced rewrite per turn, never a loop.
Re-mining later
Rates drop as habits change, and new tics grow in to replace old ones. Re-mine against fresh transcripts, compare against the trailing comments in the current list, and board only what moved. A phrase whose rate has collapsed has served its purpose and can come off the list.