5 -Manual editor-save bridge from comment markers to background Pi edits.
9 -llmiterate does not autostart.
10 -`/llmiterate` or `/llmiterate on` starts it for the exact real cwd.
11 -It loads global Pi settings, then `<scope>/.pi/settings.json`; there is no
12 -upward project-root search.
17 -2. load config and state
18 -3. acquire singleton lock for the scope hash
21 -6. queue matching markers
31 -Marker must appear after a known comment prefix.
32 -Raw markers never run.
35 -void main(final
String[] a) {
37 - if (a.length
== 0) {
54 -- raw `llmiterate:` is ignored
55 -- consecutive marker lines are grouped
56 -- empty marker lines are ignored
57 -- `!llmiterate` in a comment disables the whole file
61 -Prefixes are extension-scoped.
64 -| file type | prefix |
65 -| ----------------------------------------------------------------------------------------- | ----------------- |
66 -| .c/.cc/.cpp/.cs/.cts/.go/.h/.hpp/.java/.js/.jsx/.kt/.kts/.mts/.php/.scala/.swift/.ts/.tsx | // /// /* /** |
67 -| .rs | // /// //! /* /** |
69 -| .scss/.less | // /* /** |
70 -| .py/.sh/.bash/.zsh/.fish/.rb/.pl/.pm/.r/.toml/.yaml/.yml/.dockerfile/.ex/.exs | # |
71 -| .md/.mdx/.html/.htm/.xml | |
72 -| .sql/.lua/.hs | -- |
73 -| .lisp/.el/.clj/.scm | ; ;; ;;; |
78 -Unknown extensions do not run markers.
79 -Markdown only accepts HTML comments, so headings or bullets containing
80 -`llmiterate:` are inert.
82 -Config `commentPrefixes` appends by extension:
87 - "commentPrefixes": {
95 -##
Replacement behavior 97 -For each marker block, the worker receives a prompt containing:
102 -- marker span to replace
103 -- instruction to work in/around the file
104 -- instruction to remove the marker unless impossible
106 -Before a job starts, llmiterate rechecks that the marker still exists at the
107 -same line with the same prompt hash.
108 -If it changed, the job is failed as stale and skipped.
110 -After the worker finishes, llmiterate rechecks the file.
111 -If the same marker is still present at the same line with the same prompt hash,
112 -the job is marked failed.
113 -Otherwise that job is marked done.
117 -This extension is loaded through the root pi-ext package.
118 -See [../../README.md](../../README.md).
120 -##
Commands / tools / settings 125 -/llmiterate toggle on/off for current cwd
126 -/llmiterate on start watcher for current cwd + initial scan
127 -/llmiterate off stop watcher + worker
128 -/llmiterate status show scope/counts/state path
129 -/llmiterate explain <path> explain include/exclude/marker decision
130 -/llmiterate log render latest worker transcript and open it in $VISUAL/$EDITOR
133 -Debug commands, registered but not autocompleted:
136 -/llmiterate scan scan current scope now
137 -/llmiterate forget forget run state
138 -/llmiterate reload reload config + watcher
147 - stores UI context and renders status
148 -- `session_shutdown`:
149 - stops watcher/worker and releases lock
152 -`llmiterate` in global Pi settings and `<scope>/.pi/settings.json`.
154 -| setting | default | behavior |
155 -| ----------------- | ---------------------------------------- | ----------------------------------------------------------------------------------- |
156 -| `enabled` | `true` | `false` blocks `/llmiterate on` |
157 -| `include` | `["**/*"]` | glob allow-list |
158 -| `exclude` | built-in metadata/build/cache dirs/files | merged with user excludes |
159 -| `debounceMs` | `3000` | save debounce before scan |
160 -| `maxFileBytes` | `1000000` | larger files skipped |
161 -| `timeoutMs` | `600000` | RPC prompt timeout |
162 -| `maxWatchDirs` | `10000` | watcher directory cap |
163 -| `commentPrefixes` | built-ins by extension | appended by extension key |
164 -| `model` | unset | passed to worker as `--model` when set |
165 -| `thinking` | unset | `off \| minimal \| low \| medium \| high \| xhigh`; passed as `--thinking` when set |
166 -| `notify` | `errors` | `off \| errors \| done \| all`; worker notifications obey this policy |
174 - "include": [
"src/**/*.{ts,tsx,rs,java,md}",
"docs/**/*.md"],
175 - "exclude": [
"**/target/**",
"**/dist/**"],
176 - "debounceMs":
3000,
177 - "maxFileBytes":
1000000,
178 - "timeoutMs":
600000,
179 - "maxWatchDirs":
10000,
180 - "model":
"openai-codex/gpt-5.5",
181 - "notify":
"errors",
182 - "commentPrefixes": {
183 - "foo": [
"COMMENT"],
192 -Run `mise run bench` here, or `mise //extensions/llmiterate:bench` from the repository root, to benchmark marker parsing, path filtering, and gitignore scans.
196 -Only one watcher may own an exact real cwd at a time.
197 -Another Pi session in the same cwd enters standby and reports the lock owner.
198 -Parent and child dirs are independent.
203 -- respects `.gitignore` and `.ignore`
204 -- applies `include`/`exclude`
205 -- skips files over `maxFileBytes`
206 -- debounces file events by `debounceMs`
207 -- refreshes watched dirs after directory changes
208 -- stops at `maxWatchDirs`
210 -llmiterate itself does not edit source files.
212 -A background Pi RPC worker performs edits with normal Pi tools.
217 -<platform-state-dir>/pi/llmiterate/<sha256(scope)>/state.json
223 -${XDG_STATE_HOME:-~/.local/state}/pi/llmiterate/<sha256(scope)>/state.json
229 -queued | running | done | failed
232 -Duplicate saves do not start duplicate queued/running jobs.
233 -Failed markers remain retryable on next save or scan.
234 -Queued/running markers from a previous Pi process are reset to failed on state
236 -A marker becomes `done` after the worker finishes and the original
237 -same-line/same-hash marker no longer exists.
244 - watching/standby/queued/running/watch errors
246 - command results and worker errors
247 -- `/llmiterate log`:
248 - latest worker JSONL transcript rendered as markdown at
249 - `<state>/logs/latest.md`