AI StepNotch

Work advances one notch at a time — each approved unit locks in, and nothing slips back.

A human-in-the-loop driver around the interactive Claude Code CLI. It is a globally-installed CLI plus an Electron desktop viewer with an embedded claude terminal. It runs a software project through review of each unit of work: plan → unit → report + diff → your decision (Approve / Improve / Decline) → next unit.

No API calls, ever. StepNotch never uses the Agent SDK, the Messages API, ANTHROPIC_API_KEY, or headless claude -p (which bills as API). All agentic work happens in the embedded interactive claude terminal, under your existing Claude subscription. The tool only keeps state in Markdown and orchestrates the tempo.

Why bother? An agent left to run unattended will happily produce a thousand lines you have to read all at once, half of it wrong. StepNotch makes it stop after every unit of work, show you the diff and its own honest report of what it did not finish, and wait. You approve, ask for another pass, or throw the attempt away — and the record of every one of those decisions stays in your repo as plain Markdown.

Requires Node 18+, git, and the Claude Code CLI with an active Claude subscription. The embedded terminal can run a different agent instead — see Choosing which agent runs in the terminal.

Architecture: tool is global, data is local

• stepnotch is installed once, globally, by install.sh. All tool code (including the viewer) lives in this repo.
• .stepnotch/ in your repo holds only Markdown (+ a small config.json). Never node_modules, build output, or tool code — it stays clean and committable.
• stepnotch ui launches the viewer from this repo, pointed at the current repo's .stepnotch/ via the STEPNOTCH_ROOT env var.

The data format is the contract in spec/stepnotch-spec.md.

Install

One script. Nothing is published to or fetched from a package registry.

git clone https://github.com/mmuminovic/AI-StepNotch.git
cd AI-StepNotch
./install.sh

Or, if you would rather not clone by hand — this fetches the repo for you and installs from it:

curl -fsSL https://raw.githubusercontent.com/mmuminovic/AI-StepNotch/main/install.sh | bash

The one-liner clones into ~/.local/share/ai-stepnotch (override with --dir DIR, or STEPNOTCH_DIR=…). Piping a script into a shell is worth reading before you run it — here it is; the clone-first form above does exactly the same thing with the script in front of you.

It installs dependencies, rebuilds node-pty against Electron's ABI, builds the CLI + viewer, and drops a stepnotch launcher into the first writable directory it finds on your PATH (~/.local/bin, /usr/local/bin, ~/bin). If none is on PATH it tells you the one line to add.

The launcher is a small shim that execs the checkout's build, not a copy. So an upgrade is just:

cd /path/to/AI-StepNotch && git pull && ./install.sh --build-only

flag	what it does
--build-only	rebuild in place; skip the global command (it already points here)
--prefix DIR	install the launcher into DIR instead of the default
--dir DIR	where to clone to, when bootstrapping from the one-liner
--uninstall	remove the global command; your projects and repo are untouched

Do not move the folder after installing — the launcher records its absolute path. If you do move it, just run ./install.sh again from the new location.

Two things the installer checks for you, because both fail silently otherwise: an incomplete Electron download (a viewer window that never appears) and a node-pty built for the wrong ABI (a blank embedded terminal). If the terminal is ever blank later, run npm run rebuild.

Getting started

Three starting points. Pick the one you are actually in.

A. A brand new project — empty folder

mkdir my-app && cd my-app
git init && git commit --allow-empty -m "base"   # the diffs need a base commit
stepnotch init                                   # asks for a name + description
stepnotch ui

stepnotch init asks for a name and a short description. Give it a real description — an empty folder has no code for Claude to read, so that sentence is the only context the planner gets. (-n / -d to pass them non-interactively.)

Then, in the viewer, Plans tab:

1. Type what you want built into the Grow the plan box, e.g. "A recipe site: browse recipes, search by ingredient, save favourites, admin can add recipes."
2. Click Draft a plan for review ▶. Claude proposes features → tasks into .stepnotch/drafts/ and stops. Nothing is real yet.
3. Review the draft: rewrite titles, tighten the acceptance criteria, untick anything you did not ask for. Then Apply — the surviving tasks become work, grouped under a plan named after the draft.
4. Go to Work and hit Run next ▶.

Why draft instead of "Plan the whole project"? Both work. Plan the whole project writes straight into the plan and is quicker; Draft a plan lets you cut the scope before it exists. On a greenfield project, where the planner is guessing most of it, the draft is usually worth the extra minute.

B. An existing project, no stepnotch yet

cd /path/to/existing-repo
stepnotch init      # non-destructive: only adds .stepnotch/ and .claude/commands/
stepnotch ui

No git init needed — the repo already has history, which is exactly what the diffs need. init only adds files; an existing .claude/ directory keeps everything already in it.

Here Claude can read the codebase, so you have better options than planning from scratch:

• Draft a plan with a scoped instruction — "Add rate limiting to the public API" — and Claude reads the code before proposing tasks.
• Adopt a document… if you already wrote a docs/roadmap.md. Claude turns it into features → tasks, preserving your intent and ordering.
• + New task for work you can already describe precisely. Fastest path: no round trip through the terminal at all.

Two things worth doing on day one:

# commit the tool's state with the repo — it is the audit trail
git add .stepnotch .claude && git commit -m "chore: adopt stepnotch"

And in Settings → Git & checks, add your real check commands (npm test, npx tsc --noEmit). They run at capture, and a task whose checks fail is never auto-approved.

C. A project that already uses stepnotch

cd /path/to/repo
stepnotch migrate   # ONLY if the project was made with the old `claudework` build
stepnotch bridge    # if you upgraded StepNotch since this repo was set up
stepnotch ui

Coming from claudework? The tool was renamed, and with it the data directory (.claudework/ → .stepnotch/) and the slash commands (/cw-* → /sn-*). Without stepnotch migrate such a project goes invisible: the tool looks for .stepnotch/, finds nothing, and offers to start over on top of real work.

migrate renames the directory only — every plan, task, report, diff and decision moves untouched — then reinstalls the bridge and deletes the stale /cw-* commands. It is idempotent, refuses to guess if both directories exist, and --dry-run shows the plan first. Git sees it as a rename, so commit it and the history follows.

stepnotch init deliberately refuses to run twice — it would clobber your project. stepnotch bridge is the ordinary upgrade path: it reinstalls the format guide (.stepnotch/CLAUDE.md) and the /sn-* slash commands, and touches nothing else. Run it after upgrading, or Claude keeps working from an outdated schema and any newly added slash command simply will not exist.

Then either pick up where you left off (Run next ▶), or start a new round of planning:

1. Plans tab → describe the next chunk of work → Draft a plan for review ▶.
2. Applying it creates a second plan next to the first. Nothing existing is touched, renamed or renumbered.
3. Optionally Focus the queue on one plan so "Run next" stays inside it until that batch is finished.

This is the intended shape for a long-lived project: plan → build → plan again, with every round kept as its own whole.

The loop, once you are set up

Whatever the starting point, the daily rhythm is the same:

1. Run next ▶ — injects a focused, single-unit prompt into the embedded terminal. (Or hit ▶ on any card to run that task ahead of the queue.)
2. Claude does the unit and writes report.md, then runs /sn-done — or you click Capture & review. The tool writes changes.md (the diff) and a pending review.md, and moves the task to in_review.
3. Approve / Improve / Decline — keys A / I / D, rebindable.
   • Approve → task done (and committed, if you turned auto-commit on).
   • Improve → a new iteration on top, carrying your comment and any inline diff notes.
   • Decline → git reset to the unit base and start the task over.
4. Repeat. Turn on AutoNext (⋯ menu) and step 1 happens by itself.

Press ⌘K for the command palette.

Plans: each round of planning stays a whole

A project is rarely planned once. Plan the MVP, build it, then plan billing — and the second plan lands beside the first, never on top of it.

.stepnotch/plans/01-mvp.md       ← Auth, Sessions, Dashboard
.stepnotch/plans/02-billing.md   ← Payments, Invoicing

Each plan has its own progress (8/11 tasks), its own status, and its own features. The Plans tab shows them side by side; the sidebar and the board can group by plan.

Focus the queue on one plan and "Run next" stays inside it — that is how you finish the MVP without the queue wandering into billing work. When the plan runs dry it tells you so, instead of pretending the project is done.

Applying a draft creates a plan named after it, so a planning session survives as a named batch rather than dissolving into a flat list of features. Features can also live outside every plan — grouping is optional, and old projects keep working untouched.

Deleting a plan never deletes work: its features simply become ungrouped.

Controlling the queue

• Order — by default the queue runs in exact document order, feature by feature, top to bottom. Turn Strict order off in Settings and priority (low / normal / high / urgent) leads instead, with document order breaking ties — so an urgent task three features down runs before the one you are looking at.
• Dependencies — a task lists the tasks that must finish first; the queue skips it until they are done, and tells you why if you try to run it anyway.
• Backlog — planned work parked outside the queue. Drag it onto the board when you want it, or just hit ▶ on it and it is promoted automatically.
• Archive — keeps the record, removes it from the board and every counter. Anything with a work history is archived rather than deleted; the audit trail cannot be destroyed from the UI.

CLI

command	what it does
stepnotch init	data skeleton + bridge install (idempotent: refuses if .stepnotch/ exists)
stepnotch ui	open the Electron viewer + embedded terminal for this repo (--claude, --codex, --command, --yolo — see below)
stepnotch migrate	move a project made with the old claudework build onto the new layout (--dry-run)
stepnotch bridge	reinstall the format guide + /sn-* commands after upgrading StepNotch
stepnotch next [--print]	prepare the next unit; print its focused prompt
stepnotch capture	capture git diff of the in-progress unit → changes.md, open review
stepnotch status	print progress from the frontmatter
stepnotch task add "<title>"	create a task (-f feature, -a criterion, -p priority, -t tag, -e estimate, -b backlog)
stepnotch task list	list tasks (--status, --feature, --tag, --all)
stepnotch task move/status/rm	reorder or rehome, park/unpark, delete
stepnotch plan list/add	rounds of planning with their progress
stepnotch plan focus <plan>	restrict the run queue to one plan (no argument clears it)
stepnotch plan assign <feature> <plan>	group a feature under a plan (--none to ungroup)
stepnotch draft "<what>"	print the prompt that asks Claude for a reviewable plan
stepnotch draft list/apply/rm	inspect, apply, or discard staged plans
stepnotch template list/apply	reusable feature shapes

Choosing which agent runs in the terminal

The embedded terminal is not wired to any one CLI. It opens your interactive login shell ($SHELL -il) and types a command into it, so aliases, shell functions and PATH additions from your rc file all resolve — and the command may carry its own arguments.

The project's standing choice is claudeBin in .stepnotch/config.json (Settings → Claude binary / command). To override it for one launch only, without touching the config:

stepnotch ui --claude                 # claude
stepnotch ui --codex                  # codex
stepnotch ui --command "claude-personal --dangerously-skip-permissions"

Add --yolo to skip every confirmation prompt. Each agent spells that differently, so the flag maps per agent:

stepnotch ui --claude --yolo    # → claude --dangerously-skip-permissions
stepnotch ui --codex  --yolo    # → codex --yolo

--yolo needs --claude or --codex so the right flag is known; with --command you write the whole command line yourself. When an override is active the terminal banner says so, and names what Settings still hold.

Codex's --yolo is not the same trade as Claude's. It aliases --dangerously-bypass-approvals-and-sandbox, which drops the sandbox as well as the prompts — Codex's own docs call it "EXTREMELY DANGEROUS … solely for environments that are externally sandboxed."

Running an agent other than Claude Code. The engine is a plain CLI, so any agent that can run shell commands can drive the loop. Two things are Claude-specific: the /sn-* slash commands are installed as .claude/commands/*.md in Claude Code's format, and the default unit prompt ends by telling the agent to run /sn-done. For Codex — which has no user-defined slash commands — edit the unit prompt template (Settings → Prompt templates) to call `stepnotch capture` directly instead. The rest of the loop is unchanged.

Customisation

• Prompt templates — Settings → Prompt templates. The text injected into the terminal is a template; an override lands in .stepnotch/prompts/<key>.md and is committed with the repo, so a team shares one brief.
• Appearance and layout — four themes, custom accent, density, font size, draggable pane widths, rebindable shortcuts. These are per-machine and stay out of the repo.
• Board — group by status, feature or priority; filter by feature, priority, tag or text.
• Checks — project-wide in config.json, or per-task when one unit needs a heavier suite than the rest.
• Git on approve — off by default. Turn on Auto-commit and the approved task's work (code and its .stepnotch record) is committed for you; add Auto-push and the branch goes up too. The message is a template: {{feature}}, {{unit}}, {{iteration}}, {{summary}}, {{plan}}. A failed push is reported in the banner and never turns a successful approval into a failure.

What writes what

Claude does all the implementation and owns every report.md. The tool owns changes.md, review.md, checks.md, and every machine field on a unit (status, order, git_base, unit_base, current_iteration).

feature.md and unit.md content fields can be written by either — Claude through a planning prompt, or you through the viewer and stepnotch task. The full contract is in spec/stepnotch-spec.md §1 and §12.

Dev

npm run build:main       # tsc → dist/cli, dist/core, dist/electron
npm run build:renderer   # vite → dist/renderer
npm run typecheck
npm run dev:renderer     # vite dev server for the renderer

License

MIT — see LICENSE.

Contributing

Issues and pull requests are welcome at github.com/mmuminovic/AI-StepNotch.

Before opening a PR:

npm run typecheck   # both tsconfigs
npm test            # 54 tests, runs against the compiled dist/
npm run build       # main + renderer

The data format is a contract — if a change touches what lives under .stepnotch/, update spec/stepnotch-spec.md in the same PR.