Cabildo
БесплатноНе проверенMessaging and advisory locks for Claude Code sessions working on the same repository (mirror of gitlab.com/cardona-oss/cabildo)
Описание
Messaging and advisory locks for Claude Code sessions working on the same repository (mirror of gitlab.com/cardona-oss/cabildo)
README
pipeline status PyPI version Python versions License: MIT
Run several Claude Code sessions on the same repo without one destroying another's work.
Sessions send each other messages and claim locks through MCP tools. A PreToolUse hook denies a
git push while another session holds the push lock, and always denies force-push and
git reset --hard.
One SQLite file (~/.cabildo/chat.db), no server, no account. Linux and macOS, Python 3.12+.
Codex and opencode sessions can join the same bus.
Install
pip install cabildo # or: uv tool install cabildo
cabildo install # registers the MCP server, the hooks and the push mod in Claude Code
cabildo doctor # checks the hooks, the MCP server and the DB
Restart running Claude Code sessions. New sessions join on their own. cabildo install --print
shows the changes and writes nothing. Running cabildo install again changes nothing. Add
--client both to wire Codex too. To wire the hooks by hand, see
Manual hook setup.
Quickstart
Open two Claude Code sessions in the same repo. At SessionStart each one gets a banner: its
handle, who else is on the project, active locks, and unread mail. The agents then call the MCP
tools. This is the flow tests/test_mcp_tools.py tests, with agents alice and bob. It is a
transcript of tool calls and results, not runnable Python:
# alice
whoami() → {session_id, handle: "alice", project: "alpha", unread: 0}
list_agents() → [{handle: "bob", ...}]
send("can you take the frontend?", to="bob") → {ok: true}
send("team, standup in 5") → posts to #proj:alpha (the default)
# bob
inbox() → previews of unread mail, nothing auto-marked
read(message_ids=[1]) → {marked_read: 1, unread_remaining: 0}
# alice
claim("push:alpha", note="pushing") → {ok: true}
# bob
claim("push:alpha") → {ok: false, held_by: "@alice"}
# alice
release("push:alpha")
You can post to the same bus from a terminal, with no session:
cabildo watch # chatroom on a tty (plain tail when piped)
cabildo say "ship it" # post to #general
cabildo say -u --to bob "stop" # urgent DM: holds the recipient's turn open
cabildo log -n 50 -t general # recent messages, then exit
cabildo viewer # read-only web view on http://127.0.0.1:8787
Key features
- Presence:
whoami,set_handle,set_role,list_agents. Sessions are scoped to a project (the git repo root; a linked worktree resolves to its main repo, so agents in separate worktrees share one channel). - Messaging: DMs by handle, per-project channel
#proj:<name>, global#general,urgentas the escalation axis.send,send_to_role,inbox,get_message,read,history. Which paired machines get a channel's posts: see Channels and tags. - Roles:
[roles]in the config describes each role. Ask a role a question withsend_to_role(..., question=True); any holder answers withsend(..., reply_to=...). See Roles. - Advisory locks:
claim(resource, ttl_seconds, note),release,claims. - Hook-level git guard: denies the pushes and destructive git that overwrite other agents' work (see
What is enforced);
cabildo costreports what the hooks inject and how long they take. - Optional daemon (
cabildo service install; systemd--useron Linux, launchd on macOS). Agentsrequest(action="push")and a single worker runs fetch, rebase, gate, push, verify, then DMs the result. Alsoaction="spawn"(a headless agent in its own worktree) andaction="ask"(a desktop prompt with buttons). Installs dry-run unless you pass--allow-push/--allow-spawn. Sweeps sessions whoseclaudedied without firingSessionEnd. - Browser (
cabildo browser status | reap | login | doctor | serve): manages the visible, isolated Chrome that agents browse with. See docs/browser.md. - Platforms: Linux and macOS, Python 3.12+. Memory-pressure stall detection (PSI) is Linux-only.
Beyond these: other clients on the same bus (cabildo codex, cabildo opencode), cabildo sessions to find a lost session, context-cheap unread/preview handling, and
per-repo config (.cabildo/config.toml).
Put a folder on the bus with cabildo add --project <name> .: it pins the project name and writes
the MCP entry into the folder's .mcp.json at project scope. CABILDO_HOME relocates the DB;
CABILDO_PROJECT overrides the name.
Why cabildo, and what it does not do
Other ways to coordinate agents, and where they stop:
- A shared file or doc (
STATUS.md, a scratch note). Works until two agents write it at once, and nothing reads it for them. cabildo delivers mail into a session's context at hook boundaries, and the guard runs whether or not the agent remembered to look. - Claude Code subagents. They talk to their parent through the harness, never to each other, and die with the turn. cabildo is for independent top-level sessions: separate terminals, separate worktrees, even separate clients, each with its own context window.
- A lockfile in the repo. It coordinates one repo for processes that agree to check it. cabildo's locks are keyed by project, name the holder, expire, and the deny comes from the harness, not from the agent choosing to check.
- A hosted orchestrator. cabildo has no server, no account, and nothing leaves the machine.
Cross-machine sync (LAN pairing with
request("pair"), WAN peers in config) is peer-to-peer.
What it does not do:
- Wake an idle agent. Delivery is pull-based: hooks are the only way into a running session's
context. Ordinary mail waits for the next user turn; urgent mail is injected at the next tool
call and holds the turn open at
Stop, but a session that has already stopped is unreachable until its next prompt. - Replace git. The daemon serialises pushes; it never stages or commits for you, and refuses with uncommitted tracked changes.
- Sync presence or claims across machines. LAN/WAN sync covers messages for one project; locks stay per-machine.
How it works
cabildo is a normal Python package with two halves:
- A stdio MCP server (
cabildo-mcp): the tools agents call. Who is here, send, inbox, claim, release, request a push. - Hook scripts (
cabildo-hook <event>): what makes a session join the bus, get mail delivered, stay listed, and be held to the rules.
All state is one SQLite database (~/.cabildo/chat.db, WAL) shared by every session. No daemon is
required and nothing touches the network: if two agents share a filesystem, they share a bus. The
runtime is stdlib-only; the one dependency is mcp.
Identity is automatic. Claude Code never hands an MCP server its session_id, but hooks get it,
and both hooks and the MCP subprocess descend from the same claude process. The SessionStart
hook binds session_id to that PID; the MCP server walks the process tree (/proc on Linux, ps
on macOS) and looks it up. The model never carries an ID around.
The name: a cabildo is a council. In colonial Spanish America it was the town assembly; in Colombia today it is the governing body of an indigenous community.
What is enforced, and what is not
Claims are advisory leases with a TTL (default 600s): agents cooperate by convention, a crashed
agent never deadlocks the bus, and SessionEnd drops a session's locks. The PreToolUse hook
enforces the convention at the one place agents overwrite each other: git, issued as a
Bash tool call. It denies, with a reason naming the holder or peers:
git pushwhile another session holdspush:<project>, or while any other agent is simply live on the project. A lease you hold yourself is the escape hatch; otherwise queue it through the daemon.- Force/delete push (
--force,-f,--force-with-lease,--delete,+refspec): always. It destroys committed work that lives only on the remote. - Tree-destroying git (
reset --hard, discardingcheckout/restore,clean -f, tree-widestash): always. It wipes uncommitted work an autonomous agent cannot bring back. - Index/tree/HEAD-mutating git (
add,commit,checkout,merge,rebase, ...) while another agent stands in the same checkout. One index, one HEAD to collide on; the fix isgit worktree add, not refereeing. - Commit on a protected trunk, only where a repo opts in with
[trunk].mode = "guard".
Force-push and destructive-git denials opt out per repo via .cabildo/config.toml. A push the
remote rejects non-fast-forward is not pre-blocked; PostToolUse injects a fetch+rebase recipe so
the agent recovers without reset --hard.
Not enforced: file edits. Edit/Write are not gated by per-file leases; agents coordinate on
files by isolating in their own worktrees, which the shared-checkout denial points at.
The guard only sees git that arrives as a tool call. For plain git in a terminal,
cabildo guard install wires a thin pre-commit/pre-push hook that applies the same rules,
composes with an existing hook, and fails open.
Manual hook setup
cabildo install wires the hooks for you. To do it by hand, add each entry to
~/.claude/settings.json; each one runs cabildo-hook <event>:
{
"hooks": {
"SessionStart": [
{ "hooks": [{ "type": "command", "command": "cabildo-hook session_start", "timeout": 10 }] }
]
}
}
| event | command arg | timeout | matcher |
|---|---|---|---|
SessionStart |
session_start |
10 | none |
UserPromptSubmit |
prompt_submit |
10 | none |
SessionEnd |
session_end |
10 | none |
Stop |
stop |
10 | none |
SubagentStop |
subagent_stop |
10 | none |
PostToolUse |
post_tool_use |
5 | * |
PreToolUse |
pre_tool_use |
5 | Bash|Edit|Write|NotebookEdit |
The per-tool-call hooks get a tight timeout on purpose: they fire on every tool call, so a hung DB must cost 5s once, not block the session repeatedly.
Upgrade
A running daemon and each session's MCP server keep the code they started with. After an upgrade,
restart them, then run cabildo doctor: it warns about a daemon or MCP server older than the
install, and about more than one cabildo on PATH.
pip install -U cabildo # or: uv pip install -U cabildo
cabildo service restart # the daemon
Then restart each Claude session, which restarts its MCP server.
Links
- Repository: https://gitlab.com/cardona-oss/cabildo
- PyPI: https://pypi.org/project/cabildo/
- Documentation: https://cardona-oss.gitlab.io/cabildo/
- Changelog: CHANGELOG.md
- Issues: https://gitlab.com/cardona-oss/cabildo/-/issues
Contributing
From a clone, scripts/install.py creates the venv, installs cabildo editable, and then wires it
like cabildo install (MCP server at user scope, hooks merged into settings.json). Running it
again changes nothing:
python scripts/install.py # Claude Code
python scripts/install.py --print # dry run, changes nothing
python scripts/install.py --client both # Claude Code + Codex on one bus
Toolchain, CI, and the release process live in CONTRIBUTING.md; build and test
detail for coding agents is in AGENTS.md. In short: uv sync, make install-hooks
once, then make check (lint + format-check + typecheck + test); moon run :ci is what CI runs.
License
MIT © Jorge Cardona. See LICENSE.
Установить Cabildo в Claude Desktop, Claude Code, Cursor
unyly install cabildoСтавит в Claude Desktop, Claude Code, Cursor и VS Code — сам разбирается с npx, uvx и сборкой из исходников.
Впервые? Поставь CLI: curl -fsSL https://unyly.org/install | sh
Или настроить вручную
Выполни в терминале:
claude mcp add cabildo -- uvx cabildoПошаговые гайды: как установить Cabildo
FAQ
Cabildo MCP бесплатный?
Да, Cabildo MCP бесплатный — установка в пару кликов через Unyly без оплаты.
Нужен ли API-ключ для Cabildo?
Нет, Cabildo работает без API-ключей и переменных окружения.
Cabildo — hosted или self-hosted?
Self-hosted: сервер запускается локально на твоей машине командой из раздела установки.
Как установить Cabildo в Claude Desktop, Claude Code или Cursor?
Открой Cabildo на unyly.org, выбери вкладку своего клиента (Claude Desktop, Claude Code, Cursor) и нажми Install — конфиг сгенерируется автоматически, без правки JSON.
Похожие MCP
GitHub
PRs, issues, code search, CI status
автор: GitHubFilesystem
Secure file operations with configurable access controls.
Memory
Knowledge graph-based persistent memory system.
Template MCP Server
A CLI tool to create a new Model Context Protocol server project with TypeScript support, dual transport options, and an extensible structure
автор: mcpdotdirectServer Sequential Thinking
MCP server for sequential thinking and problem solving
автор: GitHub ActionsUnyly Deploy
Deploy sites and MCP servers to Unyly straight from your AI agent
автор: UnylyAmap Maps Mcp Server
MCP server for using the AMap Maps API
автор: duxiaohuiPayMCP
Lightweight payments layer for MCP servers: turn tools into paid endpoints with a two-line decorator. [PyPI](https://pypi.org/project/paymcp/) · [npm](https://w
автор: blustAIServer For Power BI
Enables exploring Microsoft Fabric / Power BI workspaces and semantic models, and executing ad-hoc DAX queries.
автор: Mitsubishi-FusoGpt Image 2 Mcp
RunAPI GPT Image 2 MCP server for image generation: create tasks, poll results, and check pricing across 1 model from Claude Code, Codex, Cursor, and VS Code.
автор: runapi-aiCompare Cabildo with
Не уверен что выбрать?
Найди свой стек за 60 секунд
Автор?
Embed-бейдж для README
Похожее
Все в категории development
