3 -File-save prompt markers for pi.
5 +Editor-save bridge from comments to background Pi edits.
7 -A prompt line starts with a configured marker as the first word after whitespace.
8 -Default markers: `LLM`, `PROMPT`.
15 +Marker must appear after a known comment prefix. Raw markers never run.
11 18 void main(final
String[] a) {
12 - LLM some prompt text
16 - LLM and then fix perf
22 -- `LLM some prompt text` → one agent request
23 -- `LLM deal with this` → one agent request
24 -- consecutive `LLM open ui` + `LLM and then fix perf` → one multi-line agent request
26 -Comment markers are not special. Configure them explicitly if wanted:
31 - "markers": [
"LLM",
"//LLM",
"/// LLM",
"* LLM"]
20 + if (a.length
== 0) {
37 -fn fancy_algorithm() {
44 -- marker must be first word/token on line, modulo leading whitespace
45 -- no automatic comment-prefix stripping for matching
46 -- use configured markers like `//LLM`, `* LLM`, `/// LLM` for comments
47 -- consecutive lines with the same marker are grouped
48 -- no `:` and no `{{ }}` syntax
37 +- raw `llmiterate:` is ignored
38 +- legacy `LLM` / `PROMPT` is ignored
39 +- consecutive marker lines are grouped
49 40 - empty marker lines are ignored
50 -- fenced code blocks in Markdown are ignored
41 +- `!llmiterate` disables the whole file
49 +Built in prefixes cover common languages:
52 +// /// //! # ## ### -- --- ; ;; ;;; % %% * *> ' :: REM rem dnl DNL <!-- /* /**
55 +Config `commentPrefixes` appends to builtins:
60 + "commentPrefixes": [
"COMMENT"]
52 65 ##
Replacement behavior 54 -llmiterate instructs the agent to treat marker lines as inline prompts/TODOs and replace the whole marker span with the requested implementation/change.
67 +On save or `/llmiterate scan`, matching markers are queued. A background Pi RPC worker edits files. Success means the marker span is gone/replaced.
69 +llmiterate itself does not mutate source files; only the worker uses normal Pi tools.
58 -Once queued, a marker key is recorded in the platform state dir:
71 +##
State / retry policy 60 -| Platform | State path |
61 -|----------|------------|
62 -| Linux/BSD | `${XDG_STATE_HOME:-~/.local/state}/pi/llmiterate/<projectHash>/state.json` |
63 -| macOS | `~/Library/Application Support/pi/llmiterate/<projectHash>/state.json` |
64 -| Windows | `%LOCALAPPDATA%\\pi\\llmiterate\\<projectHash>\\state.json` |
67 -file:startLine:hash(promptText)
76 +${XDG_STATE_HOME:-~/.local/state}/pi/llmiterate/<projectHash>/state.json
70 -Same marker will not rerun on later saves. To rerun, edit the prompt text or run:
82 +queued | running | done | failed
85 +Duplicate saves do not start duplicate queued/running jobs. Failed markers remain retryable on next save/scan. Markers are only `done` after the worker finishes and the marker no longer exists.
78 -llmiterate always runs marker work in an isolated background Pi RPC worker.
79 -It never injects marker prompts into the current chat session.
81 -The worker is launched as:
84 -pi --mode rpc --no-extensions --session-dir
<platform-state-dir
>/llmiterate/
<projectHash
>/sessions
92 +LLMITERATE_WORKER
=1 pi \
95 + --session-dir
<state
>/llmiterate/
<projectHash
>/sessions \
96 + --append-system-prompt
<llmiterate worker rules
> \
97 + --model
<optional
> \
98 + --thinking
<optional
> 87 -Each marker job gets a fresh RPC session. Jobs are serialized per project: one background job runs at a time, queued jobs wait.
88 -Each job revalidates the marker span before launch; stale markers are skipped.
92 -llmiterate never edits files itself. File mutation comes only from the isolated Pi job via normal tools.
96 -- handles normal writes, atomic-save rename patterns, moves into watched dirs, and new directories
97 -- refreshes directory watchers after `rename` events
98 -- removes watchers for deleted/moved-away directories
99 -- tracks watcher errors in status
100 -- skips queued requests when their marker span changed before background agent start
101 -- watches only directories that can contain paths configured in `llmiterate.include`
102 -- treats `llmiterate.exclude` as an optional veto after the include whitelist
104 -##
Singleton behavior 106 -llmiterate is a singleton per detected project root, not raw shell cwd. The first Pi process creates `<platform-state-dir>/llmiterate/<projectHash>/lock` and owns the watcher. Other Pi processes launched anywhere under the same project root go into standby and only show status.
108 -Project root detection:
110 -1. nearest ancestor containing `.pi/` or `AGENTS.md`
111 -2. else nearest ancestor containing `.git`
114 -- duplicate watchers do not queue duplicate agent runs
115 -- singleton roots are canonicalized with `realpath` so symlinked launches share a lock
116 -- stale global per-project locks are recovered when the owning PID is gone
117 -- subprojects are separate when they have their own `.pi/`, `AGENTS.md`, or `.git`
101 +`LLMITERATE_WORKER=1` prevents recursive llmiterate watchers while keeping other extensions available.
121 -All config lives under the `llmiterate` key in Pi `settings.json`.
122 -Global: `~/.pi/agent/settings.json`. Project override: `.pi/settings.json`.
124 -Default `include` is empty, so llmiterate watches nothing until explicitly enabled for paths.
105 +Default `include` is `["**/*"]`. `.gitignore` and `.ignore` files are respected, plus default metadata/build excludes.
137 118 "debounceMs": 3000,
138 119 "maxFileBytes": 1000000,
139 - "markers": ["LLM", "PROMPT"]
120 + "timeoutMs": 600000,
121 + "maxWatchDirs": 10000,
122 + "model": "zai/glm-5.1",
123 + "thinking": "high",
129 +`notify`: `off | errors | done | all`. Default: `errors`.
149 136 /llmiterate hide hide panel
150 137 /llmiterate status show panel
151 138 /llmiterate scan scan all matching files now
152 -/llmiterate reset forget processed marker ledger
139 +/llmiterate reset forget run state
153 140 /llmiterate reload reload config + watcher
141 +/llmiterate log open latest worker transcript as markdown in $VISUAL/$EDITOR
146 +- source file: final edits only
147 +- footer status: idle/queued/running/done/failed
148 +- panel: queue/dashboard
149 +- notifications: errors by default
150 +- markdown log: full assistant/tool transcript
158 154 <!-- demo:workflow_suite:start -->