{"slug": "show-hn-load-lock-a-machine-wide-semaphore-for-parallel-ai-coding-agents", "title": "Show HN: Load-lock, a machine-wide semaphore for parallel AI coding agents", "summary": "A developer released load-lock, an open-source machine-wide counting semaphore that lets parallel AI coding agents share one heavy-work budget so builds and test suites stop competing for cores and caches. The tool, installable via `npm install -g @aron98/load-lock`, defaults to a single pool named `heavy` with capacity 1 and supports harnesses including OpenCode, Claude Code, Codex CLI, Gemini CLI, Copilot CLI, Cline, Roo Code and Goose through plugins, MCP tools or a generic stdio server. Load-lock uses FIFO offers with opaque claim tokens, attaches permits to real processes (pid, process group and `/proc` start time) for crash-safe cleanup, and reports cgroup/container CPU and memory limits via `inspect_machine` rather than assuming cores equal capacity.", "body_md": "**A machine-wide heavy-work budget for parallel coding agents.**\n\nWhen several agents work side by side on one machine — separate sessions, repos, git worktrees, or harnesses (OpenCode, Codex CLI, Claude Code, ...) — their builds and test suites stomp on each other, thrash the caches, and starve each other's cores. load-lock gives them one shared counting semaphore: acquire a permit before heavy work, keep doing light work while queued, receive a FIFO offer when capacity frees, claim it, run, release. It is cooperative and advisory — no command wrapping, no automatic shell classification, no approval interruptions.\n\n```\nagent A (OpenCode)        agent B (Codex)         agent C (Claude Code)\n  acquire \"cargo test\"      acquire \"npm test\"      acquire \"build docs\"\n  granted ✓ runs            queued → keeps coding   queued → keeps coding\n  ...                       offer → claim ✓ runs    (misses window → paused)\n  release ✓                 release ✓               rejoin → offer → claim ✓\n```\n\nThree agents, one budget — the queue drains FIFO while everyone keeps coding:\n\n- **One budget for the whole machine** — every client of any harness shares\none capacity pool regardless of repo/worktree/cwd. Default: pool`heavy` ,\ncapacity 1; fully runtime-configurable by any agent via versioned CAS\nupdates (persisted with author + rationale).\n- **Atomic acquire-or-queue** — single daemon event loop; a release can\nnever slip between a failed check and queue registration.\n- **FIFO offers with opaque claim tokens** — outstanding offers reserve\ncapacity; expired offers pass capacity to the next waiter and pause the\nabsent request until it explicitly rejoins (no endless recycling).\n- **Real process-lifecycle cleanup** — permits attach to actual processes\n(pid + process group +`/proc` start time, PID-reuse-safe). Background\njobs outliving the shell keep their permit until the whole group exits.\nNever auto-expired merely for being old. Untracked work uses an honest,\ndocumented heartbeat-lease tradeoff. Explicit release is always\navailable and idempotent.\n- **Crash-safe** — agent crashes release tracked permits on confirmed\nprocess death; daemon restarts reconcile a journal against real liveness\nand auto-respawn transparently.\n- **Honest notifications** — tool-boundary offer delivery everywhere; real\nidle wakeup where the harness supports it (live-verified on OpenCode;\nhook-based on Claude Code and Codex CLI); a bounded blocking`wait_for_turn` (`load-lock wait` on the CLI) that sleeps until your\nturn and auto-claims for harnesses without idle wakeup; durable event\nids for reconnects. A notification never authorizes work — only`claim` does.\n- **Policy that actually reaches the model** — installed per harness via\nits real mechanism (plugin context hook, SessionStart hooks incl.\ncompact matchers, global instruction files), plus a detailed skill/guide.\n- **Resource-aware** —`inspect_machine` reports cgroup/container CPU and\nmemory limits and current pressure; never assumes cores = capacity.\n\n```\nnpm install -g @aron98/load-lock\nload-lock install --harness opencode     # or claude-code | codex | gemini-cli |\n                                         # copilot-cli | cline | roo-code | goose |\n                                         # omac (sandbox grants) | generic\nload-lock doctor\n```\n\nFrom then on, agents see the policy and tools automatically:\nOpenCode plugin (`load_lock_*` tools), Claude Code / Codex MCP tools\n(`mcp__load-lock__*`) plus session hooks. Any other MCP-capable harness can\nuse the generic stdio server; plain shells use the CLI:\n\n```\nload-lock run --reason \"nightly build\" -- npm run build   # acquire→run→release\nload-lock status                                          # machine-wide view\nload-lock dashboard                                       # live read-only dashboard (q quits)\nload-lock help                                            # one-screen usage of every command\nload-lock configure --capacity 2 --reason \"16-core host\" --author me\n```\n\nOpenCode users also get a live dashboard inside the TUI: `/load-lock`\nopens it in-window, every session screen shows a clickable at-a-glance\nwidget in the right sidebar, and the home screen has a footer indicator —\nsame data, themed. See docs/OPERATIONS.md → \"Dashboard\".\n\nAgents running inside a sandbox (bubblewrap/omac, Docker, macOS seatbelt,\nWSL2) share the host's budget instead of getting their own: bridge the\ndaemon's Unix socket into the sandbox, set `LOAD_LOCK_NO_SPAWN=1` so the\nclient never spawns a useless sandbox-local daemon, and optionally tag\nholds with `LOAD_LOCK_LABEL_PREFIX` (e.g. `bwrap:issue-42 build`).\nReady-to-run per-sandbox recipes — live-verified for bubblewrap and omac,\ncontract-inspected for the rest, plus the cross-PID-namespace lease\nlifecycle — live in docs/OPERATIONS.md → \"Sandboxes\".\n\n```\nsrc/core/       daemon + state machine + persistence + machine inspection\nsrc/mcp/        MCP stdio server (universal adapter)\nsrc/adapters/   OpenCode native plugin\nsrc/cli/        CLI incl. installer, hook handlers, run/wait helpers\nsrc/test/       32 tests: state machine, real multi-process daemon tests,\n                MCP integration, hook contracts, run helper\ndemo/           reproducible 3-worktree demo (three agents, one pool)\ndocs/           ARCHITECTURE / COMPATIBILITY / OPERATIONS / AGENT_GUIDE\nskills/         packaged skill\n```\n\n- [docs/ARCHITECTURE.md](https://github.com/aron98/load-lock/blob/main/docs/ARCHITECTURE.md) — design, why a dedicated\nservice (vs WorkOS Airlock / mic-lock / flock wrappers), atomicity,\nrestart semantics, notification honesty, lifecycle tradeoffs.\n- [docs/COMPATIBILITY.md](https://github.com/aron98/load-lock/blob/main/docs/COMPATIBILITY.md) — per-harness capability\nmatrix with implemented / contract-tested / proposed labels.\n- [docs/OPERATIONS.md](https://github.com/aron98/load-lock/blob/main/docs/OPERATIONS.md) — install, config,\ntroubleshooting, recovery, daemon lifecycle, sandbox bridging.\n- [docs/AGENT_GUIDE.md](https://github.com/aron98/load-lock/blob/main/docs/AGENT_GUIDE.md) — the playbook for agents.\n- [docs/ADAPTERS.md](https://github.com/aron98/load-lock/blob/main/docs/ADAPTERS.md) — how to write an adapter for a new\nharness, using the published library surface.\n\n- Core daemon/protocol/CLI: implemented, 68 automated tests passing\n(multi-process daemons, real processes, restarts, races, expiry,\nPID-reuse, subprocess survival; plus 9 dashboard tests — view-model\nshaping, event-cursor resume across a daemon restart, reconnect, and a\n`load-lock dashboard --once` render smoke test).\n- OpenCode adapter: implemented and **live-verified** (tools, policy\ninjection, compaction-proof context hook, execution-boundary wakeup\nwith tokens, skill).\n- Claude Code adapter: implemented, contract-tested against documented hook JSON; not yet live-verified (harness not installed on the verification machine).\n- Codex CLI adapter: implemented and **live-verified** end-to-end in\nDocker (interactive TUI via pty: policy injection, MCP round-trip,\nFIFO queueing behind a competing holder, Stop-hook decision-block\nwakeup; see COMPATIBILITY.md for the two upstream/provider constraints\nthe verification harness works around).\n- Tier-3 fallback installers (Gemini CLI, Copilot CLI, Cline, Roo Code, Goose): implemented merge-only installers (MCP stdio server entry into the harness's real config + a global instructions-file section/policy rule file), config-tested via temp-HOME round-trips; fallback tier (no hooks, no async push — no idle wakeup).\n- Cursor adapter: implemented (issue #6) — merge-only project-level installer\n(`.cursor/mcp.json` MCP entry,`.cursor/hooks.json` stop hook per the now-\nofficially-documented hooks v1 contract,`.cursor/rules/load-lock.mdc` Always-apply rule) +`hook cursor stop` handler emitting`{\"followup_message\":...}` idle wakeup.**Contract-tested** , not\nlive-verified (no Cursor on the verification machine).\n- Aider: researched; manual CLI tier. See COMPATIBILITY.md for the matrix.\n\nLinux-first; macOS works with documented liveness-check limitations; Windows has a named-pipe transport adapter (implemented and unit-tested on Linux via platform injection; not yet verified on a Windows machine).", "url": "https://wpnews.pro/news/show-hn-load-lock-a-machine-wide-semaphore-for-parallel-ai-coding-agents", "canonical_source": "https://github.com/aron98/load-lock", "published_at": "2026-10-26 09:08:22+00:00", "updated_at": "2026-10-26 09:14:03.462097+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols"], "entities": ["load-lock", "OpenCode", "Claude Code", "Codex CLI", "Gemini CLI", "Copilot CLI", "Cline", "Roo Code"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-load-lock-a-machine-wide-semaphore-for-parallel-ai-coding-agents", "markdown": "https://wpnews.pro/news/show-hn-load-lock-a-machine-wide-semaphore-for-parallel-ai-coding-agents.md", "text": "https://wpnews.pro/news/show-hn-load-lock-a-machine-wide-semaphore-for-parallel-ai-coding-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-load-lock-a-machine-wide-semaphore-for-parallel-ai-coding-agents.jsonld"}}