@bybrawe/opencode-loop 0.4.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +784 -672
  3. package/commands/loop-clear.md +2 -2
  4. package/commands/loop-compact.md +2 -2
  5. package/commands/loop-dev.md +2 -2
  6. package/commands/loop-doctor.md +2 -2
  7. package/commands/loop-export.md +2 -2
  8. package/commands/loop-help.md +2 -2
  9. package/commands/loop-init.md +2 -2
  10. package/commands/loop-logs.md +2 -2
  11. package/commands/loop-now.md +2 -2
  12. package/commands/loop-pause.md +2 -2
  13. package/commands/loop-progress.md +2 -2
  14. package/commands/loop-remove.md +2 -2
  15. package/commands/loop-resume.md +2 -2
  16. package/commands/loop-safe-dev.md +2 -2
  17. package/commands/loop-status.md +2 -2
  18. package/commands/loop-stop.md +2 -2
  19. package/commands/loop-testfix.md +2 -2
  20. package/commands/loop.md +2 -2
  21. package/examples/loop-prompt.md +10 -0
  22. package/package.json +9 -5
  23. package/scripts/loopd.mjs +205 -0
  24. package/src/index.js +37 -3
package/README.md CHANGED
@@ -1,706 +1,818 @@
1
- # OpenCode Loop
2
-
3
- **Claude Code style auto-continue for OpenCode.**
4
-
5
- OpenCode Loop adds a practical `/loop` command to OpenCode so an agent can keep working after each idle turn instead of waiting for you to type “continue” again. It is useful for long coding sessions, `progress.md` workflows, TODO automation, test-fix loops, periodic `/compact`, checkpoints, and safe autonomous development.
6
-
7
- Repository: **ByBrawe/opencode-loop**
8
- NPM package name: **@bybrawe/opencode-loop**
9
-
10
- ## Why this exists
11
-
12
- Claude Code users often rely on a loop-like workflow where the agent finishes one step, then immediately continues with the next step. OpenCode is powerful, but long-running autonomous workflows usually need extra control around:
13
-
14
- - auto-continue after idle
15
- - compact / summarize scheduling
16
- - `progress.md` and TODO-driven development
17
- - test verification after each turn
18
- - patch checkpoints
19
- - maximum runtime limits
20
- - failure limits
21
- - safety prompts and destructive command guards
22
-
23
- OpenCode Loop is designed for developers searching for:
24
-
25
- - OpenCode loop
26
- - OpenCode Claude Code loop
27
- - OpenCode auto continue
28
- - OpenCode continue automatically
29
- - OpenCode `/loop` command
30
- - OpenCode compact scheduler
31
- - OpenCode Ralph loop alternative
32
- - Claude Code style loop for OpenCode
33
- - autonomous coding loop for OpenCode
34
- - progress.md TODO automation for OpenCode
35
-
36
- ## Features
37
-
1
+ # OpenCode Loop
2
+
3
+ **Claude Code style auto-continue for OpenCode.**
4
+
5
+ OpenCode Loop adds a practical `/loop` command to OpenCode so an agent can keep working after each idle turn instead of waiting for you to type “continue” again. It is useful for long coding sessions, `progress.md` workflows, TODO automation, test-fix loops, periodic `/compact`, checkpoints, and safe autonomous development.
6
+
7
+ Repository: **ByBrawe/opencode-loop**
8
+ NPM package name: **@bybrawe/opencode-loop**
9
+
10
+ ## Why this exists
11
+
12
+ Claude Code users often rely on a loop-like workflow where the agent finishes one step, then immediately continues with the next step. OpenCode is powerful, but long-running autonomous workflows usually need extra control around:
13
+
14
+ - auto-continue after idle
15
+ - compact / summarize scheduling
16
+ - `progress.md` and TODO-driven development
17
+ - test verification after each turn
18
+ - patch checkpoints
19
+ - maximum runtime limits
20
+ - failure limits
21
+ - safety prompts and destructive command guards
22
+
23
+ OpenCode Loop is designed for developers searching for:
24
+
25
+ - OpenCode loop
26
+ - OpenCode Claude Code loop
27
+ - OpenCode auto continue
28
+ - OpenCode continue automatically
29
+ - OpenCode `/loop` command
30
+ - OpenCode compact scheduler
31
+ - OpenCode Ralph loop alternative
32
+ - Claude Code style loop for OpenCode
33
+ - autonomous coding loop for OpenCode
34
+ - progress.md TODO automation for OpenCode
35
+
36
+ ## Features
37
+
38
+ > Note: The TUI `/loop` command is session-bound. It runs while OpenCode is open and the session receives idle events. If the terminal closes, the machine sleeps, the process is killed, or the provider connection is lost for a long time, the TUI loop cannot continue in the background. For long-running loops, use `opencode-loopd` daemon mode.
39
+
40
+
38
41
  - **Claude Code style auto-continue** with `/loop 0s ...`.
39
- - **Interval loops** for prompts, slash commands, and shell commands.
40
- - **Prompt-file support** with `--prompt-file loop-prompt.md` for long reusable instructions.
41
- - **Include extra context files** with `--include-file`.
42
- - **progress.md workflow** with `--progress-file progress.md`.
43
- - **Large TODO support** with `--batch`.
44
- - **Compact scheduling** with `/loop 200m /compact` or `--compact-every`.
45
- - **Verification loops** with `--verify "npm test"`.
46
- - **Preflight checks** with `--preflight "npm install"`.
47
- - **Post-run commands** with `--postrun`.
48
- - **Failure control** with `--max-failures` and `--pause-on-verify-fail`.
49
- - **Runtime control** with `--max-runtime 6h`.
50
- - **Checkpoints** with `--checkpoint-only` or `--git-checkpoint`.
51
- - **Safe mode** with `--safe` and prompt-level destructive command warnings.
52
- - **Branch setup** with `--branch ai-loop`.
53
- - **Stop controls** with `--stop-file STOP_LOOP`, `--until`, `/loop-stop`, `/loop-pause`, `/loop-resume`, and `/loop-remove`.
54
- - **Watch mode** with `--watch progress.md`.
55
- - **Diagnostics** with `/loop-doctor`.
56
- - **Starter progress file** with `/loop-init`.
57
- - **State export** with `/loop-export`.
58
-
59
- ## Quick start
60
-
61
- ```text
62
- /loop 0s continue from progress.md and implement the next unfinished TODO
63
- ```
64
-
65
- This is the closest behavior to a Claude Code CLI style loop: every time OpenCode becomes idle, the loop can send the next continuation prompt.
66
-
67
- A safer development loop:
68
-
69
- ```text
70
- /loop 0s --name dev --ask-never --safe --no-overlap --batch 5 --compact-every 200m --checkpoint-only --progress-file progress.md Treat progress.md as the main project state file. Continue with the next unfinished TODO, implement it, mark completed items with [x], add useful follow-up TODOs when you discover them, run tests/lint/build when available, and keep going while work remains.
71
- ```
72
-
73
- Periodic compact:
74
-
75
- ```text
76
- /loop 200m --name compact --no-now /compact
77
- ```
78
-
79
- Test-fix loop:
80
-
81
- ```text
82
- /loop 0s --name testfix --ask-never --safe --verify "npm test" Continue from progress.md. If tests fail, analyze the failure, fix it, and run the tests again.
83
- ```
84
-
42
+ - **Background daemon mode** with `opencode-loopd` for long-running loops outside the OpenCode TUI.
43
+ - **Interval loops** for prompts, slash commands, and shell commands.
44
+ - **Prompt-file support** with `--prompt-file loop-prompt.md` for long reusable instructions.
45
+ - **Include extra context files** with `--include-file`.
46
+ - **progress.md workflow** with `--progress-file progress.md`.
47
+ - **Large TODO support** with `--batch`.
48
+ - **Compact scheduling** with `/loop 200m /compact` or `--compact-every`.
49
+ - **Verification loops** with `--verify "npm test"`.
50
+ - **Preflight checks** with `--preflight "npm install"`.
51
+ - **Post-run commands** with `--postrun`.
52
+ - **Failure control** with `--max-failures` and `--pause-on-verify-fail`.
53
+ - **Runtime control** with `--max-runtime 6h`.
54
+ - **Checkpoints** with `--checkpoint-only` or `--git-checkpoint`.
55
+ - **Safe mode** with `--safe` and prompt-level destructive command warnings.
56
+ - **Branch setup** with `--branch ai-loop`.
57
+ - **Stop controls** with `--stop-file STOP_LOOP`, `--until`, `/loop-stop`, `/loop-pause`, `/loop-resume`, and `/loop-remove`.
58
+ - **Watch mode** with `--watch progress.md`.
59
+ - **Diagnostics** with `/loop-doctor`.
60
+ - **Starter progress file** with `/loop-init`.
61
+ - **State export** with `/loop-export`.
62
+
63
+ ## Quick start
64
+
65
+ ```text
66
+ /loop 0s continue from progress.md and implement the next unfinished TODO
67
+ ```
68
+
69
+ This is the closest behavior to a Claude Code CLI style loop: every time OpenCode becomes idle, the loop can send the next continuation prompt.
70
+
71
+ A safer development loop:
72
+
73
+ ```text
74
+ /loop 0s --name dev --ask-never --safe --no-overlap --batch 5 --compact-every 200m --checkpoint-only --progress-file progress.md Treat progress.md as the main project state file. Continue with the next unfinished TODO, implement it, mark completed items with [x], add useful follow-up TODOs when you discover them, run tests/lint/build when available, and keep going while work remains.
75
+ ```
76
+
77
+ Periodic compact:
78
+
79
+ ```text
80
+ /loop 200m --name compact --no-now /compact
81
+ ```
82
+
83
+ Test-fix loop:
84
+
85
+ ```text
86
+ /loop 0s --name testfix --ask-never --safe --verify "npm test" Continue from progress.md. If tests fail, analyze the failure, fix it, and run the tests again.
87
+ ```
88
+
85
89
  Shell command loop:
86
90
 
87
91
  ```text
88
92
  /loop 10m --name tests --safe !npm test
89
93
  ```
90
94
 
91
- ## Installation
92
-
93
- OpenCode Loop can be installed either from this GitHub repository or, after npm publishing, as the scoped npm package `@bybrawe/opencode-loop`.
94
-
95
- OpenCode supports two plugin loading modes:
96
-
97
- - **Local plugin files** placed in `.opencode/plugins/` or `~/.config/opencode/plugins/`.
98
- - **npm package plugins** listed in `opencode.json`.
99
-
100
- This repository is a GitHub repository, so the recommended installation method is the local plugin install below.
101
-
102
- > **Important:** when you use the install script, you do **not** need to add `"plugin": ["@bybrawe/opencode-loop"]` to `opencode.json`. The script installs the local plugin file and command files directly into OpenCode's config directory.
103
-
104
- ### Install from GitHub - Windows PowerShell
105
-
106
- ```powershell
107
- git clone https://github.com/ByBrawe/opencode-loop.git
108
- cd opencode-loop
109
- powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1
110
- ```
111
-
112
- The installer copies:
113
-
114
- ```text
115
- src/index.js -> %USERPROFILE%\.config\opencode\plugins\opencode-loop.js
116
- commands\*.md -> %USERPROFILE%\.config\opencode\commands\
117
- ```
118
-
119
- Then restart OpenCode and run:
120
-
121
- ```text
122
- /loop-help
123
- /loop-doctor
124
- ```
125
-
126
- ### Install from GitHub - macOS / Linux / Git Bash
127
-
128
- ```bash
129
- git clone https://github.com/ByBrawe/opencode-loop.git
130
- cd opencode-loop
131
- chmod +x ./scripts/install.sh
132
- ./scripts/install.sh
133
- ```
134
-
135
- The installer copies:
136
-
137
- ```text
138
- src/index.js -> ~/.config/opencode/plugins/opencode-loop.js
139
- commands/*.md -> ~/.config/opencode/commands/
140
- ```
141
-
142
- Then restart OpenCode and run:
95
+ ## Background daemon
143
96
 
144
- ```text
145
- /loop-help
146
- /loop-doctor
147
- ```
148
-
149
- ### Manual global install
97
+ The `/loop` command is session-bound. It works while OpenCode is open and the current session emits idle/status events.
150
98
 
151
- Windows PowerShell:
99
+ If you close OpenCode, restart the terminal, lose connection, or your PC sleeps, the TUI loop will not keep running.
152
100
 
153
- ```powershell
154
- mkdir "$env:USERPROFILE\.config\opencode\plugins" -Force
155
- mkdir "$env:USERPROFILE\.config\opencode\commands" -Force
156
- copy .\src\index.js "$env:USERPROFILE\.config\opencode\plugins\opencode-loop.js"
157
- copy .\commands\*.md "$env:USERPROFILE\.config\opencode\commands\"
158
- ```
159
-
160
- macOS / Linux:
101
+ For long-running loops, use the daemon:
161
102
 
162
103
  ```bash
163
- mkdir -p ~/.config/opencode/plugins ~/.config/opencode/commands
164
- cp ./src/index.js ~/.config/opencode/plugins/opencode-loop.js
165
- cp ./commands/*.md ~/.config/opencode/commands/
104
+ opencode-loopd --project . --every 5m --prompt-file loop-prompt.md
166
105
  ```
167
106
 
168
- ### Project-local install
169
-
170
- Use this when you want the plugin to be available only inside one repository.
107
+ Run immediately after each OpenCode turn:
171
108
 
172
109
  ```bash
173
- mkdir -p .opencode/plugins .opencode/commands
174
- cp ./src/index.js .opencode/plugins/opencode-loop.js
175
- cp ./commands/*.md .opencode/commands/
176
- ```
177
-
178
- On Windows PowerShell:
179
-
180
- ```powershell
181
- mkdir .opencode\plugins -Force
182
- mkdir .opencode\commands -Force
183
- copy .\src\index.js .opencode\plugins\opencode-loop.js
184
- copy .\commands\*.md .opencode\commands\
185
- ```
186
-
187
- ### npm install - after publishing `@bybrawe/opencode-loop`
188
-
189
- Do **not** use this section for a plain GitHub clone. This is only for the npm package.
190
-
191
- The npm package name is scoped:
192
-
193
- ```text
194
- @bybrawe/opencode-loop
195
- ```
196
-
197
- Recommended npm install command:
198
-
199
- ```bash
200
- npx -y @bybrawe/opencode-loop
201
- ```
202
-
203
- This copies the plugin file and all `/loop-*` markdown command files into your OpenCode config directory, then you restart OpenCode. This is the most reliable install path because OpenCode slash commands are discovered from command files.
204
-
205
- If you only want OpenCode to load the npm plugin package directly, add the scoped package name to your OpenCode config:
206
-
207
- ```json
208
- {
209
- "$schema": "https://opencode.ai/config.json",
210
- "plugin": ["@bybrawe/opencode-loop"]
211
- }
110
+ opencode-loopd --project . --every 0s --prompt "continue from progress.md and implement the next unfinished TODO"
212
111
  ```
213
112
 
214
- Use the scoped name exactly as shown. `opencode-loop` without `@bybrawe/` is a different npm package name.
215
-
216
- To publish this package publicly from an npm account or organization that owns the `bybrawe` scope:
113
+ Limit runs:
217
114
 
218
115
  ```bash
219
- npm publish --access public
220
- ```
221
-
222
- If the package is not published to npm, the config entry above will not install the GitHub repository. Use the GitHub/local install steps instead.
223
-
224
- ### Verify installation
225
-
226
- After restarting OpenCode, run:
227
-
228
- ```text
229
- /loop-help
230
- /loop-doctor
231
- ```
232
-
233
- If the commands do not appear:
234
-
235
- 1. Make sure OpenCode was fully restarted.
236
- 2. Check that `opencode-loop.js` exists in the OpenCode plugin directory.
237
- 3. Check that `loop.md`, `loop-help.md`, and the other command files exist in the OpenCode commands directory.
238
- 4. Run `/loop-doctor` if the command is available.
239
-
240
- ## Core commands
241
-
242
- | Command | Purpose |
243
- |---|---|
244
- | `/loop <interval> <action>` | Add an idle/interval loop job |
245
- | `/loop-help` | Show usage help inside OpenCode |
246
- | `/loop-status` | Show active loop jobs |
247
- | `/loop-logs` | Show recent loop log entries |
248
- | `/loop-now [id/name/number/all]` | Run loop job(s) immediately |
249
- | `/loop-pause [id/name/number/all]` | Pause loop job(s) |
250
- | `/loop-resume [id/name/number/all]` | Resume loop job(s) |
251
- | `/loop-remove [id/name/number/all]` | Remove loop job(s) |
252
- | `/loop-stop [id/name/number/all]` | Alias for remove/stop |
253
- | `/loop-clear` | Remove all loop jobs for the current session |
254
- | `/loop-doctor` | Diagnose plugin/session state |
255
- | `/loop-init [file]` | Create a starter `progress.md` or another progress file |
256
- | `/loop-export` | Export current loop state as JSON |
257
-
258
- ## Preset commands
259
-
260
- | Command | Purpose |
261
- |---|---|
262
- | `/loop-dev 0s` | General autonomous OpenCode development loop |
263
- | `/loop-progress 0s` | Follow `progress.md` and TODOs |
264
- | `/loop-safe-dev 0s` | Safe dev loop with ask-never, batch 5, and patch checkpoints |
265
- | `/loop-testfix 0s "npm test"` | Run, fix, and re-run tests |
266
- | `/loop-compact 200m` | Compact loop shortcut |
267
-
268
- ## Intervals
269
-
270
- ```text
271
- 0s run whenever OpenCode becomes idle, like Claude Code auto-continue
272
- 5m run every 5 minutes when idle
273
- 200m run every 200 minutes when idle
274
- 1h run every hour when idle
275
- ```
276
-
277
- The plugin is **idle-driven**. It checks jobs when OpenCode becomes idle, so it avoids intentionally starting a second agent turn on top of an active one.
278
-
279
- ## Actions
280
-
281
- ### Prompt action
282
-
283
- ```text
284
- /loop 0s continue from progress.md. Work on the next unfinished TODO. Mark completed items with [x].
285
- ```
286
-
287
- ### Prompt file action
288
-
289
- Use this when the prompt is too long for a single command line:
290
-
291
- ```text
292
- /loop 0s --prompt-file loop-prompt.md
116
+ opencode-loopd --project . --every 5m --max-runs 20 --prompt-file loop-prompt.md
293
117
  ```
294
118
 
295
119
  Example `loop-prompt.md`:
296
120
 
297
121
  ```md
298
- Continue from progress.md.
299
- Do not ask questions unless truly blocked.
300
- Make reasonable assumptions and keep working.
301
- Complete TODOs in order and mark finished items with [x].
302
- Add useful follow-up TODOs when you discover them.
303
- Run tests, lint, or build when available.
304
- Do not run destructive commands, force pushes, production deploys, or database resets.
305
- ```
306
-
307
- ### Include extra context files
308
-
309
- ```text
310
- /loop 0s --include-file ARCHITECTURE.md --include-file progress.md continue with the next implementation task
311
- ```
312
-
313
- ### Slash command action
314
-
315
- ```text
316
- /loop 200m /compact
317
- /loop 15m /review current changes
318
- ```
319
-
320
- `/compact` and `/summarize` map to OpenCode session summarization.
321
-
322
- ### Shell action
323
-
324
- ```text
325
- /loop 10m !npm test
326
- /loop 30m $pnpm lint
327
- ```
328
-
329
- Shell actions starting with `!` or `$` run through the OpenCode shell tool.
330
-
331
- ## Flags
332
-
333
- ### `--name <name>`
334
-
335
- Name a loop so you can manage it later.
336
-
337
- ```text
338
- /loop 0s --name dev continue from progress.md
339
- /loop-pause dev
340
- /loop-resume dev
341
- /loop-stop dev
342
- ```
343
-
344
- ### `--max-runs <n>`
345
-
346
- Stop after N runs.
347
-
348
- ```text
349
- /loop 5m --max-runs 20 continue from progress.md
350
- ```
351
-
352
- ### `--max-runtime <duration>`
353
-
354
- Stop after total runtime from loop creation.
355
-
356
- ```text
357
- /loop 0s --max-runtime 6h continue from progress.md
358
- ```
359
-
360
- ### `--timeout <duration>`
361
-
362
- Best-effort abort after a single run timeout.
363
-
364
- ```text
365
- /loop 0s --timeout 30m continue from progress.md
366
- ```
367
-
368
- ### `--max-failures <n>`
369
-
370
- Pause after repeated verify/postrun failures.
371
-
372
- ```text
373
- /loop 0s --verify "npm test" --max-failures 3 continue from progress.md and fix test failures
374
- ```
375
-
376
- ### `--pause-on-verify-fail`
377
-
378
- Pause immediately after the first verify failure.
379
-
380
- ```text
381
- /loop 0s --verify "npm test" --pause-on-verify-fail continue from progress.md
382
- ```
383
-
384
- ### `--until <text>`
385
-
386
- Stop when a marker appears in common state files such as `progress.md`, `TODO.md`, or `.opencode/opencode-loop/until.txt`.
387
-
388
- ```text
389
- /loop 5m --until ALL_DONE continue from progress.md
390
- ```
391
-
392
- ### `--stop-file <file>`
393
-
394
- Stop when a file appears. This is a simple manual kill switch.
395
-
396
- ```text
397
- /loop 0s --stop-file STOP_LOOP continue from progress.md
398
- ```
399
-
400
- Create `STOP_LOOP` in the project root to stop that job.
401
-
402
- ### `--no-overlap` and `--allow-overlap`
403
-
404
- `--no-overlap` is the default. It prevents a new run from being triggered while a previous run is still considered active.
405
-
406
- ```text
407
- /loop 5m --no-overlap continue from progress.md
408
- ```
409
-
410
- ### `--compact-every <n|duration>`
411
-
412
- Compact before a run every N runs or every duration.
413
-
414
- ```text
415
- /loop 0s --compact-every 20 continue from progress.md
416
- /loop 0s --compact-every 200m continue from progress.md
417
- ```
418
-
419
- ### `--test "<command>"`
420
-
421
- Adds a test instruction to prompt actions.
422
-
423
- ```text
424
- /loop 0s --test "npm test" continue from progress.md
425
- ```
426
-
427
- ### `--verify "<command>"`
428
-
429
- Runs a real shell verification command after each assistant turn. If it fails, the next loop prompt includes the failure summary so the agent can fix it.
430
-
431
- ```text
432
- /loop 0s --verify "npm test" continue from progress.md and fix any failing tests
433
- ```
434
-
435
- ### `--preflight "<command>"`
436
-
437
- Runs a real shell command before each loop turn. If it fails, the loop pauses.
438
-
439
- ```text
440
- /loop 0s --preflight "npm install" continue from progress.md
441
- ```
442
-
443
- ### `--postrun "<command>"`
444
-
445
- Runs a shell command after each assistant turn and verification.
446
-
447
- ```text
448
- /loop 0s --postrun "git status --short" continue from progress.md
449
- ```
450
-
451
- ### `--notify "<command>"`
452
-
453
- Runs a shell command when a loop stops or pauses due to a control condition. The command can use `{job}` and `{reason}` placeholders.
454
-
455
- ```text
456
- /loop 0s --max-runtime 6h --notify "echo {job} stopped because {reason}" continue from progress.md
457
- ```
458
-
459
- ### `--checkpoint-only`
460
-
461
- Save `git status` and `git diff --binary` snapshots under:
462
-
463
- ```text
464
- .opencode/opencode-loop/checkpoints/<session>/
465
- ```
466
-
467
- ### `--git-checkpoint`
468
-
469
- Save a patch checkpoint and attempt to commit all changes after each completed run.
470
-
471
- ```text
472
- /loop 0s --git-checkpoint continue from progress.md
473
- ```
474
-
475
- Use carefully. It runs `git add -A` and `git commit` when changes exist.
476
-
477
- ### `--branch <name>`
478
-
479
- Switch to a branch before the first run, or create it if it does not exist.
480
-
481
- ```text
482
- /loop 0s --branch ai-loop continue from progress.md
483
- ```
484
-
485
- ### `--safe`
486
-
487
- Adds safety instructions to prompt actions and blocks obviously destructive shell actions.
488
-
489
- ```text
490
- /loop 0s --safe continue from progress.md
491
- ```
492
-
493
- Safe mode warns against or blocks patterns such as `git reset`, `git clean`, `rm -rf`, `git push`, `terraform destroy`, destructive delete commands, and production deploys.
494
-
495
- ### `--batch <n>`
496
-
497
- Tell the agent to process at most N TODO items per run.
498
-
499
- ```text
500
- /loop 0s --batch 5 continue from progress.md
501
- ```
502
-
503
- ### `--quiet`
504
-
505
- Tell the agent to keep replies short.
506
-
507
- ```text
508
- /loop 0s --quiet continue from progress.md
509
- ```
510
-
511
- ### `--ask-never`
512
-
513
- Tell the agent not to ask questions and to make reasonable assumptions.
514
-
515
- ```text
516
- /loop 0s --ask-never continue from progress.md
517
- ```
518
-
519
- ### `--progress-file <file>`
520
-
521
- Tell the agent which state file to treat as the main progress/TODO source.
522
-
523
- ```text
524
- /loop 0s --progress-file progress.md continue from the progress file
525
- ```
526
-
527
- ### `--watch <file>`
528
-
529
- Run when watched file metadata changes. This is still checked on idle events.
530
-
531
- ```text
532
- /loop --watch progress.md continue after progress.md changes
533
- /loop 5m --watch progress.md continue when progress.md changes or the interval is due
534
- ```
535
-
536
- You can pass multiple `--watch` flags.
537
-
538
- ### `--dry-run`
539
-
540
- Parse and preview a loop without saving it.
541
-
542
- ```text
543
- /loop 0s --dry-run --ask-never continue from progress.md
544
- ```
545
-
546
- ### `--now` and `--no-now`
547
-
548
- By default a new loop is due immediately. Use `--no-now` to wait for the first interval.
549
-
550
- ```text
551
- /loop 200m --no-now /compact
552
- ```
553
-
554
- ## Recommended recipes
555
-
556
- ### Claude Code style auto-continue loop
557
-
558
- ```text
559
- /loop 0s --name dev --ask-never --safe --no-overlap --batch 5 --compact-every 200m --checkpoint-only --progress-file progress.md Treat progress.md as the main project state file. Continue with the next unfinished TODO, implement it, mark completed items with [x], add useful follow-up TODOs when you discover them, run tests/lint/build when available, and keep going while work remains.
560
- ```
561
-
562
- ### Long-running autonomous development loop
563
-
564
- ```text
565
- /loop 0s --name dev --ask-never --safe --no-overlap --compact-every 20 --timeout 45m --max-runtime 6h --max-failures 3 --stop-file STOP_LOOP --checkpoint-only Continue from progress.md. Do not ask questions. Make reasonable assumptions. Complete TODOs in order, mark finished items with [x], add useful new ideas to progress.md, and keep going while work remains.
566
- ```
567
-
568
- ### Test-fix loop
569
-
570
- ```text
571
- /loop 0s --name testfix --ask-never --safe --verify "npm test" --max-failures 3 Continue from progress.md. If tests fail, analyze the failure, fix it, and run the tests again.
572
- ```
573
-
574
- ### Compact loop
575
-
576
- ```text
577
- /loop 200m --name compact --no-now /compact
578
- ```
579
-
580
- ### Prompt file loop
581
-
582
- ```text
583
- /loop 0s --name dev --prompt-file loop-prompt.md --checkpoint-only --max-runtime 6h
584
- ```
585
-
586
- ## Suggested OpenCode permission config
587
-
588
- Full `permission: "allow"` is convenient but risky. For safer long loops, keep destructive commands as ask/deny.
589
-
590
- ```json
591
- {
592
- "$schema": "https://opencode.ai/config.json",
593
- "permission": {
594
- "read": "allow",
595
- "grep": "allow",
596
- "glob": "allow",
597
- "todowrite": "allow",
598
- "edit": "allow",
599
- "bash": {
600
- "*": "ask",
601
- "git status*": "allow",
602
- "git diff*": "allow",
603
- "npm test*": "allow",
604
- "npm run test*": "allow",
605
- "npm run lint*": "allow",
606
- "pnpm test*": "allow",
607
- "pnpm lint*": "allow",
608
- "git push*": "ask",
609
- "git reset*": "ask",
610
- "git clean*": "deny",
611
- "rm *": "deny",
612
- "del *": "ask",
613
- "rmdir *": "ask"
614
- },
615
- "external_directory": "ask"
616
- }
617
- }
618
- ```
619
-
620
- ## State files
621
-
622
- Session loop state is stored under:
623
-
624
- ```text
625
- .opencode/opencode-loop/
626
- ```
627
-
628
- Patch checkpoints are stored under:
629
-
630
- ```text
631
- .opencode/opencode-loop/checkpoints/
632
- ```
633
-
634
- Recent plugin events are appended to:
635
-
636
- ```text
637
- .opencode/opencode-loop/loop.log
638
- ```
639
-
640
- ## Example progress.md
641
-
642
- Create one with:
643
-
644
- ```text
645
- /loop-init
646
- ```
647
-
648
- Example content:
649
-
650
- ```md
651
- # Progress
122
+ Continue from progress.md and implement the next unfinished TODO.
652
123
 
653
- ## Current Goal
654
- Improve the application in small safe steps.
655
-
656
- ## Agent Rules
657
- - Do not ask questions unless truly blocked.
658
- - Make reasonable assumptions and continue.
659
- - Work on unfinished TODOs in order.
660
- - Mark completed TODOs with [x].
661
- - Add new bugs, ideas, or follow-up tasks as TODOs.
124
+ Rules:
125
+ - Do not ask questions.
126
+ - Make reasonable assumptions.
127
+ - Mark completed TODO items with [x].
128
+ - Add useful follow-up TODOs when needed.
662
129
  - Run tests/lint/build when available.
663
- - Do not run destructive commands, force pushes, production deploys, or database resets.
664
-
665
- ## Active TODO
666
- - [ ] Review the project structure and identify the next safe improvement.
667
- - [ ] Fix the highest-priority failing test.
668
- - [ ] Improve the user-facing error state in the main flow.
669
-
670
- ## Completed
671
- - [x] Added initial project notes.
672
-
673
- ## Backlog Ideas
674
- - [ ] Add a smoke test for the critical path.
675
- - [ ] Improve developer setup documentation.
676
-
677
- ## Blocked
678
- - None.
130
+ - Do not run destructive commands such as git reset, git clean, rm -rf, force push, deploy, or production migrations.
131
+ - Keep going while work remains.
679
132
  ```
680
133
 
681
- ## Bug fixes and hardening in v0.4.0
134
+ ### Windows Task Scheduler
682
135
 
683
- - Renamed the public package/repo metadata to `opencode-loop` for `ByBrawe/opencode-loop`.
684
- - Replaced project-specific examples with public, English OpenCode examples.
685
- - Added `--prompt-file` for long prompts instead of huge command lines.
686
- - Added `--include-file` for extra context files.
687
- - Added `--max-runtime` so loops can stop after a total runtime.
688
- - Added `--max-failures` and `--pause-on-verify-fail` for failing verification loops.
689
- - Added `--postrun` and `--notify` hooks.
690
- - Added `/loop-doctor`, `/loop-init`, and `/loop-export`.
691
- - Fixed the max-runs/checkpoint ordering issue so the last run can still finalize and checkpoint.
692
- - Improved no-overlap behavior and state cleanup for non-assistant actions such as `/compact`.
693
- - Kept all README examples in English for public GitHub discovery.
136
+ You can create a Windows scheduled task that runs a one-shot daemon job every N minutes:
694
137
 
695
- ## Notes and limits
138
+ ```powershell
139
+ opencode-loopd install-task --project "C:\path\to\project" --every 10m --prompt-file loop-prompt.md --name OpenCodeLoop
140
+ ```
696
141
 
697
- - The plugin is idle-driven. It does not run a background daemon while OpenCode is busy.
698
- - `--timeout` is best-effort and relies on OpenCode's abort API.
699
- - `--verify`, `--preflight`, `--postrun`, and `--notify` run shell commands, so configure OpenCode permissions carefully.
700
- - `--until` scans common state files and a limited number of markdown/text/json/yaml files to avoid walking huge projects.
701
- - `--safe` reduces risk but does not replace careful OpenCode permissions.
702
- - For truly unattended multi-hour work, use a disposable branch or worktree and checkpoint patches.
142
+ Remove it:
703
143
 
704
- ## License
144
+ ```powershell
145
+ opencode-loopd uninstall-task --name OpenCodeLoop
146
+ ```
147
+
148
+ For active development, a visible terminal running `opencode-loopd --project . --every 0s ...` is easier to monitor.
149
+
150
+
151
+ ## Installation
152
+
153
+ ### Recommended: install from npm
154
+
155
+ Install from npm with `npx`:
156
+
157
+ ```bash
158
+ npx -y @bybrawe/opencode-loop
159
+ ```
160
+
161
+ On Windows CMD:
162
+
163
+ ```bat
164
+ npx -y @bybrawe/opencode-loop
165
+ ```
166
+
167
+ On Windows PowerShell:
168
+
169
+ ```powershell
170
+ npx -y @bybrawe/opencode-loop
171
+ ```
172
+
173
+ The installer copies the plugin and slash command files into your OpenCode config directory.
174
+
175
+ Windows target paths:
176
+
177
+ ```text
178
+ %USERPROFILE%\.config\opencode\plugins\opencode-loop.js
179
+ %USERPROFILE%\.config\opencode\commands\loop*.md
180
+ ```
181
+
182
+ macOS / Linux target paths:
183
+
184
+ ```text
185
+ ~/.config/opencode/plugins/opencode-loop.js
186
+ ~/.config/opencode/commands/loop*.md
187
+ ```
188
+
189
+ Then fully restart OpenCode and run:
190
+
191
+ ```text
192
+ /loop-help
193
+ /loop-doctor
194
+ ```
195
+
196
+ The npm package also installs the `opencode-loopd` CLI for background loops:
705
197
 
706
- MIT
198
+ ```bash
199
+ opencode-loopd --help
200
+ ```
201
+
202
+ ### Why `npx` is the recommended npm install
203
+
204
+ OpenCode can load npm plugins from the `plugin` array in `opencode.json`, but OpenCode slash commands are discovered from command definitions such as markdown files in a `commands/` directory or command entries in config. The `npx` installer installs both parts: the plugin file and the `/loop-*` command files.
205
+
206
+ Use the OpenCode config-only method only if you already installed the command files separately or you are only testing plugin loading.
207
+
208
+ ### Optional: OpenCode config package entry
209
+
210
+ If you want OpenCode to load the npm plugin package directly, add the scoped package name to your OpenCode config:
211
+
212
+ ```json
213
+ {
214
+ "$schema": "https://opencode.ai/config.json",
215
+ "plugin": ["@bybrawe/opencode-loop"]
216
+ }
217
+ ```
218
+
219
+ Use the scoped package name exactly as shown. `opencode-loop` without `@bybrawe/` is a different npm package name.
220
+
221
+ If `/loop` does not appear after using only the config method, run the installer once:
222
+
223
+ ```bash
224
+ npx -y @bybrawe/opencode-loop
225
+ ```
226
+
227
+ ### Install from GitHub
228
+
229
+ Use this if you want to install from source instead of npm.
230
+
231
+ Windows PowerShell:
232
+
233
+ ```powershell
234
+ git clone https://github.com/ByBrawe/opencode-loop.git
235
+ cd opencode-loop
236
+ powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1
237
+ ```
238
+
239
+ macOS / Linux / Git Bash:
240
+
241
+ ```bash
242
+ git clone https://github.com/ByBrawe/opencode-loop.git
243
+ cd opencode-loop
244
+ chmod +x ./scripts/install.sh
245
+ ./scripts/install.sh
246
+ ```
247
+
248
+ Then restart OpenCode and run:
249
+
250
+ ```text
251
+ /loop-help
252
+ /loop-doctor
253
+ ```
254
+
255
+ ### Manual global install
256
+
257
+ Windows PowerShell:
258
+
259
+ ```powershell
260
+ mkdir "$env:USERPROFILE\.config\opencode\plugins" -Force
261
+ mkdir "$env:USERPROFILE\.config\opencode\commands" -Force
262
+ copy .\src\index.js "$env:USERPROFILE\.config\opencode\plugins\opencode-loop.js"
263
+ copy .\commands\*.md "$env:USERPROFILE\.config\opencode\commands\"
264
+ ```
265
+
266
+ macOS / Linux:
267
+
268
+ ```bash
269
+ mkdir -p ~/.config/opencode/plugins ~/.config/opencode/commands
270
+ cp ./src/index.js ~/.config/opencode/plugins/opencode-loop.js
271
+ cp ./commands/*.md ~/.config/opencode/commands/
272
+ ```
273
+
274
+ ### Project-local install
275
+
276
+ Use this when you want the plugin to be available only inside one repository.
277
+
278
+ ```bash
279
+ mkdir -p .opencode/plugins .opencode/commands
280
+ cp ./src/index.js .opencode/plugins/opencode-loop.js
281
+ cp ./commands/*.md .opencode/commands/
282
+ ```
283
+
284
+ On Windows PowerShell:
285
+
286
+ ```powershell
287
+ mkdir .opencode\plugins -Force
288
+ mkdir .opencode\commands -Force
289
+ copy .\src\index.js .opencode\plugins\opencode-loop.js
290
+ copy .\commands\*.md .opencode\commands\
291
+ ```
292
+
293
+ <<<<<<< HEAD
294
+ =======
295
+ ### npm install - after publishing `@bybrawe/opencode-loop`
296
+
297
+ Do **not** use this section for a plain GitHub clone. This is only for the npm package.
298
+
299
+ The npm package name is scoped:
300
+
301
+ ```text
302
+ @bybrawe/opencode-loop
303
+ ```
304
+
305
+ Recommended npm install command:
306
+
307
+ ```bash
308
+ npx -y @bybrawe/opencode-loop
309
+ ```
310
+
311
+ This copies the plugin file and all `/loop-*` markdown command files into your OpenCode config directory, then you restart OpenCode. This is the most reliable install path because OpenCode slash commands are discovered from command files.
312
+
313
+ If you only want OpenCode to load the npm plugin package directly, add the scoped package name to your OpenCode config:
314
+
315
+ ```json
316
+ {
317
+ "$schema": "https://opencode.ai/config.json",
318
+ "plugin": ["@bybrawe/opencode-loop"]
319
+ }
320
+ ```
321
+
322
+
323
+ >>>>>>> 600c1cf8146d317efd682e20298f53c0cf2bf213
324
+ ### Verify installation
325
+
326
+ After restarting OpenCode, run:
327
+
328
+ ```text
329
+ /loop-help
330
+ /loop-doctor
331
+ ```
332
+
333
+ If the commands do not appear:
334
+
335
+ 1. Make sure OpenCode was fully restarted.
336
+ 2. Check that `opencode-loop.js` exists in the OpenCode plugin directory.
337
+ 3. Check that `loop.md`, `loop-help.md`, and the other command files exist in the OpenCode commands directory.
338
+ 4. Run `npx -y @bybrawe/opencode-loop` again to reinstall the command files.
339
+
340
+ ## Multiple loops and duplicate protection
341
+
342
+ By default, `/loop ...` uses an upsert/replace behavior. Running `/loop 5m ...` again replaces the existing default loop instead of creating duplicate jobs.
343
+
344
+ Use `--name` to manage separate named loops, or `--multi` when you intentionally want multiple loops with the same shape:
345
+
346
+ ```text
347
+ /loop 5m --name dev continue from progress.md
348
+ /loop 200m --name compact /compact
349
+ /loop 10m --multi !npm test
350
+ ```
351
+
352
+ ## Core commands
353
+
354
+ | Command | Purpose |
355
+ |---|---|
356
+ | `/loop <interval> <action>` | Add an idle/interval loop job |
357
+ | `/loop-help` | Show usage help inside OpenCode |
358
+ | `/loop-status` | Show active loop jobs |
359
+ | `/loop-logs` | Show recent loop log entries |
360
+ | `/loop-now [id/name/number/all]` | Run loop job(s) immediately |
361
+ | `/loop-pause [id/name/number/all]` | Pause loop job(s) |
362
+ | `/loop-resume [id/name/number/all]` | Resume loop job(s) |
363
+ | `/loop-remove [id/name/number/all]` | Remove loop job(s) |
364
+ | `/loop-stop [id/name/number/all]` | Alias for remove/stop |
365
+ | `/loop-clear` | Remove all loop jobs for the current session |
366
+ | `/loop-doctor` | Diagnose plugin/session state |
367
+ | `/loop-init [file]` | Create a starter `progress.md` or another progress file |
368
+ | `/loop-export` | Export current loop state as JSON |
369
+
370
+ ## Preset commands
371
+
372
+ | Command | Purpose |
373
+ |---|---|
374
+ | `/loop-dev 0s` | General autonomous OpenCode development loop |
375
+ | `/loop-progress 0s` | Follow `progress.md` and TODOs |
376
+ | `/loop-safe-dev 0s` | Safe dev loop with ask-never, batch 5, and patch checkpoints |
377
+ | `/loop-testfix 0s "npm test"` | Run, fix, and re-run tests |
378
+ | `/loop-compact 200m` | Compact loop shortcut |
379
+
380
+ ## Intervals
381
+
382
+ ```text
383
+ 0s run whenever OpenCode becomes idle, like Claude Code auto-continue
384
+ 5m run every 5 minutes when idle
385
+ 200m run every 200 minutes when idle
386
+ 1h run every hour when idle
387
+ ```
388
+
389
+ The plugin is **idle-driven**. It checks jobs when OpenCode becomes idle, so it avoids intentionally starting a second agent turn on top of an active one.
390
+
391
+ ## Actions
392
+
393
+ ### Prompt action
394
+
395
+ ```text
396
+ /loop 0s continue from progress.md. Work on the next unfinished TODO. Mark completed items with [x].
397
+ ```
398
+
399
+ ### Prompt file action
400
+
401
+ Use this when the prompt is too long for a single command line:
402
+
403
+ ```text
404
+ /loop 0s --prompt-file loop-prompt.md
405
+ ```
406
+
407
+ Example `loop-prompt.md`:
408
+
409
+ ```md
410
+ Continue from progress.md.
411
+ Do not ask questions unless truly blocked.
412
+ Make reasonable assumptions and keep working.
413
+ Complete TODOs in order and mark finished items with [x].
414
+ Add useful follow-up TODOs when you discover them.
415
+ Run tests, lint, or build when available.
416
+ Do not run destructive commands, force pushes, production deploys, or database resets.
417
+ ```
418
+
419
+ ### Include extra context files
420
+
421
+ ```text
422
+ /loop 0s --include-file ARCHITECTURE.md --include-file progress.md continue with the next implementation task
423
+ ```
424
+
425
+ ### Slash command action
426
+
427
+ ```text
428
+ /loop 200m /compact
429
+ /loop 15m /review current changes
430
+ ```
431
+
432
+ `/compact` and `/summarize` map to OpenCode session summarization.
433
+
434
+ ### Shell action
435
+
436
+ ```text
437
+ /loop 10m !npm test
438
+ /loop 30m $pnpm lint
439
+ ```
440
+
441
+ Shell actions starting with `!` or `$` run through the OpenCode shell tool.
442
+
443
+ ## Flags
444
+
445
+ ### `--name <name>`
446
+
447
+ Name a loop so you can manage it later.
448
+
449
+ ```text
450
+ /loop 0s --name dev continue from progress.md
451
+ /loop-pause dev
452
+ /loop-resume dev
453
+ /loop-stop dev
454
+ ```
455
+
456
+ ### `--max-runs <n>`
457
+
458
+ Stop after N runs.
459
+
460
+ ```text
461
+ /loop 5m --max-runs 20 continue from progress.md
462
+ ```
463
+
464
+ ### `--max-runtime <duration>`
465
+
466
+ Stop after total runtime from loop creation.
467
+
468
+ ```text
469
+ /loop 0s --max-runtime 6h continue from progress.md
470
+ ```
471
+
472
+ ### `--timeout <duration>`
473
+
474
+ Best-effort abort after a single run timeout.
475
+
476
+ ```text
477
+ /loop 0s --timeout 30m continue from progress.md
478
+ ```
479
+
480
+ ### `--max-failures <n>`
481
+
482
+ Pause after repeated verify/postrun failures.
483
+
484
+ ```text
485
+ /loop 0s --verify "npm test" --max-failures 3 continue from progress.md and fix test failures
486
+ ```
487
+
488
+ ### `--pause-on-verify-fail`
489
+
490
+ Pause immediately after the first verify failure.
491
+
492
+ ```text
493
+ /loop 0s --verify "npm test" --pause-on-verify-fail continue from progress.md
494
+ ```
495
+
496
+ ### `--until <text>`
497
+
498
+ Stop when a marker appears in common state files such as `progress.md`, `TODO.md`, or `.opencode/opencode-loop/until.txt`.
499
+
500
+ ```text
501
+ /loop 5m --until ALL_DONE continue from progress.md
502
+ ```
503
+
504
+ ### `--stop-file <file>`
505
+
506
+ Stop when a file appears. This is a simple manual kill switch.
507
+
508
+ ```text
509
+ /loop 0s --stop-file STOP_LOOP continue from progress.md
510
+ ```
511
+
512
+ Create `STOP_LOOP` in the project root to stop that job.
513
+
514
+ ### `--no-overlap` and `--allow-overlap`
515
+
516
+ `--no-overlap` is the default. It prevents a new run from being triggered while a previous run is still considered active.
517
+
518
+ ```text
519
+ /loop 5m --no-overlap continue from progress.md
520
+ ```
521
+
522
+ ### `--compact-every <n|duration>`
523
+
524
+ Compact before a run every N runs or every duration.
525
+
526
+ ```text
527
+ /loop 0s --compact-every 20 continue from progress.md
528
+ /loop 0s --compact-every 200m continue from progress.md
529
+ ```
530
+
531
+ ### `--test "<command>"`
532
+
533
+ Adds a test instruction to prompt actions.
534
+
535
+ ```text
536
+ /loop 0s --test "npm test" continue from progress.md
537
+ ```
538
+
539
+ ### `--verify "<command>"`
540
+
541
+ Runs a real shell verification command after each assistant turn. If it fails, the next loop prompt includes the failure summary so the agent can fix it.
542
+
543
+ ```text
544
+ /loop 0s --verify "npm test" continue from progress.md and fix any failing tests
545
+ ```
546
+
547
+ ### `--preflight "<command>"`
548
+
549
+ Runs a real shell command before each loop turn. If it fails, the loop pauses.
550
+
551
+ ```text
552
+ /loop 0s --preflight "npm install" continue from progress.md
553
+ ```
554
+
555
+ ### `--postrun "<command>"`
556
+
557
+ Runs a shell command after each assistant turn and verification.
558
+
559
+ ```text
560
+ /loop 0s --postrun "git status --short" continue from progress.md
561
+ ```
562
+
563
+ ### `--notify "<command>"`
564
+
565
+ Runs a shell command when a loop stops or pauses due to a control condition. The command can use `{job}` and `{reason}` placeholders.
566
+
567
+ ```text
568
+ /loop 0s --max-runtime 6h --notify "echo {job} stopped because {reason}" continue from progress.md
569
+ ```
570
+
571
+ ### `--checkpoint-only`
572
+
573
+ Save `git status` and `git diff --binary` snapshots under:
574
+
575
+ ```text
576
+ .opencode/opencode-loop/checkpoints/<session>/
577
+ ```
578
+
579
+ ### `--git-checkpoint`
580
+
581
+ Save a patch checkpoint and attempt to commit all changes after each completed run.
582
+
583
+ ```text
584
+ /loop 0s --git-checkpoint continue from progress.md
585
+ ```
586
+
587
+ Use carefully. It runs `git add -A` and `git commit` when changes exist.
588
+
589
+ ### `--branch <name>`
590
+
591
+ Switch to a branch before the first run, or create it if it does not exist.
592
+
593
+ ```text
594
+ /loop 0s --branch ai-loop continue from progress.md
595
+ ```
596
+
597
+ ### `--safe`
598
+
599
+ Adds safety instructions to prompt actions and blocks obviously destructive shell actions.
600
+
601
+ ```text
602
+ /loop 0s --safe continue from progress.md
603
+ ```
604
+
605
+ Safe mode warns against or blocks patterns such as `git reset`, `git clean`, `rm -rf`, `git push`, `terraform destroy`, destructive delete commands, and production deploys.
606
+
607
+ ### `--batch <n>`
608
+
609
+ Tell the agent to process at most N TODO items per run.
610
+
611
+ ```text
612
+ /loop 0s --batch 5 continue from progress.md
613
+ ```
614
+
615
+ ### `--quiet`
616
+
617
+ Tell the agent to keep replies short.
618
+
619
+ ```text
620
+ /loop 0s --quiet continue from progress.md
621
+ ```
622
+
623
+ ### `--ask-never`
624
+
625
+ Tell the agent not to ask questions and to make reasonable assumptions.
626
+
627
+ ```text
628
+ /loop 0s --ask-never continue from progress.md
629
+ ```
630
+
631
+ ### `--progress-file <file>`
632
+
633
+ Tell the agent which state file to treat as the main progress/TODO source.
634
+
635
+ ```text
636
+ /loop 0s --progress-file progress.md continue from the progress file
637
+ ```
638
+
639
+ ### `--watch <file>`
640
+
641
+ Run when watched file metadata changes. This is still checked on idle events.
642
+
643
+ ```text
644
+ /loop --watch progress.md continue after progress.md changes
645
+ /loop 5m --watch progress.md continue when progress.md changes or the interval is due
646
+ ```
647
+
648
+ You can pass multiple `--watch` flags.
649
+
650
+ ### `--dry-run`
651
+
652
+ Parse and preview a loop without saving it.
653
+
654
+ ```text
655
+ /loop 0s --dry-run --ask-never continue from progress.md
656
+ ```
657
+
658
+ ### `--now` and `--no-now`
659
+
660
+ By default a new loop is due immediately. Use `--no-now` to wait for the first interval.
661
+
662
+ ```text
663
+ /loop 200m --no-now /compact
664
+ ```
665
+
666
+ ## Recommended recipes
667
+
668
+ ### Claude Code style auto-continue loop
669
+
670
+ ```text
671
+ /loop 0s --name dev --ask-never --safe --no-overlap --batch 5 --compact-every 200m --checkpoint-only --progress-file progress.md Treat progress.md as the main project state file. Continue with the next unfinished TODO, implement it, mark completed items with [x], add useful follow-up TODOs when you discover them, run tests/lint/build when available, and keep going while work remains.
672
+ ```
673
+
674
+ ### Long-running autonomous development loop
675
+
676
+ ```text
677
+ /loop 0s --name dev --ask-never --safe --no-overlap --compact-every 20 --timeout 45m --max-runtime 6h --max-failures 3 --stop-file STOP_LOOP --checkpoint-only Continue from progress.md. Do not ask questions. Make reasonable assumptions. Complete TODOs in order, mark finished items with [x], add useful new ideas to progress.md, and keep going while work remains.
678
+ ```
679
+
680
+ ### Test-fix loop
681
+
682
+ ```text
683
+ /loop 0s --name testfix --ask-never --safe --verify "npm test" --max-failures 3 Continue from progress.md. If tests fail, analyze the failure, fix it, and run the tests again.
684
+ ```
685
+
686
+ ### Compact loop
687
+
688
+ ```text
689
+ /loop 200m --name compact --no-now /compact
690
+ ```
691
+
692
+ ### Prompt file loop
693
+
694
+ ```text
695
+ /loop 0s --name dev --prompt-file loop-prompt.md --checkpoint-only --max-runtime 6h
696
+ ```
697
+
698
+ ## Suggested OpenCode permission config
699
+
700
+ Full `permission: "allow"` is convenient but risky. For safer long loops, keep destructive commands as ask/deny.
701
+
702
+ ```json
703
+ {
704
+ "$schema": "https://opencode.ai/config.json",
705
+ "permission": {
706
+ "read": "allow",
707
+ "grep": "allow",
708
+ "glob": "allow",
709
+ "todowrite": "allow",
710
+ "edit": "allow",
711
+ "bash": {
712
+ "*": "ask",
713
+ "git status*": "allow",
714
+ "git diff*": "allow",
715
+ "npm test*": "allow",
716
+ "npm run test*": "allow",
717
+ "npm run lint*": "allow",
718
+ "pnpm test*": "allow",
719
+ "pnpm lint*": "allow",
720
+ "git push*": "ask",
721
+ "git reset*": "ask",
722
+ "git clean*": "deny",
723
+ "rm *": "deny",
724
+ "del *": "ask",
725
+ "rmdir *": "ask"
726
+ },
727
+ "external_directory": "ask"
728
+ }
729
+ }
730
+ ```
731
+
732
+ ## State files
733
+
734
+ Session loop state is stored under:
735
+
736
+ ```text
737
+ .opencode/opencode-loop/
738
+ ```
739
+
740
+ Patch checkpoints are stored under:
741
+
742
+ ```text
743
+ .opencode/opencode-loop/checkpoints/
744
+ ```
745
+
746
+ Recent plugin events are appended to:
747
+
748
+ ```text
749
+ .opencode/opencode-loop/loop.log
750
+ ```
751
+
752
+ ## Example progress.md
753
+
754
+ Create one with:
755
+
756
+ ```text
757
+ /loop-init
758
+ ```
759
+
760
+ Example content:
761
+
762
+ ```md
763
+ # Progress
764
+
765
+ ## Current Goal
766
+ Improve the application in small safe steps.
767
+
768
+ ## Agent Rules
769
+ - Do not ask questions unless truly blocked.
770
+ - Make reasonable assumptions and continue.
771
+ - Work on unfinished TODOs in order.
772
+ - Mark completed TODOs with [x].
773
+ - Add new bugs, ideas, or follow-up tasks as TODOs.
774
+ - Run tests/lint/build when available.
775
+ - Do not run destructive commands, force pushes, production deploys, or database resets.
776
+
777
+ ## Active TODO
778
+ - [ ] Review the project structure and identify the next safe improvement.
779
+ - [ ] Fix the highest-priority failing test.
780
+ - [ ] Improve the user-facing error state in the main flow.
781
+
782
+ ## Completed
783
+ - [x] Added initial project notes.
784
+
785
+ ## Backlog Ideas
786
+ - [ ] Add a smoke test for the critical path.
787
+ - [ ] Improve developer setup documentation.
788
+
789
+ ## Blocked
790
+ - None.
791
+ ```
792
+
793
+ ## Bug fixes and hardening in v0.4.0
794
+
795
+ - Renamed the public package/repo metadata to `opencode-loop` for `ByBrawe/opencode-loop`.
796
+ - Replaced project-specific examples with public, English OpenCode examples.
797
+ - Added `--prompt-file` for long prompts instead of huge command lines.
798
+ - Added `--include-file` for extra context files.
799
+ - Added `--max-runtime` so loops can stop after a total runtime.
800
+ - Added `--max-failures` and `--pause-on-verify-fail` for failing verification loops.
801
+ - Added `--postrun` and `--notify` hooks.
802
+ - Added `/loop-doctor`, `/loop-init`, and `/loop-export`.
803
+ - Fixed the max-runs/checkpoint ordering issue so the last run can still finalize and checkpoint.
804
+ - Improved no-overlap behavior and state cleanup for non-assistant actions such as `/compact`.
805
+ - Kept all README examples in English for public GitHub discovery.
806
+
807
+ ## Notes and limits
808
+
809
+ - The plugin is idle-driven. It does not run a background daemon while OpenCode is busy.
810
+ - `--timeout` is best-effort and relies on OpenCode's abort API.
811
+ - `--verify`, `--preflight`, `--postrun`, and `--notify` run shell commands, so configure OpenCode permissions carefully.
812
+ - `--until` scans common state files and a limited number of markdown/text/json/yaml files to avoid walking huge projects.
813
+ - `--safe` reduces risk but does not replace careful OpenCode permissions.
814
+ - For truly unattended multi-hour work, use a disposable branch or worktree and checkpoint patches.
815
+
816
+ ## License
817
+
818
+ MIT