Decide before Claude Code builds, check after it's done — two npx tools

Masanori Chida — Wed, 04 Nov 2026 04:39:20 +0000

When Claude Code builds an app for me, it decides things I never asked about:

Does the data survive closing the app, or is it gone?
What shows when there's nothing in the list?
Does deleting ask first?
How many items does it need to handle?

Claude's guesses are usually reasonable. The trouble is that I find out which ones I disagree with only after it's built, when changing them is expensive.

So I made two npx tools that split the work into decide before building, check after. This post shows the basic three steps, and what I learned along the way.

kokoro-baton  →  your AI builds it  →  kokoro-aegis
   decide           (Claude Code etc.)       check

Both run with npx — nothing to install. Free, no sign-up.

Here's the flow in a 1-minute video (the screens are the Japanese web version of the same tools; English subtitles are on):

What you need

Node.js 22 or later
An AI coding tool (Claude Code, etc.)
An Anthropic API key — only Baton uses it. Set it as the environment variable ANTHROPIC_API_KEY.

Baton's AI cost goes to your own key: under 1¢ per round of questions. Aegis uses no AI.

Don't paste your API key into an AI chat. It stays in the conversation history.

1. Decide — kokoro-baton

In an empty folder, describe what you want in one sentence:

npx kokoro-baton "a flashcard app: English on the front, meaning on the back"

Baton asks about what's still undecided, as multiple choice, with what happens if you pick each option. You never get a blank "what do you want?" box, so answering is quick.

When you're done, you get kokoro-spec.md, a spec for your AI. It holds what you decided, what is still open (so the AI doesn't quietly decide it), and how to check each decision.

Answer these questions yourself. If you ask your AI to run Baton, the AI answers them for you — which is exactly what Baton is there to prevent. Run this one in your own terminal.

2. Build — hand the spec to your AI

Open Claude Code in the same folder and say:

Read kokoro-spec.md and build it.

The spec ends with an "After building" section. When Claude Code finishes, it runs the no-AI check (Aegis, next) by itself. For anything that uses AI and costs money, it tells you the cost and asks first, so you can say no.

3. Check — kokoro-aegis

If your AI didn't run it, run it yourself:

npx kokoro-aegis . --out aegis-report.md

Aegis uses no AI and sends your code nowhere. The report has two parts: holes it found by reading the code, and a hand-check table with one line for each decision in your spec. For a small sample game, lines like these came out (translated from the Japanese run):

- [ ] 2 to 3 weapon choices are shown → does it work that way?
- [ ] Enemies appear from every side of the screen → does it work that way?
- [ ] Holding P down does not make the pause flicker → does it work that way?

Use the app, go down the table line by line, and tell your AI about anything that's off.

Zero findings does not mean "no problems". The report always lists what it did not check.

What I learned

I'm a former game planner, not a programmer, and these tools came out of building with Claude Code.

What the AI decides on its own usually isn't wrong. It's just mine to decide, and I wasn't asked.
The first version of Baton only asked about data — where it's saved, sort order, empty input, delete confirmation. I built an MP3 player from its spec, was happy with 4 songs, and the screen broke at 68 artists. It had never asked how you play a song, or how many songs there are. Now it always asks how the main action starts and how many items the app must handle.
A checker built on the same model as the builder shares its blind spots. That's why Aegis uses no AI at all.
"0 findings" looks like an answer. If a report doesn't say what it skipped, silence gets read as "all clear".

What leaves your machine

Aegis sends nothing.
Baton sends your sentence and answers, with your key, to my server (usekokoro.com), which holds the prompts and calls Anthropic with your key. It doesn't store your text or key. For rate limits it keeps a short hash of the key, deleted after 2 days.
The source isn't public; the tools are distributed on npm.

There are six more tools for after the build — spec documents, an Excel table of the tunable numbers in your code, a slider tuner, and a review by Claude Fable. All eight are listed here, with what each one reads and writes:

https://github.com/xmichinokux/kokoro-os-tools

I wrote this article in Japanese and translated it into English with help from Claude. I checked the facts, commands and numbers against the tools myself.

DEV Community: Masanori Chida