@jjanczur/tyran 0.1.27 → 0.1.29
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +137 -0
- package/README.md +69 -29
- package/package.json +1 -1
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
{
|
|
12
12
|
"name": "tyran",
|
|
13
13
|
"description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
|
|
14
|
-
"version": "0.1.
|
|
14
|
+
"version": "0.1.29",
|
|
15
15
|
"source": "./",
|
|
16
16
|
"author": {
|
|
17
17
|
"name": "Jacek Janczura",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "tyran",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.29",
|
|
4
4
|
"description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Jacek Janczura",
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,142 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.29 — 2026-08-16
|
|
4
|
+
|
|
5
|
+
Tyran has videos. Five cuts, and a page that says which one to send.
|
|
6
|
+
|
|
7
|
+
### The slate
|
|
8
|
+
|
|
9
|
+
A 3:20 explainer, a 3:53 first-session tutorial, and three vertical shorts —
|
|
10
|
+
the mistake, the board, the retrospective. Built with Hyperframes (HTML in,
|
|
11
|
+
deterministic MP4 out) and a Gemini voiceover, with burned-in captions and an
|
|
12
|
+
`.srt` sidecar each.
|
|
13
|
+
|
|
14
|
+
They are not five lengths of one video, which is the point of
|
|
15
|
+
[`docs/videos.md`](docs/videos.md): each answers a different question, and the
|
|
16
|
+
shorts and the tutorial fail at each other's jobs. The explainer argues, the
|
|
17
|
+
tutorial instructs, the board short shows rather than argues, and the retro
|
|
18
|
+
short is the only one whose subject is restraint.
|
|
19
|
+
|
|
20
|
+
### The written surfaces now say what the video says
|
|
21
|
+
|
|
22
|
+
The README and the landing hero were accurate and abstract where the explainer
|
|
23
|
+
is concrete. Both now open on the same sentence it does — your most expensive
|
|
24
|
+
model renaming a variable in the same chat it judged an authentication
|
|
25
|
+
boundary — and carry the manager framing through to the board, the bill and the
|
|
26
|
+
retro. Two descriptions of one product drifting apart is the defect this repo
|
|
27
|
+
calls ADR-21, and the video is now the widest-reach description of Tyran, so it
|
|
28
|
+
is the one the prose should agree with.
|
|
29
|
+
|
|
30
|
+
### The claims in the explainer, checked against the code
|
|
31
|
+
|
|
32
|
+
Every spoken claim was audited (`NOTES-REQUESTS.md` §10). Nine are exact, and
|
|
33
|
+
several turn out to be near-verbatim quotes of the mechanism's own
|
|
34
|
+
documentation: the four-question interview batch, the reviewer that ships with
|
|
35
|
+
no editing tools, the role floor applied after both the risk shift and the
|
|
36
|
+
override, and the three-to-knowledge / five-to-law ladder.
|
|
37
|
+
|
|
38
|
+
Two are not, and are recorded rather than quietly left:
|
|
39
|
+
|
|
40
|
+
- **"cheap tier, read only"** — the scout is granted `Bash`. *"You change
|
|
41
|
+
nothing"* is the first line of its instructions, which is the one form of
|
|
42
|
+
guarantee this project refuses to accept anywhere else. The fix is a
|
|
43
|
+
read-only agent class in the policy gate, not a rewording.
|
|
44
|
+
- **"this is not an estimate, it is the bill"** — the figures are exactly what
|
|
45
|
+
the sandbox board shows (404 requests, 4.53M tokens, 54.9% conductor) and the
|
|
46
|
+
rollup computing them is the real one, but the usage feeding it is authored,
|
|
47
|
+
and the board honestly labels those models `sample-large` / `sample-small`.
|
|
48
|
+
Publishing a real `cost.json` into the sandbox makes the line true and makes
|
|
49
|
+
the sandbox a better artefact than the video.
|
|
50
|
+
|
|
51
|
+
### What is in the repository, and what is not
|
|
52
|
+
|
|
53
|
+
The video *sources* are tracked — compositions, the voiceover pipeline, the
|
|
54
|
+
scripts, the storyboards — because they are text and they are how a cut gets
|
|
55
|
+
rebuilt. The renders are not. They come to roughly 430 MB, and this repository
|
|
56
|
+
is what `/plugin marketplace add jjanczur/tyran` clones, so committing them
|
|
57
|
+
would put marketing video into every install of the plugin. Git LFS was
|
|
58
|
+
considered and rejected on the same ground: a clone without `git-lfs` gets
|
|
59
|
+
pointer files, which breaks both the Pages build and the install.
|
|
60
|
+
|
|
61
|
+
`assets/video/` carries 1.1 MB of poster frames and caption sidecars, which is
|
|
62
|
+
everything the README and the docs page actually reference. The cuts live on
|
|
63
|
+
YouTube, and their IDs live in exactly one file,
|
|
64
|
+
`site/src/data/videos.json`.
|
|
65
|
+
|
|
66
|
+
Tyran's own secrets gate refused the first attempt at that commit — the payload
|
|
67
|
+
was past the 4 MiB it can scan inside its budget, and it refuses rather than
|
|
68
|
+
scanning a prefix, because a partial scan that reports nothing looks exactly
|
|
69
|
+
like a clean one. That is the gate behaving as designed, and it is what forced
|
|
70
|
+
the question of which bytes really needed to be in the tree. Two MP4s turned
|
|
71
|
+
out to be referenced by nothing.
|
|
72
|
+
|
|
73
|
+
## 0.1.28 — 2026-08-15
|
|
74
|
+
|
|
75
|
+
A maintenance release: the documentation site's dependencies, and three
|
|
76
|
+
numbers in the prose that had gone stale because nothing was watching them.
|
|
77
|
+
|
|
78
|
+
### Five vulnerabilities, now zero
|
|
79
|
+
|
|
80
|
+
`npm audit` in `site/` reported five, three of them high, all transitive:
|
|
81
|
+
nanoid's infinite loop on a zero size, js-yaml, fast-uri, dompurify, and
|
|
82
|
+
mermaid's prototype pollution. `npm update` and `npm audit fix` clear all five
|
|
83
|
+
and carry astro 7.1.4 to 7.2.2, starlight 0.41.4 to 0.41.7 and playwright
|
|
84
|
+
1.62.0 to 1.62.1. Lockfile only — no range in `package.json` moved, and the
|
|
85
|
+
plugin itself still has zero runtime dependencies, which is the property that
|
|
86
|
+
keeps this whole section confined to `site/`.
|
|
87
|
+
|
|
88
|
+
Verified against the built site rather than asserted: `astro check` reports 0
|
|
89
|
+
errors over 27 files, the build produces 18 pages, 488 of 488 root-absolute
|
|
90
|
+
URLs carry the `/tyran` base prefix, the browser pass finds 0 broken links and
|
|
91
|
+
0 console errors across every page, and the worst mermaid contrast is 5.68:1
|
|
92
|
+
against a floor of 3.
|
|
93
|
+
|
|
94
|
+
**TypeScript stays on 6.** `@astrojs/check` is at its newest release, 0.9.10,
|
|
95
|
+
and still declares `typescript: ^5.0.0 || ^6.0.0` — and `astro check` is what
|
|
96
|
+
the Pages workflow runs, so accepting TS 7 breaks the deploy rather than a
|
|
97
|
+
test. Dependabot now ignores that major with the reason written beside it.
|
|
98
|
+
|
|
99
|
+
The four Dependabot PRs this closes had been open for ten days. They were
|
|
100
|
+
*security* updates, which arrive ungrouped and without the seven-day cooldown,
|
|
101
|
+
so four one-line lockfile changes became four review cycles nobody ran. Both
|
|
102
|
+
tracks are grouped now: one chore a month instead of a queue.
|
|
103
|
+
|
|
104
|
+
### Three numbers that were wrong
|
|
105
|
+
|
|
106
|
+
The house rule is that a number in the prose is a claim, verified against the
|
|
107
|
+
thing it describes. These three were claims nothing verified.
|
|
108
|
+
|
|
109
|
+
- The README said **1314 unit tests**; the suite has 1405.
|
|
110
|
+
`docs-claims.test.mjs` pins every such claim on the docs surfaces, but each
|
|
111
|
+
of those is about ONE test file and is counted by running it. The README's
|
|
112
|
+
is about the whole suite, which no unit test can count without running the
|
|
113
|
+
suite from inside itself. CI now compares it against the full run it already
|
|
114
|
+
performs for the skipped-test check, so the guard costs nothing.
|
|
115
|
+
- The README said the board has **four tabs**. It has had five since 0.1.24,
|
|
116
|
+
and `docs/board.md` said five throughout. One surface moved, the other did
|
|
117
|
+
not — the failure the two-surfaces rule exists to prevent, on the one
|
|
118
|
+
surface that rule does not name.
|
|
119
|
+
- `templates/config.yaml` keeps **63** comment lines out of 90, not 60.
|
|
120
|
+
|
|
121
|
+
`assets/board-demo.gif` was recorded at 0.1.22 and moves through four tabs, so
|
|
122
|
+
it predates the Settings tab. Its alt text no longer claims to show the whole
|
|
123
|
+
page; the re-record needs a live board and a screen recorder, so it is written
|
|
124
|
+
down as an open item rather than quietly left wrong.
|
|
125
|
+
|
|
126
|
+
### The browser check had been shrinking
|
|
127
|
+
|
|
128
|
+
`site/scripts/check-browser.mjs` carried a hand-written list of 14 slugs while
|
|
129
|
+
the site had grown to 17 pages. The three it missed — board, overnight, cost —
|
|
130
|
+
were the three newest, which is to say the likeliest to carry a relative link
|
|
131
|
+
nobody had clicked. It reads the content directory now, so the list cannot
|
|
132
|
+
fall behind again. All 17 pass, 18 internal links, 0 broken. A check whose
|
|
133
|
+
coverage silently shrinks as the thing it checks grows is worse than no check,
|
|
134
|
+
because it still prints OK.
|
|
135
|
+
|
|
136
|
+
Astro 7's `preview` daemonizes and returns, so the `npm run preview -- &` in
|
|
137
|
+
both check-script headers no longer described what happens: the server
|
|
138
|
+
outlives the shell that started it and needs `astro preview stop`.
|
|
139
|
+
|
|
3
140
|
## 0.1.27 — 2026-08-15
|
|
4
141
|
|
|
5
142
|
The last four items of the munder-difflin plan, and the half of the model
|
package/README.md
CHANGED
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
<p align="center">
|
|
15
15
|
<b><a href="https://jjanczur.github.io/tyran/">📖 Documentation</a></b> ·
|
|
16
16
|
<a href="https://jjanczur.github.io/tyran/getting-started/">Getting started</a> ·
|
|
17
|
+
<a href="https://jjanczur.github.io/tyran/videos/">Videos</a> ·
|
|
17
18
|
<a href="https://jjanczur.github.io/tyran/architecture/">Architecture</a> ·
|
|
18
19
|
<a href="https://github.com/jjanczur/tyran/releases/latest">Releases</a>
|
|
19
20
|
</p>
|
|
@@ -22,44 +23,56 @@
|
|
|
22
23
|
|
|
23
24
|
## What Tyran is
|
|
24
25
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
rather than something you can check. Start a new session and you start
|
|
28
|
-
explaining from the beginning.
|
|
26
|
+
Your most expensive model just renamed a variable. In the same chat, it judged
|
|
27
|
+
an authentication boundary.
|
|
29
28
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
29
|
+
One chat, one model, every job — that is why the bill is high and the work gets
|
|
30
|
+
worse. The context fills up, the plan is somewhere in the scrollback, and
|
|
31
|
+
*"the tests pass"* is a sentence rather than something you can check.
|
|
32
|
+
|
|
33
|
+
**You didn't install a tool. You hired a manager.** You describe the work once;
|
|
34
|
+
he interviews you until the goal is unambiguous — batches of at most four
|
|
35
|
+
questions, each with his recommendation — turns the plan into tickets on a
|
|
36
|
+
board, and hands each piece to a **dedicated subagent with fresh context and a
|
|
37
|
+
model tier matched to how hard that piece actually is.** A good manager doesn't
|
|
38
|
+
put a principal engineer on a grep: a scout reads the repo on the cheap tier,
|
|
39
|
+
implementers take one story each on their own branch, the reviewer has no
|
|
40
|
+
editing tools at all, and security review always gets the strongest tier — a
|
|
41
|
+
floor no cost profile or flag can lower.
|
|
36
42
|
|
|
37
43
|
That is a cost lever and a quality lever at the same time. The conductor holds
|
|
38
44
|
the plan and never accumulates its agents' transcripts, which is where the
|
|
39
45
|
tokens in a long session actually go; and an agent that never saw the last six
|
|
40
46
|
failed attempts cannot inherit them, so the second opinion is a real one.
|
|
41
47
|
|
|
48
|
+
**Nothing you say is lost.** Remember something halfway through a run and say
|
|
49
|
+
it — it doesn't land in the scrollback, it becomes a ticket. Every decision,
|
|
50
|
+
spawn, report, merge and open question is appended to a journal **committed to
|
|
51
|
+
your repo**, so a restart, a compaction and a colleague on another branch all
|
|
52
|
+
read the same thing.
|
|
53
|
+
|
|
42
54
|
**It learns your repo while it works.** Setup reads how the repo is really
|
|
43
55
|
worked — stack, validation commands, how things get deployed — rather than
|
|
44
|
-
asking you to describe it.
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
Underneath, **
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
56
|
+
asking you to describe it. After every initiative the team runs a retrospective
|
|
57
|
+
on itself, and what it changes is Tyran, never your product code. The same
|
|
58
|
+
failure three times becomes knowledge pasted into every matching handoff; five
|
|
59
|
+
times and it becomes a rule in your `CLAUDE.md`, carrying the dates that earned
|
|
60
|
+
it. Most retros correctly change nothing.
|
|
61
|
+
|
|
62
|
+
All of it lands on one page — a **board**: what every agent is doing right now,
|
|
63
|
+
which questions are waiting on you (answer them there and the run carries on),
|
|
64
|
+
and what the work cost, in the tokens the platform itself reported, per model,
|
|
65
|
+
per agent and per ticket. The conductor gets its own row, so its overhead never
|
|
66
|
+
hides inside the total.
|
|
67
|
+
|
|
68
|
+
Underneath, **a hook decides before the tool ever runs** — none of this is a
|
|
69
|
+
prompt asking nicely. A report with no raw command output is refused: it blocks
|
|
70
|
+
silence, not forgery. Every write is classified against a policy file you own.
|
|
71
|
+
And a commit carrying a secret is refused, even inside a markdown file.
|
|
72
|
+
Mechanisms rather than instructions — which is the whole argument.
|
|
60
73
|
|
|
61
74
|
<p align="center">
|
|
62
|
-
<img src="assets/board-demo.gif" width="100%" alt="The Tyran dashboard, recorded live, moving through its
|
|
75
|
+
<img src="assets/board-demo.gif" width="100%" alt="The Tyran dashboard, recorded live, moving through four of its tabs: Overview with what is waiting on you and the strip of running agents each showing the time since it last signalled; Board, where selecting a ticket opens its initiative, agents and spend; Waiting on you, the open questions above the commands that answer them; and Spend, toggling the same split between tokens and cost">
|
|
63
76
|
</p>
|
|
64
77
|
|
|
65
78
|
<p align="center">
|
|
@@ -68,6 +81,31 @@ than instructions — which is the whole argument.
|
|
|
68
81
|
lanes, select a card.
|
|
69
82
|
</p>
|
|
70
83
|
|
|
84
|
+
### Watch it
|
|
85
|
+
|
|
86
|
+
<table>
|
|
87
|
+
<tr>
|
|
88
|
+
<td width="50%" align="center">
|
|
89
|
+
<a href="https://youtu.be/ThulYtbYNXI"><img src="assets/video/a-explainer-16x9.jpg" width="100%" alt="Still from the Tyran explainer: the routing table, with each role resolving to a model tier"></a><br>
|
|
90
|
+
<b><a href="https://youtu.be/ThulYtbYNXI">You Didn't Install a Tool — You Hired a Manager</a></b><br>
|
|
91
|
+
3:20 · the whole argument, end to end
|
|
92
|
+
</td>
|
|
93
|
+
<td width="50%" align="center">
|
|
94
|
+
<a href="https://youtu.be/vr49hKk9G8g"><img src="assets/video/a-onboarding-16x9.jpg" width="100%" alt="Still from the Tyran onboarding video: the install commands typed into a terminal"></a><br>
|
|
95
|
+
<b><a href="https://youtu.be/vr49hKk9G8g">Your First Session</a></b><br>
|
|
96
|
+
3:53 · install, run, read the board
|
|
97
|
+
</td>
|
|
98
|
+
</tr>
|
|
99
|
+
</table>
|
|
100
|
+
|
|
101
|
+
<p align="center">
|
|
102
|
+
Three 60-second cuts too —
|
|
103
|
+
<a href="https://www.youtube.com/shorts/2EgRBR0fVRo">the mistake</a> ·
|
|
104
|
+
<a href="https://www.youtube.com/shorts/HKePDLkYDqA">the board</a> ·
|
|
105
|
+
<a href="https://www.youtube.com/shorts/EMcPJj7c0mk">the retro</a> —
|
|
106
|
+
and <a href="https://jjanczur.github.io/tyran/videos/">which to send when</a>.
|
|
107
|
+
</p>
|
|
108
|
+
|
|
71
109
|
## What it gives you
|
|
72
110
|
|
|
73
111
|
- **Reports that carry evidence, or are refused.** A `SubagentStop` hook
|
|
@@ -204,7 +242,7 @@ open .tyran/state/board.html # xdg-open on Linux, start on Windows
|
|
|
204
242
|
— and inside a session you need neither command, because **`/tyran:status`
|
|
205
243
|
regenerates the board and tells you where it is.**
|
|
206
244
|
|
|
207
|
-
|
|
245
|
+
Five tabs, because the page answers five questions:
|
|
208
246
|
|
|
209
247
|
- **Overview** — what is waiting on you, agents running, progress, and what
|
|
210
248
|
needs a human (blocked lanes **and** blocked agents); then the agent strip,
|
|
@@ -220,6 +258,8 @@ Four tabs, because the page answers four questions:
|
|
|
220
258
|
- **Spend** — tokens, the amount under your rate card, the conductor's share, a
|
|
221
259
|
composition bar across input / cache write / cache read / output, and three
|
|
222
260
|
ranked charts (by model, agent type, ticket) with a tokens/cost toggle.
|
|
261
|
+
- **Settings** — what Tyran is configured to do, every knob with the sentence
|
|
262
|
+
that explains it. Read-only until you pass `--write`, as above.
|
|
223
263
|
|
|
224
264
|
Spend is served rather than embedded, so it is the one thing missing when you
|
|
225
265
|
open the file directly — [the board](https://jjanczur.github.io/tyran/board/)
|
|
@@ -257,7 +297,7 @@ enforces the cap (4352 of 5000 characters). What each one assumes, when it
|
|
|
257
297
|
fires and who invokes it, is in
|
|
258
298
|
[skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
|
|
259
299
|
themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
|
|
260
|
-
it:
|
|
300
|
+
it: 1405 unit tests, run with `node --test "tests/**/*.test.mjs"`.
|
|
261
301
|
|
|
262
302
|
## Documentation
|
|
263
303
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jjanczur/tyran",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.29",
|
|
4
4
|
"description": "Command-line scripts for the Tyran task conductor (doctor, journal, schema, and repo tooling) for CI and terminals outside Claude Code. Installing this package does NOT install the Claude Code plugin — add that separately with `/plugin marketplace add jjanczur/tyran` inside Claude Code.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|