{"_id":"@bugabinga/pi-ext-llmiterate","name":"@bugabinga/pi-ext-llmiterate","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@bugabinga/pi-ext-llmiterate","version":"0.1.0","type":"module","main":"index.ts","scripts":{"test":"bun test ./__tests__/*.test.ts"},"peerDependencies":{"@earendil-works/pi-coding-agent":"*","@earendil-works/pi-tui":"*"},"license":"MIT","description":"LLM iteration watcher for Pi.","keywords":["pi","pi-extension"],"gitHead":"a40a427fabf644375d6aab393ae450e15079f5b5","_id":"@bugabinga/pi-ext-llmiterate@0.1.0","_nodeVersion":"26.1.0","_npmVersion":"11.14.1","dist":{"integrity":"sha512-9Q8pGA6XD3RkIT0yt5DH5KqgSXajJ/wVnXQCr/BbXEfhGwykW3CqeaKYHXelnCH3LLE01wtKM/wi8U90YV0a5g==","shasum":"3f3cf25f60691cdfd30191ca760a54e6fa7fcf6e","tarball":"https://registry.npmjs.org/@bugabinga/pi-ext-llmiterate/-/pi-ext-llmiterate-0.1.0.tgz","fileCount":24,"unpackedSize":796605,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFo8Qb2UFSH9fsClwKVdgc1uZ2HLwOS37JoRpo5ynQzGAiAqAq2w00rTxbEz1BOnHj3DK5xLZFxT9lxQ5D9Q0lY2lQ=="}]},"_npmUser":{"name":"bugabinga","email":"oliver+npm@bugabinga.net"},"directories":{},"maintainers":[{"name":"bugabinga","email":"oliver+npm@bugabinga.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-ext-llmiterate_0.1.0_1779328438652_0.6453180786264521"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-21T01:53:58.487Z","0.1.0":"2026-05-21T01:53:58.862Z","modified":"2026-05-21T01:53:59.107Z"},"maintainers":[{"name":"bugabinga","email":"oliver+npm@bugabinga.net"}],"description":"LLM iteration watcher for Pi.","keywords":["pi","pi-extension"],"license":"MIT","readme":"# llmiterate\n\nFile-save prompt markers for pi.\n\n## Marker syntax\n\nA prompt line starts with a configured marker as the first word after whitespace.\nDefault markers: `LLM`, `PROMPT`.\n\n```java\nvoid main(final String[] a) {\n  LLM some prompt text\n  if (a.length == 0)\n    LLM deal with this\n  LLM open ui\n  LLM and then fix perf\n}\n```\n\nParsing result:\n\n- `LLM some prompt text` → one agent request\n- `LLM deal with this` → one agent request\n- consecutive `LLM open ui` + `LLM and then fix perf` → one multi-line agent request\n\nComment markers are not special. Configure them explicitly if wanted:\n\n```json\n{\n  \"llmiterate\": {\n    \"markers\": [\"LLM\", \"//LLM\", \"/// LLM\", \"* LLM\"]\n  }\n}\n```\n\n```rust\nfn fancy_algorithm() {\n  //LLM implement knapsack algorithm\n}\n```\n\nRules:\n\n- marker must be first word/token on line, modulo leading whitespace\n- no automatic comment-prefix stripping for matching\n- use configured markers like `//LLM`, `* LLM`, `/// LLM` for comments\n- consecutive lines with the same marker are grouped\n- no `:` and no `{{ }}` syntax\n- empty marker lines are ignored\n- fenced code blocks in Markdown are ignored\n\n## Replacement behavior\n\nllmiterate instructs the agent to treat marker lines as inline prompts/TODOs and replace the whole marker span with the requested implementation/change.\n\n## Rerun policy\n\nOnce queued, a marker key is recorded in the platform state dir:\n\n| Platform | State path |\n|----------|------------|\n| Linux/BSD | `${XDG_STATE_HOME:-~/.local/state}/pi/llmiterate/<projectHash>/state.json` |\n| macOS | `~/Library/Application Support/pi/llmiterate/<projectHash>/state.json` |\n| Windows | `%LOCALAPPDATA%\\\\pi\\\\llmiterate\\\\<projectHash>\\\\state.json` |\n\n```text\nfile:startLine:hash(promptText)\n```\n\nSame marker will not rerun on later saves. To rerun, edit the prompt text or run:\n\n```text\n/llmiterate reset\n```\n\n## Execution model\n\nllmiterate always runs marker work in an isolated background Pi RPC worker.\nIt never injects marker prompts into the current chat session.\n\nThe worker is launched as:\n\n```bash\npi --mode rpc --no-extensions --session-dir <platform-state-dir>/llmiterate/<projectHash>/sessions\n```\n\nEach marker job gets a fresh RPC session. Jobs are serialized per project: one background job runs at a time, queued jobs wait.\nEach job revalidates the marker span before launch; stale markers are skipped.\n\n## Editor safety\n\nllmiterate never edits files itself. File mutation comes only from the isolated Pi job via normal tools.\n\n## Watch behavior\n\n- handles normal writes, atomic-save rename patterns, moves into watched dirs, and new directories\n- refreshes directory watchers after `rename` events\n- removes watchers for deleted/moved-away directories\n- tracks watcher errors in status\n- skips queued requests when their marker span changed before background agent start\n- watches only directories that can contain paths configured in `llmiterate.include`\n- treats `llmiterate.exclude` as an optional veto after the include whitelist\n\n## Singleton behavior\n\nllmiterate 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.\n\nProject root detection:\n\n1. nearest ancestor containing `.pi/` or `AGENTS.md`\n2. else nearest ancestor containing `.git`\n3. else current cwd\n\n- duplicate watchers do not queue duplicate agent runs\n- singleton roots are canonicalized with `realpath` so symlinked launches share a lock\n- stale global per-project locks are recovered when the owning PID is gone\n- subprojects are separate when they have their own `.pi/`, `AGENTS.md`, or `.git`\n\n## Config\n\nAll config lives under the `llmiterate` key in Pi `settings.json`.\nGlobal: `~/.pi/agent/settings.json`. Project override: `.pi/settings.json`.\n\nDefault `include` is empty, so llmiterate watches nothing until explicitly enabled for paths.\n\n```json\n{\n  \"llmiterate\": {\n    \"enabled\": true,\n    \"include\": [\"src/**/*.{ts,tsx,rs,java,md}\", \"docs/**/*.md\"],\n    \"exclude\": [\n      \".git/**\",\n      \".pi/**\",\n      \"node_modules/**\",\n      \"target/**\"\n    ],\n    \"debounceMs\": 3000,\n    \"maxFileBytes\": 1000000,\n    \"markers\": [\"LLM\", \"PROMPT\"]\n  }\n}\n```\n\n## Commands\n\n```text\n/llmiterate          toggle panel\n/llmiterate show     show panel\n/llmiterate hide     hide panel\n/llmiterate status   show panel\n/llmiterate scan     scan all matching files now\n/llmiterate reset    forget processed marker ledger\n/llmiterate reload   reload config + watcher\n```\n\n## Demo\n\n<!-- demo:workflow_suite:start -->\n![Workflow suite](assets/workflow_suite.gif)\n<!-- demo:workflow_suite:end -->\n","readmeFilename":"README.md","_rev":"1-75defed1fd8c6486018b0c8005f36fb3"}