Collide, forget, repeat: parallel agents explained

One coding agent, working alone, is easy to supervise. Run a dozen of them at once, on different tasks, on different machines, each starting from a clean context that remembers nothing between sessions, and three problems show up on schedule. Two agents edit the same files without either one knowing. A lesson one session learned the hard way evaporates the moment that session ends. And every new agent has to be told the same house rules from scratch, because it has no memory of the last one being told.

CodeHerder has one feature for each of those, and they’re worth a deep dive on mechanism rather than pitch: working nearby, the workspace wiki, and skills.

Working nearby: agents find out before they collide

Two agents can cross paths in two different ways, and CodeHerder checks for both. The first is file overlap: two live sessions have touched at least one of the same paths in the same repository. The second is shared ancestry: two sessions’ tasks trace back to a common parent, even if neither has written a line the other has touched. Both checks live behind one server-side endpoint, GET /v1/sandboxes/{id}/neighbors, so the agent’s own brief, the ch sandbox neighbors command, and the web app’s panel are all reading the same answer instead of three separate guesses at it.

File overlap needs live data to check, so each session recomputes its own changed-path set every 90 seconds and only reports upstream when that set has actually changed, capped at 500 paths and 512 bytes per path so the check-in stays cheap even on a large working tree. On the server, a sweeper ticks every 60 seconds, groups live sandboxes by repository, and alerts both sides of any pair it finds. That alert is throttled per pair: a brand-new overlapping pair fires immediately, an unchanged overlap never re-alerts, and a pair whose overlap keeps changing waits 30 minutes between nudges, so two agents grinding through the same file all afternoon don’t get paged every minute.

Shared ancestry doesn’t need a sweeper at all, because it’s static for the life of the task: it’s resolved once, at spawn, when a new session’s brief lists its live cohort peers up front (capped at 50 peers scanned, 10 shown, with an honest count of how many more weren’t). Peers that are already running when a new sibling task starts get a one-time arrival notification instead, throttled to once per peer per hour.

Both checks are scoped by the same workspace-containment rule, and both are advisory only: nothing locks, nothing blocks, and every session already has its own git worktree, so there’s no actual file contention to prevent. What working nearby buys you is earlier awareness, not enforcement. An alert names the other agent, lists up to three overlapping paths verbatim plus a “+N more” if there are others, and comes with a DM command already addressed to that peer’s exact live session, so acting on it is one command, not a hunt through the dashboard. The full mechanism is documented at Working nearby.

The workspace wiki: what survives the reset

A clean-context session has no transcript from the session before it, which means anything worth remembering across tasks needs somewhere durable to live. That’s the workspace wiki: a shared collection of pages, each with a title, a unique slug, a scope (shared across the workspace, or private to one agent persona), a kind (fact, feedback, project, or reference), and a body capped at 8 KB. A page over that cap is rejected outright rather than silently trimmed, so nothing important gets quietly truncated.

A page reaches a session twice, at two different resolutions. The brief a new session starts with carries a bounded one-line index of relevant pages, and the full text of every page in scope also lands as ordinary files under .codeherder/knowledge/ in the agent’s own working copy, so it can open and read the whole thing whenever it actually needs to. Pages placed on a parent group are inherited by every workspace beneath it, the same way devices, repositories, and agents are; writing with --at targets that ancestor group directly instead of copying the same page into every child workspace by hand.

Agents write the wiki themselves, through the same path a human uses with ch wiki write: a new or updated page is live for every other member the moment it’s written, attributed to whoever wrote it, and recoverable from history if it turns out to be wrong. Any member can archive a page that’s stopped being true. Writes and archives aren’t just for the next session, either: a write or archive is pushed straight out to every session already running in that workspace and beneath it, so an agent mid-task picks up a correction without restarting, no polling involved. The direction that does poll runs the other way: an agent editing a page in place inside its own .codeherder/knowledge/ copy has that edit flushed back up to the server after a 2-second quiet period, on a 10-second poll. ch wiki report is the standing health check across all of it, flagging broken links, index drift, orphaned pages, and malformed frontmatter. Full detail is at Workspace wiki.

Skills: the house rules, said once

The third failure mode is the most repetitive: every fresh agent has to be told the same conventions, the same gotchas, the same “don’t do X” that the team has already learned, because it walks in with none of that context. Skills solve it by packaging instructions once, per workspace, rather than repeating them in every task brief. A skill is a SKILL.md plus whatever supporting files it needs, bounded at 64 files, 256 KB per file, and 512 KB per skill, with a workspace-wide budget of 2 MB shared across every skill that’s currently enabled. That budget is enforced as a hard refusal at the moment you try to enable one more skill than it allows, not as a silent drop somewhere later at spawn.

An enabled skill is delivered fresh into each session’s own working copy and linked into whichever folder that agent’s harness reads skills from. Nothing about it is committed: it’s excluded from git in that clone, and a folder the repository already owns for its own purposes is never overwritten by a delivered skill. A skill takes effect on the next session that spawns, never retroactively into one already running, and disabling it removes exactly what was delivered. Every session’s own page reports the outcome per skill: linked, already there, copied, skipped, or removed, so you can check that a skill actually reached a given session rather than assuming it did. This only applies to task sessions; a dev session doesn’t receive them. Skills owned by a group inherit down to every workspace beneath it, and a slug is unique across the whole workspace tree, so a workspace can never accidentally shadow a skill it inherited from above. The full picture is at Skills.