What changes on day one

See it at work

Three moments from a session. Step through them.

$ git push --tagsyokoten: git push --tags pushes tags. Only the owner decides when to release. If the owner asked for this, they start the session with YOKOTEN_RELEASE_APPROVAL set.

yokoten: stage 1 of 5, safety net. Next: no AGENTS.md, so the agents have no written rules here; `yokoten init` adds one.Why: an agent follows the rules it can read, and only those.Tell the user in plain words, one step at a time, and offer to do it (as-is, lighter, or not now with a reason).

The road

Software teams work in a loop: plan, build, test, review, release. yokoten takes you along it one stage at a time. The yokoten repo does every stage itself, so you can see it working.

1. 1

   doctor: stage 1 · safety net

   Safety net◉ you are here

   You don’t have to work out where you are. doctor reads your project’s files and says it, for example stage 1 of 5, safety net. A new project starts at stage 1. The order is advice, not a gate.

   You learn

   rules your agents read, and checks that stop them when rules aren’t enough

   See it here

   AGENTS.md

2. 2

   doctor: stage 2 · issues and pull requests

   Issues and pull requests

   You learn

   every change starts as an issue and merges only when CI passes; labels, milestones, and a board keep track

   See it here

   issues, pull requests, the board

3. 3

   doctor: stage 3 · release

   Release

   You learn

   commit messages that say what changed and why, a changelog, a version number for every release

   See it here

   CHANGELOG.md

4. 4

   doctor: stage 4 · a team of agents

   A team of agents

   You learn

   a bot opens pull requests, workers take tasks, a reviewer checks them; only you merge

   See it here

   the guide

5. 5

   doctor: stage 5 · going public

   Going public

   You learn

   scan every past commit for private data, turn on security settings, protect main

   See it here

   security policy

The road to the dream

Each milestone covers more of the cycle, for more people and more tools.

1. Now, before 26 Oct 2026

   doctor walks you along the road; a release flow; checks on GitHub settings; npx yokoten; the same guard in Codex and Gemini CLI

   M0

2. Meta hackathon, 26 Oct – 3 Nov

   an agent that reads an old project and drafts how to adopt yokoten; Muse Code support

   M1

3. Next

   Gitea and other code hosts; a short spec before larger changes; the OpenSSF Best Practices badge as public proof

   issues

Every step is planned in the open: the board shows what is being built today, and the milestones show what comes next.

Quick start

You need Node 22.18 or later. Nothing else: no build step, no dependencies.

$ git clone https://github.com/coo1white/yokoten$ node yokoten/bin/yokoten.ts install  # once per computer$ cd your-project$ node ~/.local/share/yokoten/bin/yokoten.ts init  # once per project

A one-command npx yokoten comes with the npm release.

Check it works

In your project, run doctor. It shows the whole road and marks the next step:

$ node .yokoten/bin/yokoten.ts doctoryokoten 0.1.0, self-test okthe road: stage 1 of 5, safety net  1. safety net    done        rules    done        tool-hook    done        commit-check    done        runtime    next        tests: CI does not run the tests; add a step that runs `npm test` …  2. issues and pull requests    …

Shortened. Your steps will differ.

To see the guard stop something without running anything, hand it a pretend tool call:

$ echo '{"tool_name":"Bash","tool_input":{"command":"git push --tags"}}' | node .yokoten/bin/yokoten.ts hookyokoten: git push --tags pushes tags. Only the owner decides when to release. If the owner asked for this, they start the session with YOKOTEN_RELEASE_APPROVAL set.

Nothing is pushed: the hook only reads the call. Exit code 2 means “blocked”.

What it can’t do

Honest limits, from the guide:

• The guards read command text. A command put together in pieces gets past them. They catch mistakes and drift; they aren’t a lock. The lock is on the server: branch protection, code owners, and a bot that can’t release or change CI.
• Server settings aren’t checked yet. doctor lists the three steps for the owner. Checking them through the API is planned.
• Claude Code first. The guard also runs in Codex and Gemini CLI, but nobody has yet seen it block a real session there (#30). Muse Code support is planned.

The full list in the guide ↗

Learn more

• The guide →the twelve rules, every command, how it works, and what it can't do.
• Server setup →protect main and release tags on GitHub.
• Decisions →why it's built this way.