llmiterate

File-save prompt markers for pi.

Marker syntax

A prompt line starts with a configured marker as the first word after whitespace. Default markers: LLM, PROMPT.

void main(final String[] a) {
  LLM some prompt text
  if (a.length == 0)
    LLM deal with this
  LLM open ui
  LLM and then fix perf
}

Parsing result:

• LLM some prompt text → one agent request
• LLM deal with this → one agent request
• consecutive LLM open ui + LLM and then fix perf → one multi-line agent request

Comment markers are not special. Configure them explicitly if wanted:

{
  "llmiterate": {
    "markers": ["LLM", "//LLM", "/// LLM", "* LLM"]
  }
}

fn fancy_algorithm() {
  //LLM implement knapsack algorithm
}

Rules:

• marker must be first word/token on line, modulo leading whitespace
• no automatic comment-prefix stripping for matching
• use configured markers like //LLM, * LLM, /// LLM for comments
• consecutive lines with the same marker are grouped
• no : and no {{ }} syntax
• empty marker lines are ignored
• fenced code blocks in Markdown are ignored

Replacement behavior

llmiterate instructs the agent to treat marker lines as inline prompts/TODOs and replace the whole marker span with the requested implementation/change.

Rerun policy

Once queued, a marker key is recorded in the platform state dir:

| Platform | State path | |----------|------------| | Linux/BSD | ${XDG_STATE_HOME:-~/.local/state}/pi/llmiterate/<projectHash>/state.json | | macOS | ~/Library/Application Support/pi/llmiterate/<projectHash>/state.json | | Windows | %LOCALAPPDATA%\\pi\\llmiterate\\<projectHash>\\state.json |

file:startLine:hash(promptText)

Same marker will not rerun on later saves. To rerun, edit the prompt text or run:

/llmiterate reset

Execution model

llmiterate always runs marker work in an isolated background Pi RPC worker. It never injects marker prompts into the current chat session.

The worker is launched as:

pi --mode rpc --no-extensions --session-dir <platform-state-dir>/llmiterate/<projectHash>/sessions

Each marker job gets a fresh RPC session. Jobs are serialized per project: one background job runs at a time, queued jobs wait. Each job revalidates the marker span before launch; stale markers are skipped.

Editor safety

llmiterate never edits files itself. File mutation comes only from the isolated Pi job via normal tools.

Watch behavior

• handles normal writes, atomic-save rename patterns, moves into watched dirs, and new directories
• refreshes directory watchers after rename events
• removes watchers for deleted/moved-away directories
• tracks watcher errors in status
• skips queued requests when their marker span changed before background agent start
• watches only directories that can contain paths configured in llmiterate.include
• treats llmiterate.exclude as an optional veto after the include whitelist

Singleton behavior

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.

Project root detection:

1. nearest ancestor containing .pi/ or AGENTS.md
2. else nearest ancestor containing .git
3. else current cwd

• duplicate watchers do not queue duplicate agent runs
• singleton roots are canonicalized with realpath so symlinked launches share a lock
• stale global per-project locks are recovered when the owning PID is gone
• subprojects are separate when they have their own .pi/, AGENTS.md, or .git

Config

All config lives under the llmiterate key in Pi settings.json. Global: ~/.pi/agent/settings.json. Project override: .pi/settings.json.

Default include is empty, so llmiterate watches nothing until explicitly enabled for paths.

{
  "llmiterate": {
    "enabled": true,
    "include": ["src/**/*.{ts,tsx,rs,java,md}", "docs/**/*.md"],
    "exclude": [
      ".git/**",
      ".pi/**",
      "node_modules/**",
      "target/**"
    ],
    "debounceMs": 3000,
    "maxFileBytes": 1000000,
    "markers": ["LLM", "PROMPT"]
  }
}

Commands

/llmiterate          toggle panel
/llmiterate show     show panel
/llmiterate hide     hide panel
/llmiterate status   show panel
/llmiterate scan     scan all matching files now
/llmiterate reset    forget processed marker ledger
/llmiterate reload   reload config + watcher

Demo