Skip to main content

raidlock

Many agents. One repo. No collisions.

raidlock locks the files each agent may change, enforces it at edit time across Claude Code, Codex and Gemini, and accepts work only after the tests pass in a sandbox and another provider reviews it.

CI PyPI Python 3.11+ OpenSSF Best Practices OpenSSF Scorecard License: MIT

raidlock web UI tour

🔒 File-level edit locks · ✅ Tested and cross-reviewed before done · ⚔️ Live raid board

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

Run two coding agents on one repo and the same things go wrong: they overwrite each other's files, one says "tests pass" and nobody checks, and a stalled session keeps writing after someone else took over. raidlock prevents each of these:

  • No overwrites. A card leases the exact paths an agent may change; the hooks refuse edits anywhere else, across every project and clone on your machine.
  • No stale writers. When a card changes hands, the old owner's writes are refused.
  • No unproven "done". Only the lead closes a card, and only after its check passed in a sandbox on that exact commit and, with mixed providers, an agent from another provider approved it.
  • No off-board work. Every edit and every subagent needs a card first, so the board always shows who is doing what.
  • Local and light. No server, no runtime dependencies; the Claude Code plugin adds about 190 tokens per session (benchmark).

How it compares

Tool Great at What raidlock adds
claude-squad, ccmanager, vibe-kanban running many agent sessions raidlock doesn't run sessions; it coordinates whichever ones you run, and works alongside these
Claude Code agent teams native Claude task lists and claims enforcement on code paths, not just task claims, and it spans Claude, Codex and Gemini
beads a dependency-aware issue graph for agents path leases enforced at edit time, plus a verify-and-review gate
mcp_agent_mail rich agent messaging and file reservations lead-only done with signed receipts and cross-provider review

More detail: Overview.

Install with your agent

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

Install or update raidlock by following
https://raw.githubusercontent.com/agi1clj/raidlock/main/AGENT_INSTALL.md

The agent installs or upgrades to the latest release, adds 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. They stay on only while both providers are present (seen within the lease TTL, or holding a lease); when one leaves, the next close relaxes them back to the defaults, raid done says so and the UI bell shows "Review gates relaxed". Shell agents and people never count as a second provider. Claude Code alone is enough.

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. Writes outside the workspace's repos (scratchpads, /tmp) are never blocked.

Self-healing lead. When the lead's session ends, its lease is freed at once and the next session is told the exact takeover command; a refusal always names both session ids and the command that fixes it. raid --lead-secret FILE tidy reaps expired leases, closes cards whose PR merged and lists what still waits on you; raid ui reaps every 5 minutes on its own. raid upgrade updates the CLI and the plugin. raid and raidlock are the same command.

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 and raid land (apply, verify and hand back a delegated patch in one command), 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, a first-run tour Web UI
Notification bell across every project (rings, desktop alerts) and an in-app notice when a new release is out Web UI, Upgrade
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.2.7

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.2.7
File Size Uploaded Provenance Actions
raidlock-0.2.7.tar.gz 13.2 MB With provenance Details for raidlock-0.2.7.tar.gz

Built distribution (wheel)

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

Total release size: 13.6 MB

Release files / raidlock-0.2.7.tar.gz

Download URL raidlock-0.2.7.tar.gz
Size 13.2 MB
Tags Source
SHA-256 checksum
How to use checksums
3e7688bc1bbe9d1c128a2ee778851a72297b4d25de37cd2088af741850d44a27
BLAKE2b-256 checksum
How to use checksums
d219c91036984e8808cdef9664a7927e1ad3eb141669eb15947cee4a10fe9e80
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 28, 2026.

Transparency log

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

Download URL raidlock-0.2.7-py3-none-any.whl
Size 429.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
81a0fa497a99da0403e35ef6d8c1edc4a942bdcab5de019f451c579abae8d740
BLAKE2b-256 checksum
How to use checksums
eb29297b8b5ab7c0d43433fed27f140b2d17abdb76be07f97247afba8f99a05b
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 28, 2026.

Transparency log

Security for raidlock 0.2.7

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.2.7.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 28, 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