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.

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.

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.

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.

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. To read contracts use contract_get or contract_list.

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.

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. Returns the decision with its permalink.

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.

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. Returns a digest of what was removed; not_found if there is none.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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. Returns the task with its id.

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.

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.

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. To get the next task without naming one use task_pull. Returns the task in full.