Tirith

io.github.eabzPublished by GitHub account eabzv1.2.0Updated Oct 24, 2026

Coordination server for parallel coding agents: claims, contracts, notices, and memory notes.

VerifiedSTDIODesktop onlyProductivity & WorkflowKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

A local coordination daemon that lets multiple coding agents claim files, share tasks, contracts, notices and path-scoped notes over MCP.

What you can do
  • Claim, release and renew leases on files or directories, and list current claims, with overlaps refused or waited out.
  • Create, pull, update and list tasks with priority, owner and dependencies.
  • Publish, fetch and list versioned interface contracts, and publish or list change notices.
  • Record and list settled decisions, and write, read, search or delete memory notes scoped to repository paths.
  • Send and list short messages between agents, and check status counts and load problems.
When to use it
Useful when several coding agents work on the same repository at once and need to avoid editing the same files, agree on interface shapes, and pass lessons between sessions. A single agent on a small project gains little from it.
Requirements
A local process installed via the install script or cargo (package tirith-mcp, binary tirith); macOS, Linux or Windows. Run tirith init in the repository to register it, and each agent passes a stable agent name with every call. The daemon serves MCP on a local HTTP port and writes state to a .tirith directory in the repository.
Before you install
It writes state into the repository: contracts, notices, decisions and memory notes are meant to be committed, while runtime data is gitignored. Agents can create, update and delete tasks, notes and messages, and the lead role gates who may publish contracts, create tasks or delete notes. Escalations may mention credentials, permissions, spending or destructive steps, which the lead relays to you.

Installation

In SourceWeft

  1. Open Tirith in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[Tirith]

Tirith

Coordination server for parallel coding agents.
Claims, a task board, interface contracts, change notices, a decisions log, path-scoped memory notes, and agent messages, over MCP.

[CI] [Release] [crates.io] [License: MIT]

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:

bash
curl -LsSf https://eabz.github.io/tirith/install.sh | sh

Windows (PowerShell):

powershell
irm https://eabz.github.io/tirith/install.ps1 | iex

With cargo (the package is tirith-mcp, the binary is tirith):

bash
cargo install tirith-mcp

Already 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.

Quick start

In the repository, run:

bash
tirith init

It 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.

ClientSetup
Claude Codeclaude mcp add tirith -- tirith stdio
Cursor.cursor/mcp.json: { "mcpServers": { "tirith": { "command": "tirith", "args": ["stdio"] } } }
Codexcodex mcp add tirith -- tirith stdio
LangGraph, CrewAI, curlconnect 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

PrimitiveToolsPurpose
Claimsclaim, release, renew, claims_listLease files or directories before editing. Overlaps are refused with the owner, reason, and expiry, or waited out server-side with wait_secs. Leases expire if the agent dies, and the agent is told on its next call.
Task boardtask_create, task_pull, task_update, task_listTasks with priority, owner, and dependencies. Agents pull the next unblocked task, skipping tasks another agent holds, and can wait server-side for one with wait_secs; a task whose owner goes silent returns to the board.
Contractscontract_publish, contract_get, contract_listInterface shapes published and versioned before implementation. A new version notifies its consumers automatically.
Change noticesnotice_publish, notice_list"Renamed X to Y, these paths are affected." Dependents get them in the brief that comes back with a claim, once each.
Decisions logdecision_record, decision_listSettled choices with rationale, so nothing is decided twice.
Memory notesmemory_write, memory_read, memory_search, memory_deleteLessons, traps, and handoffs scoped to repository paths. Committed Markdown, searchable, and delivered to whoever claims the paths a note is about.
Messagesmessage_send, message_listShort notes between agents, delivered on the recipient's next call, so any MCP client can take part. Runtime only.
StatusstatusCounts, persistence and load problems; verbose adds who holds what.

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:

bash
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:

bash
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 alicetirith 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.

bash
tirith serve                               # run the repo's daemon by handtirith stdio                               # per-session shim clients spawn; starts the daemon if neededtirith update                              # replace the binary with the latest releasetirith status                              # counts, and who holds whattirith init [--file AGENTS.md] [--instructions]  # register the server, add the agents blocktirith claim | release | renew | claimstirith task     create | pull | update | listtirith contract publish | get | listtirith notice   publish | listtirith decision record | listtirith memory   write | read | search | delete   # body from --body, --file, or stdintirith message  send | list                # talk to other agents; the inbox shows on any resulttirith lead log                            # the swarm lead and its policy's decisionstirith lead human                          # items waiting for you, most agents blocked firsttirith lead human done <id> [--reply TEXT] # answer one; the reply reaches its sendertirith tray                                # macOS only: menu bar icon listing every daemontirith tools                               # list tools with descriptionstirith 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 gets conflict naming the lead and proposes the change with message_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 with message_send to human, 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/human on 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 or tirith lead human done <id> --reply "..."; the reply reaches the sender as a message from human.

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

SectionContents
1-aboutPurpose, architecture, project structure, tool reference, installation
2-examplesThe demo, client setup for every supported framework, and the swarm playbook: lead, workers, briefs, models
3-testsTesting strategy
4-styleRust rules and their sources, git conventions
5-decisionsArchitecture decision records
6-agent-workflowHow agents work on this repo: Serena, memory, Tirith on itself
7-releaseRelease process and version bumping
index.htmlThe 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

MIT

Source: README.md at commit 5036a0f

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v1.2.0LatestSep 19, 2026
  2. v1.1.1Sep 18, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts