From 9c90d4837213251d8615dd0e7386530ad008c792 Mon Sep 17 00:00:00 2001 From: Ismo Vuorinen Date: Fri, 20 Mar 2026 21:56:31 +0200 Subject: [PATCH] docs(claude): document new hooks, skills, and context-mode --- CLAUDE.md | 115 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 105 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index fbb143c..56205b1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -163,20 +163,115 @@ SC2174 (mkdir -p -m), SC2016 (single-quote expressions). ## Claude Code Configuration - **Hooks** (`.claude/settings.json`): - - *PreToolUse*: Blocks edits to `fzf-tmux`, `yarn.lock`, `.yarn/` - - *PostToolUse*: Auto-runs `shfmt` on shell scripts after Edit/Write - - *PostToolUse*: Auto-runs `fish_indent` on `.fish` files after Edit/Write - - *PostToolUse*: Auto-runs `stylua` on `.lua` files after Edit/Write + - *PreToolUse*: Blocks edits to `fzf-tmux`, `yarn.lock`, + `.yarn/`, submodule paths, and real secrets.d files + - *PostToolUse*: Auto-formats files by extension + (shfmt, fish_indent, stylua, biome, prettier) + - *PostToolUse*: Validates Dotbot `install.conf.yaml` + after edits + - *PostToolUse*: Warns on formatter/linter config changes + - *Stop*: Runs `yarn lint` gate before finishing - **Skills** (`.claude/skills/`): - - `shell-validate`: Auto-validates shell scripts (syntax + shellcheck) - - `fish-validate`: Auto-validates fish scripts (syntax + fish_indent) + - `shell-validate`: Auto-validates shell scripts + (syntax + shellcheck) + - `fish-validate`: Auto-validates fish scripts + (syntax + fish_indent) - `lua-format`: Auto-formats Lua files with stylua - - `yaml-validate`: Auto-validates YAML files (yamllint + actionlint) + - `yaml-validate`: Auto-validates YAML files + (yamllint + actionlint) + - `dotbot-validate`: Validates Dotbot install.conf.yaml + - `new-script`: Scaffolds helper scripts in local/bin/ + - `new-fish-function`: Scaffolds fish functions + - `host-override`: Creates host-specific config overlays - **Subagents** (`.claude/agents/`): - - `code-reviewer`: Reviews shell/fish/lua changes for correctness and style -- **MCP Servers**: - - `context7`: Live documentation lookup for tools and libraries + - `code-reviewer`: Reviews shell/fish/lua changes +- **Plugins** (required): + - `context-mode`: Context window protection — must be + installed for this repo. See routing rules below. + - `context7`: Live documentation lookup ## Package Manager Yarn (v4+) is the package manager. Do not use npm. + +# context-mode — MANDATORY routing rules + +You have context-mode MCP tools available. These rules are NOT optional — +they protect your context window from flooding. A single unrouted command +can dump 56 KB into context and waste the entire session. + +## BLOCKED commands — do NOT attempt these + +### curl / wget — BLOCKED +Any Bash command containing `curl` or `wget` is intercepted and replaced with an error message. Do NOT retry. +Instead use: +- `ctx_fetch_and_index(url, source)` to fetch and index web pages +- `ctx_execute(language: "javascript", code: "const r = await fetch(...)")` to run HTTP calls in sandbox + +### Inline HTTP — BLOCKED +Any Bash command containing `fetch('http`, `requests.get(`, +`requests.post(`, `http.get(`, or `http.request(` is intercepted +and replaced with an error message. Do NOT retry with Bash. +Instead use: +- `ctx_execute(language, code)` to run HTTP calls in sandbox — only stdout enters context + +### WebFetch — BLOCKED +WebFetch calls are denied entirely. The URL is extracted and you are told to use `ctx_fetch_and_index` instead. +Instead use: +- `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` to query the indexed content + +## REDIRECTED tools — use sandbox equivalents + +### Bash (>20 lines output) +Bash is ONLY for: `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, `npm install`, `pip install`, and other short-output commands. +For everything else, use: +- `ctx_batch_execute(commands, queries)` — run multiple commands + search in ONE call +- `ctx_execute(language: "shell", code: "...")` — run in sandbox, only stdout enters context + +### Read (for analysis) +If you are reading a file to **Edit** it → Read is correct (Edit needs content in context). +If you are reading to **analyze, explore, or summarize** → +use `ctx_execute_file(path, language, code)` instead. Only your +printed summary enters context. The raw file stays in the sandbox. + +### Grep (large results) +Grep results can flood context. +Use `ctx_execute(language: "shell", code: "grep ...")` to run +searches in sandbox. Only your printed summary enters context. + +## Tool selection hierarchy + +1. **GATHER**: `ctx_batch_execute(commands, queries)` — Primary + tool. Runs all commands, auto-indexes output, returns search + results. ONE call replaces 30+ individual calls. +2. **FOLLOW-UP**: `ctx_search(queries: ["q1", "q2", ...])` — + Query indexed content. Pass ALL questions as array in ONE call. +3. **PROCESSING**: `ctx_execute(language, code)` | + `ctx_execute_file(path, language, code)` — Sandbox execution. + Only stdout enters context. +4. **WEB**: `ctx_fetch_and_index(url, source)` then + `ctx_search(queries)` — Fetch, chunk, index, query. + Raw HTML never enters context. +5. **INDEX**: `ctx_index(content, source)` — Store content in FTS5 knowledge base for later search. + +## Subagent routing + +When spawning subagents (Agent/Task tool), the routing block is +automatically injected into their prompt. Bash-type subagents are +upgraded to general-purpose so they have access to MCP tools. +You do NOT need to manually instruct subagents about context-mode. + +## Output constraints + +- Keep responses under 500 words. +- Write artifacts (code, configs, PRDs) to FILES — never return + them as inline text. Return only: file path + 1-line description. +- When indexing content, use descriptive source labels so others can `ctx_search(source: "label")` later. + +## ctx commands + +| Command | Action | +|---------------|---------------------------------------------------------------------------------------| +| `ctx stats` | Call the `ctx_stats` MCP tool and display the full output verbatim | +| `ctx doctor` | Call the `ctx_doctor` MCP tool, run the returned shell command, display as checklist | +| `ctx upgrade` | Call the `ctx_upgrade` MCP tool, run the returned shell command, display as checklist |