Skip to main content

raidlock

raidlock stops parallel coding agents from overwriting each other's files, across Claude Code, Codex and Gemini, and won't accept their work until the tests pass and an agent from another provider signs off.

CI PyPI Python OpenSSF Scorecard License: MIT

raidlock web UI tour

Run Claude Code, Codex, Gemini, shell scripts and people on one board. Each piece of work is a card. Claiming a card leases the exact paths it may touch, and hooks refuse edits anywhere else. One lead closes cards, and only after a signed verify receipt exists for the commit and, on a mixed-provider board, a reviewer from another provider has approved. You can follow who is doing what in the terminal or in a raid-themed web UI.

Why

Parallel agents fail in predictable ways. Two of them edit the same file. One reports "tests pass" and nobody checks. The lead loses track of who is on what, and a stalled session keeps writing after someone else took over. raidlock is a small local tool that handles each of these:

  • Path leases are atomic, keyed by the repo's git remote, and checked across every project on your machine.
  • A fence number changes with every new owner, so a replaced worker's writes are refused.
  • raid done is lead-only and refuses a card until its verify command has passed in a sandbox on the exact commit.
  • Once a second provider joins, done also needs an approval from a reviewer on another provider.
  • Board-first by default: the hooks deny edits outside a card you hold, including the lead's, and subagent launches whose prompt names no open card.
  • It runs on your machine with no runtime dependencies. The Claude Code plugin adds about 190 tokens per session (benchmark).

Install with your agent

Paste this into Claude Code, Codex or another terminal coding agent:

Install raidlock by following the "Install with your agent" steps in
https://github.com/agi1clj/raidlock/blob/main/docs/guides/install.md

The agent installs the CLI and the Claude Code plugin, runs raid doctor, creates a board and explains the board-first rule back to you. It never reads the lead secret.

Install by hand

uv tool install raidlock          # or: pipx install raidlock
raid doctor

In Claude Code, add the plugin (hooks, skill and the raid-worker agent):

/plugin marketplace add agi1clj/raidlock
/plugin install raidlock@raidlock

Needs Python 3.11 or newer on Linux or macOS. On Windows, use WSL2 (expected to work, not yet tested). Codex and MCP setup: Install.

Quickstart

Lead terminal:

mkdir -p ~/demo/shop && cd ~/demo/shop
raid quickstart --demo            # a board, a demo repo acme-shop/, and you as the lead
LEAD_SECRET_FILE="<the path it printed>"
raid --lead-secret "$LEAD_SECRET_FILE" new "Reject empty carts" --id checkout \
  --locks acme-shop/src/checkout --verify-cmd "python3 -m unittest"

Worker terminal:

cd ~/demo/shop/acme-shop
raid up --join --agent worker-1 --card checkout --runtime human   # then run the source line it prints
raid claim checkout --checkout "$PWD"                              # then paste the two export lines
raid ui --open                                                     # http://127.0.0.1:8765

worker-1 now holds acme-shop/src/checkout, and any other agent editing there is refused. Getting started finishes the card: edit, commit, review, verify, done.

How coordination works

One lead, many agents, one project. The lead splits work into cards with narrow, disjoint locks. Each worker claims one, posts notes and hands it back to review. The lead verifies and closes it:

raid --lead-secret "$LEAD_SECRET_FILE" new "Paginate orders" --id orders \
  --locks acme-shop/src/orders --verify-cmd "python3 -m unittest"
raid claim orders --checkout "$PWD"                                     # worker
raid note orders "pagination added; tests pass"                          # worker; renews the lease
raid --lead-secret "$LEAD_SECRET_FILE" msg --to worker-1 --card orders "keep page size at 50"
raid move orders review --note "python3 -m unittest: 9 passed"          # worker
raid --lead-secret "$LEAD_SECRET_FILE" verify orders                    # signed receipt on the commit
raid --lead-secret "$LEAD_SECRET_FILE" done orders

Many projects. Each workspace has its own .board/, and every board registers in one lease index under ~/.raidlock. A path locked from one workspace is locked in all of them. raid ui shows every workspace on its realm page, with tabs for Guilds, Tavern chatter and Treasury.

Many sessions. Separate Claude Code or Codex sessions join the same board with raid up --join, each in its own clone or worktree. Leases map through the git remote, so every checkout of a repo shares one lock space.

Mixed providers. When an agent from a second provider joins, raidlock turns on the verify gate and the cross-provider review gate and records the change. Values you set yourself with raid config set are kept.

Board-first enforcement, on by default. The Claude Code hooks deny edits outside the card you hold, and that includes the lead: a lead edit inside a git repo needs a card the lead holds (require_card_for_lead_edits). A Task or Agent launch is denied unless its prompt names an open card as card <id> (board_first_subagents). Turn either off with raid --lead-secret FILE config set <key> off. The git commit guard checks other agents' leases either way.

Full version: Orchestration.

Two ways to run agents

Workstreams Sandboxed agents
What Sessions you run yourself: Claude Code, Codex, you raid delegate CARD --to codex|claude|gemini|shell runs an agent CLI for you
Where Your own clone or worktree; claim with raid claim CARD --checkout "$PWD" A throwaway clone with no remote and a cleared environment
Guard Lease, edit hooks, git guards Lease, a diff check against the card's locks and a secret scan; the lead applies the returned patch
Cleanup Yours The clone is deleted on done, close or cancel; logs and the patch stay

Use a workstream for a session you watch, and raid delegate for unattended or less trusted runs. Details: Workstreams and sandboxed agents.

Features

Feature Guide
Path leases with expiry and fencing, across clones, worktrees and workspaces Concepts
Board-first hooks, git pre-commit and pre-push guards, runner diff Hooks
Lead-only done, signed verify receipts, cross-provider review Verification
raid delegate, raid next routing on plan headroom, raid duel, raid resume, opt-in raid resurrect Orchestration
Import a checklist or a spec tool's tasks.md, lock suggestions, merge-conflict foresight, a lessons vault Planning
Pull requests from a verified commit; merged PRs close cards through the gates Pull requests
Spend per card, model, agent and day; delegation budgets Operations
Live web UI on 127.0.0.1: Needs you first, quest log, chatter, cost, dependency graph, lease map, replay Web UI
CLI with --json and stable exit codes; an MCP server that never acts as lead Commands, MCP
Optional hardened container image for raid ui, raid mcp and sandboxed verify Docker

Gemini runs only through raid delegate --to gemini, and that adapter is tested against recorded events, not a live Gemini CLI.

Documentation

If you are an agent, start with skills/raidlock/SKILL.md.

Why "raid"

Running several agents feels like leading a raid in an MMO such as World of Warcraft: a raid leader assigns the party, each member holds a role, big quests become bosses, and nobody loots until the boss is down. raidlock borrows that vocabulary for the web UI (guilds, quests, raid frames, boss board, feats). The CLI and the docs use plain terms. raidlock is not affiliated with or endorsed by Blizzard Entertainment.

Security

raidlock keeps cooperating agents out of each other's way. It is not a sandbox. Tokens, the lead secret and the verify signing key are files under your user account, readable by any process running as you. raid verify runs only under bubblewrap on Linux or sandbox-exec on macOS. The UI listens on 127.0.0.1 and answers GET only. Threat model and reporting: SECURITY.md. Limits: Security and limits.

Contributing

See CONTRIBUTING.md and the Code of Conduct.

License

MIT. The web UI bundles the Cinzel font under the SIL Open Font License 1.1. raidlock is an independent project, not affiliated with or endorsed by Anthropic, OpenAI or Google. Claude, Codex and Gemini are trademarks of their respective owners.

Metadata

Release files for raidlock 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for raidlock 0.1.1
File Size Uploaded Provenance Actions
raidlock-0.1.1.tar.gz 14.0 MB With provenance Details for raidlock-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for raidlock 0.1.1
File Interpreter ABI Platform Actions
raidlock-0.1.1-py3-none-any.whl Python 3 none any Details for raidlock-0.1.1-py3-none-any.whl

Total release size: 14.4 MB

Release files / raidlock-0.1.1.tar.gz

Download URL raidlock-0.1.1.tar.gz
Size 14.0 MB
Tags Source
SHA-256 checksum
How to use checksums
f3a70d3d800d68ed3570888f962b8d2a3c5f68699ec91723aadf2aead38046e8
BLAKE2b-256 checksum
How to use checksums
eefe880688afce5f8942fa0f7816033819096591825fafc10f9f57c0fd571835
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / raidlock-0.1.1-py3-none-any.whl

Download URL raidlock-0.1.1-py3-none-any.whl
Size 412.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f804e9492aa253595ed712a565a791dfd6fb26aa65597ae5fa5ff46978b27646
BLAKE2b-256 checksum
How to use checksums
67cd0e99db2ed6ed8e4d34638becf83c20861a5c8d86e05c4e15711668649d1b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for raidlock 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for raidlock-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page