docs(coding-agents): say which harnesses retainEveryTurns applies to - #3380
Merged
Conversation
It has exactly one consumer, RuntimeCore — the persistent-plugin harnesses
(opencode, Kilo, Cline CLI), which stay loaded and therefore choose when to write
back. The hook harnesses ignore it, and not by oversight: the host decides when
they run, and each Stop is a fresh process with no memory of how many turns have
passed.
Neither the config comment nor the settings table said so. Its neighbour
retainSessions does spell out the same split ("hook harnesses always write on
Stop"), so the silence read as "applies everywhere" — a Claude Code user setting
retainEveryTurns: 5 gets no effect and no warning. That is the workaround #2143's
reporter reached for, so the gap was load-bearing.
The README also said "opencode", which undersold it: Kilo and Cline CLI share
that runtime.
nicoloboschi
added a commit
that referenced
this pull request
Aug 12, 2026
I committed this in #3380 and it has been on main since, in the v0.2.0 and v0.2.1 tags: a symlink at hindsight-integrations/coding-agents/node_modules pointing at an absolute path on my own machine. Anyone cloning gets a dangling link where the package's node_modules belongs. The published npm tarballs are unaffected — npm excludes node_modules from packs — so this is repository hygiene, not a shipped defect. .gitignore had `node_modules/`, which matches directories only. A symlink is a file, so it slipped straight past — which is exactly how it got committed, since pointing a scratch worktree at an already-installed node_modules is the fast way to run this package's tests. Adding the slashless pattern closes that.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fell out of triaging #2143.
retainEveryTurnshas exactly one consumer:RuntimeCoreis the persistent-plugin path — opencode, Kilo, Cline CLI. Those hosts load the plugin once and keep it alive, so it chooses when to write back, and a cadence is the only thing stopping a write every turn.The hook harnesses (claude-code, codex, cursor-cli, copilot-cli, grok-build, antigravity, devin) never consult it, and that's structural rather than an oversight: the host decides when they run, and each Stop is a fresh process with no memory of how many turns have passed.
Neither the config comment nor the settings table said any of this. Its neighbour
retainSessionsdoes spell out the same split ("hook harnesses always write on Stop"), so the silence on this one reads as "applies everywhere" — a Claude Code user settingretainEveryTurns: 5gets no effect and no warning. That happens to be the exact workaround #2143's reporter reached for, so the gap was load-bearing rather than cosmetic.The README row also said "opencode", which undersold it: Kilo and Cline CLI share that runtime.
Docs-only; the page and skill mirror are regenerated from the README through
sync-coding-agents-doc.mjs. 433 tests, tsc and lint clean.