Tirith
OfficialTirith is an MCP coordination server for parallel coding agents: it leases files, runs a task board, versions interface contracts, pushes change notices, logs decisions, stores path-scoped memory notes, and carries agent messages.
Claims (
claim,release,renew,claims_list): atomically lease files/directories before editing, with TTLs, server-side waiting (wait_secs), automatic renewal, and conflicts naming the owner, reason, and expiry.Task board (
task_create,task_pull,task_update,task_list): queue prioritized tasks with dependencies and paths; pull the next unblocked task, hand it back, park it as blocked, force-take others' work, or wait for work server-side.Contracts (
contract_publish,contract_get,contract_list): publish versioned interface shapes (http, function, type, event, cli, other) with consumers before either side implements; republishing auto-notifies consumers, andexpected_versionguards concurrent writes.Change notices (
notice_publish,notice_list): announce renames, signature changes, removals, moves, or behavior changes with affected paths; delivered at once to holders' inboxes and to later claimers' briefs, with durable unread tracking.Decisions log (
decision_record,decision_list): record settled choices with rationale, alternatives, and constrained paths as committed Markdown, searchable by text or path, so nothing is decided twice.Memory notes (
memory_write,memory_read,memory_search,memory_delete): save durable Markdown lessons, traps, handoffs, and research scoped to paths; search/filter them, read full bodies plus related notes, update in place with concurrency guards, or delete permanently.Messages (
message_send,message_list): send short notes to one agent, all active agents (*), or the human queue, threaded viareply_toand delivered once as inbox on the recipient's next call; dropped after 24 hours.Status and guidance (
status,guide): report daemon health, counts, lead, and active agents (verbose), or fetch static how-to guidance for the loop and each primitive.Every result is JSON with a
statusfield and may also carrylost(ended leases),inbox(waiting messages), orpersist_error; lists are paged, and claim briefs bundle unread notices, contracts, decisions, and memory excerpts for the claimed paths.Swarm coordination: claiming the reserved path
.tirith/leadmakes a session the lead, gating contract/task/decision writes and routing escalations (blocked tasks, repeated claim refusals) to the lead or the human queue.CLI parity: every tool has a subcommand (
tirith claim,tirith task pull,tirith memory write,tirith call <tool>, etc.), plusinit,serve,stdio,update,status,lead, andtray.
Run five or ten coding agents on one repository and they edit the same files, rename things others depend on, and build both sides of an interface to different shapes. Tirith is a small daemon they all talk to: an agent claims files before editing, gets the notices, contracts, decisions, and notes for those files back with the claim, and publishes the shape of an interface before either side implements it.
It works with anything that speaks MCP, over stdio or HTTP: Claude Code, Cursor, Codex, LangGraph, CrewAI, or a plain script.
It also remembers. Agents leave notes scoped to repository paths, so what one agent learned about a file reaches the next agent that claims it. Tirith stores no conversation history and no embeddings.
Status: v1 shipped. Every primitive, the CLI, persistence, and the dashboard are built and tested, against the definition in ADR-0013; tool schemas follow semantic versioning.
Install
macOS and Linux:
curl -LsSf https://eabz.github.io/tirith/install.sh | shWindows (PowerShell):
irm https://eabz.github.io/tirith/install.ps1 | iexWith cargo (the package is tirith-mcp, the binary is tirith):
cargo install tirith-mcpAlready installed? tirith update replaces the binary in place with the
latest release. Prebuilt binaries for macOS, Linux, and Windows on x86_64
and ARM64 are on the releases page;
every option is in docs/1-about/05-installation.md.
Listed in the MCP Registry:
mcp-name: io.github.eabz/tirith.
Related MCP server: LLM Bus
Quick start
In the repository, run:
tirith initIt registers tirith stdio in .mcp.json and puts a short block in
AGENTS.md (--file for another). The protocol itself, from the first
claim to who leads a swarm, arrives as the MCP server's instructions
every time a session connects; a repository that wants its own protocol
keeps it in .tirith/instructions.md (tirith init --instructions
writes the built-in one there to edit). Other clients register the same
command by hand: the shim starts the repository's daemon the first time a
session needs it, replaces a daemon of another version, and proxies to it
after that; nothing has to be started by hand.
Client | Setup |
Claude Code |
|
Cursor |
|
Codex |
|
LangGraph, CrewAI, curl | connect over HTTP, see docs/2-examples/02-client-setup.md |
The daemon serves MCP at http://127.0.0.1:7477/mcp and a live dashboard
at http://127.0.0.1:7477/. State is written to .tirith/ in your
repository: contracts, notices, decisions, and memory notes are meant to
be committed; .tirith/runtime/ (claims, tasks, messages) is gitignored
by a .gitignore Tirith writes itself.
Every agent passes a stable agent name with each call. That is the only
convention it has to follow. To run several agents at once, paste the
protocol block from
docs/2-examples/03-swarm-playbook.md
into your project's agent instructions: it says which session leads,
when it spawns workers, what each worker is told, and which model each
runs on. The daemon serves the same rules in its instructions.
What it does
Primitive | Tools | Purpose |
Claims |
| Lease files or directories before editing. Overlaps are refused with the owner, reason, and expiry, or waited out server-side with |
Task board |
| Tasks with priority, owner, and dependencies. Agents pull the next unblocked task, skipping tasks another agent holds, and can wait server-side for one with |
Contracts |
| Interface shapes published and versioned before implementation. A new version notifies its consumers automatically. |
Change notices |
| "Renamed |
Decisions log |
| Settled choices with rationale, so nothing is decided twice. |
Memory notes |
| Lessons, traps, and handoffs scoped to repository paths. Committed Markdown, searchable, and delivered to whoever claims the paths a note is about. |
Messages |
| Short notes between agents, delivered on the recipient's next call, so any MCP client can take part. Runtime only. |
Status |
| Counts, persistence and load problems; |
Twenty-two tools, each with a description of every parameter, MCP
annotations, and an output schema, plus the protocol as the server's
instructions on connect (ADR-0038). Every result is JSON with a status
field, lists are paged, and any result may carry lost (a lease that
ended) or inbox (messages waiting). The full reference, the single source of truth for
tool schemas, is docs/1-about/04-primitives.md.
Example
Two agents, one directory. The second is refused with enough information to decide what to do next:
tirith claim --agent alice --reason "refactor session handling" src/auth/
# ok alice src/auth expires 04:14:34Z
tirith claim --agent bob --reason "fix login redirect" src/auth/login.rs
# conflict src/auth/login.rs overlaps src/auth (alice: "refactor session handling", expires 04:14:34Z)A note left for whoever edits a path next. Alice writes it once; it comes back on Bob's claim without anyone searching, as an excerpt, never a body:
tirith memory write --agent alice "Session ids are opaque" -k gotcha --path src/auth/ <<'NOTE'
Tokens are opaque strings. Compare them, never parse them.
NOTE
tirith release --agent alice
tirith claim --agent bob --reason "fix login redirect" src/auth/login.rs
# ok bob src/auth/login.rs expires 04:14:34Z
# memory:
# session-ids-are-opaque gotcha 04:04:34Z paths src/auth Session ids are opaque: Tokens are opaque strings. Compare them, never parse them.The full walkthrough, with contracts, notices, and the same calls over raw MCP, is docs/2-examples/01-two-agents-demo.md; the script is examples/demo.sh.
CLI
Every tool has a subcommand; the CLI uses the same MCP path agents do.
tirith serve # run the repo's daemon by hand
tirith stdio # per-session shim clients spawn; starts the daemon if needed
tirith update # replace the binary with the latest release
tirith status # counts, and who holds what
tirith init [--file AGENTS.md] [--instructions] # register the server, add the agents block
tirith claim | release | renew | claims
tirith task create | pull | update | list
tirith contract publish | get | list
tirith notice publish | list
tirith decision record | list
tirith memory write | read | search | delete # body from --body, --file, or stdin
tirith message send | list # talk to other agents; the inbox shows on any result
tirith lead log # the swarm lead and its policy's decisions
tirith lead human # items waiting for you, most agents blocked first
tirith lead human done <id> [--reply TEXT] # answer one; the reply reaches its sender
tirith tray # macOS only: menu bar icon listing every daemon
tirith tools # list tools with descriptions
tirith call <tool> '<json>' # call any tool directly--agent sets your name, --json prints the raw result, and non-ok
outcomes exit with status 1.
Swarm lead and escalations
The session that spawns other agents claims the reserved path
.tirith/lead and becomes the swarm lead; status and the dashboard show
who holds it. The daemon then handles routine escalations with fixed
rules, without spending an LLM turn:
What is the lead's: while it holds
.tirith/lead, only the lead publishes contracts, creates tasks, records decisions, deletes memory notes and forces another agent's task; anyone else getsconflictnaming the lead and proposes the change withmessage_send(ADR-0036). With no lead nothing is gated. The lead is also the only session that commits, pushes, opens pull requests or deploys (ADR-0037).What escalates: a task set to
blocked(its note is the reason), or the third refusal of the same claim within 360 s. A message to the lead is never an escalation.Where it goes: while there is a lead, to the lead's inbox as a message from
tirith, tagged "may need the human" when it mentions credentials, permissions, spending, or destructive steps. Nothing reaches you on its own: the lead relays what needs you withmessage_sendtohuman, written for you. While there is no lead, escalations go to your queue.Your queue: the dashboard's "Needs you" list,
tirith lead human,/api/humanon the dashboard port, and the macOS tray, which lists each item's sender and first line and notifies you of new ones. Answer with the dashboard's Done button ortirith lead human done <id> --reply "..."; the reply reaches the sender as a message fromhuman.
Claim grants, refusals, waits, releases and lease ends, notice pushes, and
escalations are appended to the lead decision log: tirith lead log, or
/api/lead on the dashboard port. Design:
ADR-0027; per tool:
04-primitives.md.
Documentation
Section | Contents |
Purpose, architecture, project structure, tool reference, installation | |
The demo, client setup for every supported framework, and the swarm playbook: lead, workers, briefs, models | |
Testing strategy | |
Rust rules and their sources, git conventions | |
Architecture decision records | |
How agents work on this repo: Serena, memory, Tirith on itself | |
Release process and version bumping | |
The landing page at eabz.github.io/tirith |
Contributing
Coding agents must read AGENTS.md first. This repository is
coordinated with Tirith itself: a daemon runs for the repo and agents claim
files through it before editing. The skills in
.agents/skills/ say how.
License
Available Tools
23 toolsclaimA
Lease repo paths to yourself before editing them, atomically: every path becomes yours or none does. A directory covers its contents, and re-claiming a path you hold renews it. ok carries a brief of the unread notices, contracts, decisions and memory notes for those paths, and marks the notices shown as seen: read it before editing. conflict lists each overlapping lease; do not edit, or pass wait_secs so the daemon waits for the paths instead of you retrying. To see who holds a path without taking it use claims_list; to extend leases use renew.
Inputs: agent (required), paths (required), reason (required), brief, +2 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
claims_listARead-only
List live leases: by default yours plus any lease overlapping path, which is what a conflict check needs; all=true lists the whole board. Use before claim to see who holds a path and until when; for counts and daemon health use status. Expired leases are never listed. Newest first, 20 rows per page; pass next_before as before for older rows.
Inputs: agent (required), all, path, limit, +1 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
contract_getARead-only
Fetch one contract in full by name, id or unique id prefix: its current shape and every earlier version. Use when a brief or contract_list names a contract you consume; to find contracts by path or kind use contract_list. not_found if there is none, and an ambiguous prefix is invalid.
Inputs: name (required), agent (required). Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
contract_listARead-only
List contracts, filtered by a consumer path or by kind, most recently published first. Use to find what a path depends on when you are not claiming it, since a claim's brief already lists them; shapes come from contract_get. Rows are compact, 20 rows per page; pass next_before as before for older rows.
Inputs: agent (required), kind, path, limit, +1 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
contract_publishA
Publish the shape of an interface (an endpoint, function, type, event or CLI) before either side implements it, with the paths that will consume it. Publishing an existing name creates a new version and sends its consumers a change notice by itself, so do not also call notice_publish. Omitting consumers on a republish keeps the list, and expected_version refuses the write with conflict if another agent published first. Lead-only while a swarm has a lead. To read contracts use contract_get or contract_list.
Inputs: kind (required), name (required), agent (required), shape (required), +3 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
decision_listARead-only
List recorded decisions, filtered by an affected path or a case-insensitive text query over title, decision and rationale, newest first. Use before decision_record so nothing is decided twice; a claim's brief already carries the decisions for the paths it claims. 20 rows per page; pass next_before as before for older rows.
Inputs: agent (required), path, limit, query, +1 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
decision_recordA
Record a settled project choice with its rationale, the alternatives considered and the paths it constrains, so no agent decides it again. It is written as one committed Markdown file under .tirith/decisions/ and appears in the brief of later claims on those paths. Use only once the choice is final; for discussion use message_send, and for lessons about code use memory_write. Lead-only while a swarm has a lead. Returns the decision with its permalink.
Inputs: agent (required), title (required), decision (required), rationale, +2 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
guideARead-only
Explain what Tirith is for and how to work with it: the working loop from claim to release, the rules every reply follows (status, lost, inbox, paging), and which tool each situation calls for. Call it first in a session, or when unsure which tool fits; topic narrows it to one primitive with when to use each of its tools. Returns static guidance only: for the daemon's live state use status.
Inputs: agent, topic. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
memory_deleteADestructiveIdempotent
Delete one memory note by permalink, id or exact title, permanently: its file is removed and does not return on restart. Use to retract a note that holds a secret or a wrong fact; to correct a note use memory_write, which updates in place. Lead-only while a swarm has a lead. Returns a digest of what was removed; not_found if there is none.
Inputs: name (required), agent (required). Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
memory_readARead-only
Read one memory note in full by permalink, id or exact title. It is the only tool that returns a note's body; depth 1 to 3 adds the notes linked to it, as digests. Use after memory_search or a claim's brief names the note; to find notes use memory_search. not_found if there is none.
Inputs: name (required), agent (required), depth. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
memory_searchARead-only
Find memory notes by free text, path, kind, tag or time, best match first; with no query it lists the most recently updated, which is the call to make when a session starts. Rows are digests with a 160-character excerpt and a score, never bodies: read one with memory_read. Terms match as substrings, with no embeddings. truncated is true when limit hid matches.
Inputs: agent (required), tag, kind, path, +3 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
memory_writeAIdempotent
Save a durable note about repository paths (a lesson, trap, handoff or research) as committed Markdown; the next agent that claims those paths gets its excerpt in the brief. A title that already exists updates that note in place, and permalink targets one explicitly. Pass the updated_at you read as if_updated_at so a concurrent edit returns conflict instead of being overwritten. Not for settled choices (decision_record) or talk between agents (message_send).
Inputs: body (required), agent (required), title (required), kind, +4 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
message_listARead-only
List your own conversations, sent and received, newest first; filter by the other agent (with), since a time, or unread messages to you. New messages already arrive as inbox on every reply, so use this for history, not to poll. with=human shows the human queue thread. 20 rows per page; pass next_before as before for older rows.
Inputs: agent (required), with, limit, since, +2 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
message_sendA
Send a short message to one agent by name, to every agent active in the last hour with *, or to the human queue with human. It is delivered once, as inbox on the recipient's next call of any tool, and reply_to threads an answer. Use for coordination talk; not for lasting knowledge (memory_write, decision_record) or for code changes others must react to (notice_publish). Messages are dropped after 24 hours.
Inputs: to (required), text (required), agent (required), paths, +1 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
notice_listA
List change notices for a path, since a time, or only those you have not been shown (unread=true), newest first. unread without path is scoped to the paths you hold, and all=true looks beyond them. Listing unread notices marks them seen by you, durably, so they do not come back. A claim's brief already delivers the unread notices for the paths it claims; use this for other paths or older pages. 20 rows per page; pass next_before as before for older rows.
Inputs: agent (required), all, path, limit, +3 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
notice_publishA
Announce a change other files must react to: a rename, signature change, removal, move or behavior change, with from, to and the affected_paths. Use after changing something used outside the paths you claimed; not for interface shapes, which contract_publish versions and announces itself. Every other agent holding an affected path gets it in its inbox at once, and the rest see it in the brief of their next claim there.
Inputs: kind (required), agent (required), summary (required), affected_paths (required), +3 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
releaseAIdempotent
Give up leases so other agents can claim the paths; omit paths to release everything you hold. Use when you finish editing, not to extend time (renew) or to inspect (claims_list). Paths are matched exactly: releasing a file does not release a file#Symbol anchor inside it. not_found if you do not hold a named path, and then nothing is released.
Inputs: agent (required), paths. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
renewAIdempotent
Extend every lease you hold by its original TTL and restart the four-TTL age limit that ends a lease however active you are. Needed only during long work with no other call, because any tool call already renews; to take new paths use claim. Returns how many leases were renewed and the latest expiry; not_found when you hold none.
Inputs: agent (required). Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
statusARead-only
Report the daemon's health: counts of claims, tasks, contracts, notices, decisions and notes, the swarm lead, the last persistence failure and the files skipped at load. verbose=true adds up to 50 active agents with what they hold. Use for a health check or to find the lead; it publishes nothing and takes no lease. For your own leases use claims_list, and for how to work with Tirith use guide.
Inputs: agent, verbose. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
task_createA
Add a todo task to the shared board for any agent to pull. depends_on holds it back until those tasks are done, higher priority is pulled first, and paths lets task_pull keep agents off each other's files. Use to queue work, not to start it: task_pull assigns work and task_update changes a task. Lead-only while a swarm has a lead. Returns the task with its id.
Inputs: agent (required), title (required), paths, priority, +2 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
task_listARead-only
List tasks on the board, filtered by status or owner, most recently updated first. Use to inspect the board without taking anything; to take work use task_pull. Rows are compact, 20 rows per page; pass next_before as before for older rows.
Inputs: agent (required), limit, owner, before, +1 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
task_pullA
Take the next task: the highest-priority todo whose dependencies are done becomes in_progress and yours, preferring tasks whose paths nobody else holds. Use to get work; to look without taking use task_list, and to change a named task use task_update. none means nothing is unblocked; a task that comes with waiting_on overlaps paths others hold, so coordinate before editing them. wait_secs waits server-side for work instead of you polling.
Inputs: agent (required), wait_secs. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
task_updateAIdempotent
Change one task's status: done to finish it, todo to hand it back, blocked to park it with note as the reason, in_progress to take it by id. Changing a task another agent has in_progress is a conflict naming the owner, unless force, which is recorded in the task's notes, lead-only while a swarm has a lead. To get the next task without naming one use task_pull. Returns the task in full.
Inputs: agent (required), status (required), task_id (required), note, +1 more. Returns: Any result may also carry lost, inbox, inbox_more and persist_error; see guide.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Each tool targets a distinct primitive and action, and descriptions explicitly cross-reference alternatives (e.g., claim vs claims_list vs renew, contract_get vs contract_list). The many similar-sounding resource tools are clearly delineated by their stated use cases, so an agent can select the right one.
Compound tools follow a consistent snake_case noun_verb pattern (contract_get, decision_record, task_pull), but core primitives are single words (claim, renew, release, guide, status) and 'claims_list' uses a plural resource while most others use singular. This is mostly predictable with minor deviations.
23 tools for a multi-agent coordination daemon spanning claims, tasks, contracts, decisions, memory, messages, notices, and meta-guidance. The breadth justifies many tools, but the count sits in the heavy 16-25 range rather than the ideal 3-15.
The surface covers lifecycle operations for claims, memory, messages, notices, and contracts (via versioned publish). Tasks and decisions lack direct get/delete or update operations for some flows, but list and update calls provide workarounds, leaving only minor gaps.
Maintenance
Related MCP Connectors
Coordinate multiple AI agents over MCP: atomic claims, leases, shared ledger, handoffs, tasks.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
Shared blackboard and MCP control plane for multi-agent teams.
Team agent collaboration: shared team facts, human-confirmed writes, tasks and threads over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables peer-to-peer communication, discovery, shared state, and file coordination between AI coding agents across machines and sessions.8 npm16Elastic 2.0
- AlicenseBqualityCmaintenanceMCP server that provides a live coordination layer for AI agents, including attributable handoffs, a shared event ledger, atomic work-claiming, and advisory file leases to prevent collisions.279AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceMCP server that enforces multi-agent scope boundaries. Prevents scope drift, work duplication, and infinite delegation loops in agentic systems.51 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides MCP tools for AI coding agents to coordinate on shared repositories, enabling task claiming, conflict detection, and plan management in real-time.26 npmMIT