tyran

📖 Documentation · Getting started · Videos · Architecture · Releases

The more you use it, the better it gets.

What Tyran is

Your most expensive model just renamed a variable. In the same chat, it judged an authentication boundary.

One chat, one model, every job — that is why the bill is high and the work gets worse. The context fills up, the plan is somewhere in the scrollback, and "the tests pass" is a sentence rather than something you can check.

You didn't install a tool. You hired a manager. You describe the work once; he interviews you until the goal is unambiguous — batches of at most four questions, each with his recommendation — turns the plan into tickets on a board, and hands each piece to a dedicated subagent with fresh context and a model tier matched to how hard that piece actually is. A good manager doesn't put a principal engineer on a grep: a scout reads the repo on the cheap tier, implementers take one story each on their own branch, the reviewer can never bless a patch it wrote, and security review always gets the strongest tier — a floor no cost profile or flag can lower.

That is a cost lever and a quality lever at the same time. The conductor holds the plan and never accumulates its agents' transcripts, which is where the tokens in a long session actually go; and an agent that never saw the last six failed attempts cannot inherit them, so the second opinion is a real one.

Nothing you say is lost. Remember something halfway through a run and say it — it doesn't land in the scrollback, it becomes a ticket. Every decision, spawn, report, merge and open question is appended to a journal committed to your repo, so a restart, a compaction and a colleague on another branch all read the same thing.

It learns your repo while it works. Setup reads how the repo is really worked — stack, validation commands, how things get deployed — rather than asking you to describe it. After every initiative the team runs a retrospective on itself, and what it changes is Tyran, never your product code. The same failure three times becomes knowledge pasted into every matching handoff; five times and it becomes a rule in your CLAUDE.md, carrying the dates that earned it. That knowledge does not only grow: entries the counters have written off are retired on evidence, and two that say one thing are merged by appending a third that supersedes both — the originals stay on disk, so an unwanted merge is one file to delete. Most retros correctly change nothing.

All of it lands on one page — a board: what every agent is doing right now, which questions are waiting on you (answer them there and the run carries on), and what the work cost, in the tokens the platform itself reported, per model, per agent and per ticket. The conductor gets its own row, so its overhead never hides inside the total.

Underneath, a hook decides before the tool ever runs — none of this is a prompt asking nicely. A report with no raw command output is refused: it blocks silence, not forgery. Every write is classified against a policy file you own. And a commit carrying a secret is refused, even inside a markdown file. Mechanisms rather than instructions — which is the whole argument.

▶ Open the sandbox board — the real page with sample data, in your browser. Click the tabs, filter the lanes, select a card.

Watch it

You Didn't Install a Tool — You Hired a Manager 3:20 · the whole argument, end to end

Your First Session 3:53 · install, run, read the board

Three 60-second cuts too — the mistake · the board · the retro — and which to send when.

What it gives you

• Reports that carry evidence, or are refused. A SubagentStop hook rejects a report with no raw command output — measured on 55 real reports from this project's own agents: 53 pass, and both misses were not reports. It blocks silence, not forgery; the evidence gate is precise about the difference.
• State you can read without a session. The journal is the single source of truth; STATE.md, PROGRESS.md, BOARD.md, board.json and board.html are generated projections of it.
• The routing table is one file. Model names appear in exactly one place; skills, agents and policies are written in role names, so a deprecation is a one-line edit. The expensive tier is reserved for security review, arbitration and final acceptance, and those two sit on a floor no cost profile or risk flag can cross.
• A spend ledger. npx @jjanczur/tyran cost reports what the work cost, in the tokens the platform itself reported, per model, per agent type and per ticket — read out of the transcripts Claude Code already writes. Dollars need no setup: the published list prices ship, so a fresh install shows what the run would have cost through the API, next to what your plan costs a month. Write a rate card only to override them.
• It can run overnight, because the usage limit is a wind-down and not a crash. The platform's own behaviour at the limit is a cliff: calls start failing mid-flight and agents die between a write and its commit. Near the threshold Tyran instead checkpoints, commits the state files, schedules a resume and stops — then a watcher wakes at the window reset and continues the same session. Leave it working and read the board in the morning. Both windows were hit live while the feature was being built; the protocol that survived them is what shipped. See overnight mode.

Tyran vs. an ordinary session

The axis, not the winner — a comparison that can be made without guessing at anyone's internals.

Tyran vs. other Claude Code orchestrators

Five rows of eleven, verified against those projects' code and public issue trackers (July 2026) rather than their READMEs. ✅ shipped and enforced · ⚠️ partial or prompt-only · ❌ absent or broken · 🎯 committed in the design, ships test-gated.

¹ Their deliverable check is explicitly non-blocking. ² Their issues #32/#33/#36: a crash loses loop state. ³ Open issues #3535/#3536: an update deletes user files from ~/.claude. The other six rows — repo-specific learning, cost tiers, independent review, context budget, safe parallelism, OSS hygiene — and every footnote in full are in the FAQ.

Worth knowing before tuning anything: cache reads were measured at roughly three quarters of a real session's cost, and the conductor's own context at between 44% and 86% of a tree's tokens — so the lever is context size and turn count, not the price of a model.

Install

One command, then one restart, then one paste:

curl -fsSL https://raw.githubusercontent.com/jjanczur/tyran/main/install.sh | sh

It checks Node, installs the plugin, installs the secrets scanner the write gate needs, and prints the prompt to paste after you restart — which runs setup and opens the dashboard in your browser.

Tyran refuses some things by default — reading a .env, writing outside the repository, pushing past your autonomy class. If you would rather it did not, boundaries: {preset: open} in .tyran/config.yaml relaxes all five at once, and the dashboard's Settings tab has the switch. Secret scanning at commit and push is not one of the five and cannot be turned off from there. See configuration.

Or do it by hand, inside Claude Code:

/plugin marketplace add jjanczur/tyran
/plugin install tyran@tyran
/tyran:hello

Restart Claude Code afterwards — hooks and agents are read when a session starts, so an install you have not restarted into is an install you are not running. /tyran:hello is the smoke test. The only requirement is Claude Code ≥ 2.1: the scripts ship with the plugin and Claude Code runs them, so there is nothing to install and no version of anything else to match. /plugin is a slash command a human has to type — the prompt that has Claude Code install itself, the npm package for a shell or a CI job, updating and uninstalling are all in getting started.

Use it

/tyran:setup          # once per repo: scans it, writes .tyran/, installs /tyran
/tyran                # then describe what you want done

Setup infers your stack, your validation commands and your deployment autonomy class from how the repo is actually worked, annotates every value with the fact that produced it, and asks only about what it could not establish. /tyran then interviews you, sizes the work, and either does it itself or drives the roster — tyran:scout, tyran:implementer, tyran:reviewer, tyran:retro — through it, stopping only at genuine decisions. Also /tyran:status, /tyran:doctor, /tyran:retro.

Hit the brake at any time, from anywhere, without killing the session:

echo "wrong branch — hold everything" > .tyran/STOP

The dashboard

It is already running. /tyran:setup writes board: autostart: true, so every session after it starts the dashboard if it is not up and prints the URL — open that. The board is bound to loopback, re-rendered on every request, and it reloads itself every 30 seconds.

The Settings tab is an editor for .tyran/config.yaml and the autonomy policy — every knob with a sentence explaining it, your comments kept, and loosening a boundary behind a second deliberate press. Setup turns it on; board: write: false makes the board read-only, autostart: false stops it starting at all.

From a plain shell — outside Claude Code, or in a script:

npx @jjanczur/tyran board --dir .tyran --detach   # starts it, prints the URL, returns
npx @jjanczur/tyran board --dir .tyran --status   # where is it, if anywhere
npx @jjanczur/tyran board --dir .tyran --stop     # ends it

--serve instead of --detach holds the terminal until Ctrl-C, which is what you want only if you are a person at a prompt. --port <n> if 4173 is taken. These are the one place a Node version matters, because npx runs the scripts outside Claude Code and they need Node ≥ 22.

No terminal, no server: the same page is written to .tyran/state/board.html after every agent, so you can just open the file —

open .tyran/state/board.html      # xdg-open on Linux, start on Windows

— and inside a session you need neither command, because /tyran:status regenerates the board and tells you where it is.

Five tabs, because the page answers five questions:

• Overview — what is waiting on you, agents running, progress, and what needs a human (blocked lanes and blocked agents); then the agent strip, stalest first, each chip carrying its last signal and what it said it would do next. Anything a journal could not account for is listed here rather than quietly dropped.
• Board — every ticket in exactly one of ten kanban lanes, strongest verdict first. Click a card for its initiative, agents, note, spend, and the files that initiative actually has on disk.
• Waiting on you — the open questions with their recommendations and recorded defaults, above the commands that answer them. The count sits in the tab label, so a pending question survives being on another tab.
• Spend — tokens, the amount under your rate card, the conductor's share, a composition bar across input / cache write / cache read / output, and three ranked charts (by model, agent type, ticket) with a tokens/cost toggle.
• Settings — what Tyran is configured to do, every knob with the sentence that explains it. Read-only until you pass --write, as above.

Spend is served rather than embedded, so it is the one thing missing when you open the file directly — the board says why, and covers the lanes, the drill-down and answering a question.

What ships

Fourteen skills and five agents. Six of the skills are the conductor's own machinery, though commands rather than internals — /tyran:doctor runs on any repo, initiative or not — and the other eight are standalone protocols.

Agents: tyran:scout (recon, read-only), tyran:implementer (one story, own branch), tyran:reviewer (may fix what it finds, but editing forfeits APPROVE — it can never bless its own patch), tyran:verifier (runs the suite on the cheapest tier, reports raw counts, never fixes), tyran:retro. A skill is admitted only when something already asks for the protocol by name, and every description is loaded into every session whether the skill fires or not — so the combined length is capped and CI enforces the cap (3868 of 5000 characters). What each one assumes, when it fires and who invokes it, is in skills and agents; the prompts themselves are in skills/ and agents/. Behind all of it: 1659 unit tests, run with node --test "tests/**/*.test.mjs".

Documentation

Everything below also reads as a site, with search and rendered diagrams: jjanczur.github.io/tyran.

License

Apache-2.0

From Berlin with ♥ by two buddies — Jacek and Piotr.