andreseloysv/Tirith

An autonomous manager for your coding agents. They finish the plan; you see everything and decide only what only you can.
Landing page · Submission · Contributing
⭐ If Tirith helps you, please star the repo. It is the best way to say it is useful.
## Quick start
bash
git clone https://github.com/andreseloysv/Tirith && cd Tirith && ./run --demo
No agents or keys needed: it opens the page on demo data. Requires uv and a browser.
Problem. You run several coding agents at once. You ask "what is everyone doing?" all day, you
re-explain the rules, and the agents ask you things they could settle themselves.
Solution. Tirith keeps a plan, starts agents only from plan items, checks what they report, merges what
passes and answers questions in a chat. Rules are code that blocks, not text the agent may ignore.
Result. You open the app, see what runs and what is done, and are asked only what needs you: a password,
a payment, a choice that is yours.
Built for the Meta Global AI Developer Hackathon (track: Build for Your World).
Everything in this repository was created during the hackathon, starting 2026-10-28.
Submission text for the judges: docs/SUBMISSION.md.
## What it does
Every item below is on main; the contract file named next to it says exactly how it works.
### Plan-driven
Agents start only from a plan item. tirith lane run and tirith launch refuse to start without an open
item of the project's plan (--step N --item "..."). No item, no agent. (CONTRACT-roadmap.md, CONTRACT-launch.md)
Every agent reports an outcome (tirith plan report --status done|partial|blocked). A lane that ends without one is not merged; its item is reopened and it is started once more.
Tirith is the only plan writer. Agents cannot edit the plan file (the roadmap-edit rule); they ask Tirith with tirith plan add.
Items are ticked when the work is on main, not when an agent says so.
No duplicate agents on the same plan item.
Shared task coordination. Permanent task IDs, explicit prerequisites, atomic claims and declared
write reservations let independent items in one step proceed together. Worker inboxes support durable
handoffs and acknowledgements. (CONTRACT-coordination.md)
### Rules in code
Each rule is checked by code, in a hook that runs before the agent's tool call, and the refusal tells the agent
the exact command to use instead (CONTRACT-gates.md). In plain words:
Tests and builds run through Tirith (tirith run --stage ...), so they show up in Pipelines.
An agent may not start another agent or its own sub-agents; helpers start through Tirith so you can see them.
Nobody skips the checks that run before a commit (--no-verify, core.hooksPath, .git/hooks are blocked).
Agents may not edit the plan, the agents' settings files or Tirith's config.
A lane starts only with a written brief, a passing project check and an intact commit guard.
Custom rules per project in tirith.toml, enforced the same way.
Owner gate: nothing reaches you unless only you can do it (credentials, payment, personal account,
physical device, your decision). Everything else goes to the manager. (CONTRACT-inbox.md)
Claim check: before a merge, the agent's report is compared with the real change: files it says it