Skip to content

Latest commit

 

History

585 Commits

Folders and files

Repository files navigation

yokoten · 横展

npm ci license Node

Your agent ran rm -rf. The project next door is still there.

One command turns on your agent's sandbox, and it fails closed: npx yokoten.

yokoten.app · English · 简体中文 · 繁體中文 · 日本語

Is it for you?

Yes, if a coding agent runs commands on your machine and you want it stopped before it deletes another project, force-pushes, commits a key or ships a release. Set it up once; after that there is nothing to run day to day.

You may not need it if your agent already runs in its own sandbox, and you never let it push or release.

Start

You need Node 22.23.4 or later. Then run:

cd your-project
npx yokoten

That's it: one command, nothing to set. Run it again any time; it does only what is still missing.

To take it off: npx yokoten uninstall. It takes back what it wrote on this computer and leaves your own files and settings as they were. The files it added to a project are plain files you can delete.

On Linux the sandbox needs bubblewrap and socat; without them Claude Code stops.

The first run shows one screen: what it set up, where you are, and the next command.

yokoten 0.2.1 · set up; stage 1 of 5, safety net

  ok           guard on for Claude Code on this computer
  ok           38 files written in this project, none of yours changed
  ok           sandbox on for Claude Code, Codex, Grok CLI in this project

  MISSING      ~/.config/yokoten/private-marks is missing or has no marks
               Type your name, your city or a domain; it is not shown.
               Fix: `npx yokoten marks add`

  done         12 of 26 steps
  next         Run your tests on every push
  to do        Put the project on GitHub or Gitea
  to do        Name the owner (CODEOWNERS)
  to do        Set up the bot account
  to do        Add a license and a security policy
  can't check  9 steps: they read the code host; doctor checks them after a push

  note         16 uncommitted files, the oldest changed 1 minute ago

Next: `git add -A && git commit -m "chore: add yokoten"`
More: `npx yokoten doctor --all` shows every check and 5 notes

Why I built this

My agent, Claude Opus 5.5, one of the best coding models there is, ran one delete command and wiped my whole work folder. I had a guard on, and it did not stop it. A guard reads commands, and commands have too many forms. So yokoten now turns on the agent's sandbox. A sandbox does not read. It refuses. My lesson: whatever agent you use, turn on its own sandbox. yokoten turns it on for you, where your agent has one.

A test replays five delete commands from inside one project against yokoten's fence, and the project next to it stays.

A sandbox does not protect the folder the agent starts in. Start the agent in one project, not in your home folder; yokoten says so when you don't.

What it stops

It protects It stops
Your work a force push, a hard reset, deleting .git
Your secrets a commit that adds a key, a private email or an IP address
Your releases a new tag, a package publish, making a repo public
The code you run a download that runs before anyone reads it
The guard itself skipping the commit check, or switching it off

When it stops something, it says why and what to do instead:

yokoten stopped this: git push origin v1.2.0 pushes a release tag [release]

  Why       Only the owner decides when to release.

  Instead   Stop and tell the owner: only the owner releases, with the steps in
            How to release; do not look for another way.

  More      https://github.com/yokoten-labs/yokoten/blob/main/docs/guide.md#how-to-release

How it works

  • A program, not an AI. The same command always gets the same answer, in under a fifth of a second, at no cost.
  • Three places. Your AI tool asks yokoten before each command or edit; yokoten also checks each commit and runs in CI.
  • Leaves your settings alone. It keeps your choices, and saves a copy before it changes a file of yours.
  • Many AI sessions in one repo. yokoten conflicts says which open change to merge first, and the guard stops an edit to a file another open change is moving.

The commands

You need one command to start. Four more help along the way.

Command What it does
npx yokoten sets up what is missing, then shows the next step
yokoten check looks for secrets and broken rules before a commit
yokoten desk gives one task to one AI, in its own desk
yokoten kanban shows the team at a glance (preview)
yokoten tidy lists old branches, worktrees and desks

yokoten help --all lists the rest, in groups by job: Start, Work, Guard, Merge and CI, Maintain.

Works with

Any AI model works. The guard checks the commands the agent runs, not the model.

  • Agents: the guard runs with each agent below. The agent table in the guide holds the evidence: the date, how each run went, and what to know first.
  • Trust first: yes means you run npx yokoten trust once in the folder, so the agent runs the guard.
Agent Verified end to end Trust first Models tested
Claude Code ✅ yes no deepseek-flash
GitHub Copilot CLI ✅ yes yes gpt-6-luna (Auto)
Antigravity CLI ✅ yes no gemini-3.8-flash-high
Codex CLI ✅ yes yes deepseek-flash
Muse Code ✅ yes yes muse-spark-1.3-contributor
DeepSeek Harness ✅ yes no the default DeepSeek model
Grok CLI ✅ yes yes the default model
Gemini CLI not yet no —
OpenCode ✅ yes no opencode-go/deepseek-v4.1-flash, opencode-go/glm-5.3-flash
  • Programming languages: any. doctor finds the test command for JavaScript, TypeScript, Python, Go, Rust, Java, .NET, Ruby, PHP, Swift, Elixir, Dart and make test.
  • Platforms: Linux, macOS and WSL. Native Windows is in beta, in Git Bash and PowerShell 7.

More ways to install

npx yokoten runs all three for you. Each one still runs alone:

npx yokoten install     # once per computer
npx yokoten init        # once per project
npx yokoten doctor      # where you are, and the one next step
  • Claude Code plugin: /plugin marketplace add https://github.com/yokoten-labs/yokoten.git, then /plugin install yokoten@yokoten. Use the plugin or npx, not both.
  • Versions: Stable (the default), Beta or Dev; see which version to install.
  • CI only: use it as a GitHub Action.
  • Node: 22.23.4+, 24.22.1+ or 26.12.1+.
  • UTC: the commit check asks for UTC commit times. npx yokoten doctor names the line for your shell.

Roadmap

  • Done, v0.1.2: five commands up front, yokoten, check, desk, kanban and tidy; another model than the writer reviews each change.
  • Now, v0.2.0: doctor --files reads only the files in a project, so a web page can show its road; a review ends in three rounds.
  • Later: a lesson one project learns becomes a check for every project.

Yokoten (横展) is a word from Toyota's factories: a fix that one line finds goes to every line.

Learn more

The guide · The standard · Decisions · Changelog · Milestones · Contributing · Security

MIT license. Built by coolwhite and a team of AI agents.