The notchfit Command Line: Drive Your Workout, Read Status as JSON, Validate Plans and Test the Notch Without Leaving the Terminal

Most people drive NotchFit from the notch: tap Start set, do the reps, tap Done. But NotchFit is built for people who live in a terminal, and it ships a small command-line tool for exactly that reason. The notchfit command lets you start and finish sets, read the app's state as JSON, validate a workout plan, trigger the notch without a real Claude Code task, and diagnose a broken install, all without leaving the shell your agent is running in. This post is a tour of every command, what each is for, and a few workflows that only make sense once you have it.

Where the command comes from

You do not install the CLI separately. When you click Install / update integrations in NotchFit's Setup tab, the step that adds the Claude Code plugin and the Codex skills and hooks also links a notchfit command for your shell. Run notchfit doctor to confirm it is there. Uninstalling the integrations from the same Setup tab removes the link again, along with the plugin and hooks. The guide's own description is honest about its status: the CLI is optional, "handy for scripts or a quick keyboard workflow", and you never need it for normal use.

Everything the command does goes to the NotchFit app running on your Mac over localhost. It is the same local server the Claude Code hooks talk to, so there is no account, no network and nothing leaves the machine; see the local-first post for what that server receives.

The commands

Driving the workout

• notchfit start: start today's workout, the same as tapping Start workout in the notch.
• notchfit stop: stop today's workout.
• notchfit done: finish the current set, equivalent to the Done button; you get the confetti and the rest timer as usual.
• notchfit skip: skip the current set.
• notchfit now: start the next set immediately, instead of waiting for the rest timer and the Start set tap.
• notchfit pause and notchfit resume: pause or resume the workout.

These are the commands you reach for when the notch is minimised behind a fullscreen terminal and you would rather type five letters than move the mouse. They respect the same rules as the notch: a set never starts on its own, and alerts from Claude or Codex that arrive mid-set still wait until the set ends (the reasoning is in why mid-set notifications wait).

Reading state

• notchfit status: a JSON document describing the current set and the AI sessions NotchFit knows about. This is the command that makes everything else scriptable.
• notchfit catalog: the exercise catalog, with the ids the notch can animate. There are 239 of them: 198 photo animations of real athletes plus around 40 illustrated moves.

Plans

• notchfit validate [file]: check a plan file. With no argument it checks ~/.notchfit/plan.json, which is where /notchfit:plan in Claude Code and $notchfit-plan in Codex write the weekly plan.
• notchfit reload: reload plan.json into the app. NotchFit picks up a plan written by your AI on its own; reload is for when you edited the file by hand.

Testing and troubleshooting

• notchfit simulate done|working|permission: fire a fake AI event so the notch opens without a real task. working shows the panel as if an agent had just started, done sends a done alert, permission sends a permission request. The Setup tab's "Try it" buttons do the same thing with a click.
• notchfit doctor: checks the app, the Claude Code and Codex integrations and the local server, and is the first thing to run when the notch did not open for a task.

Five workflows the CLI makes possible

1. Hand-edit a plan and know it is valid before the app sees it

The AI-written plan is good, but you might want to swap one exercise for another or move leg day. Open ~/.notchfit/plan.json, make the change, then run notchfit validate. It checks that the file is a plan NotchFit can run. Use ids from notchfit catalog for any exercise you add, since the notch can only animate moves in that catalog; pipe it through grep to find the id of the move you want. Then notchfit reload. The weekly plan post covers what the plan looks like in the first place.

2. Test the notch before you trust it with a real run

After installing, or after a macOS update, run notchfit simulate working, then notchfit simulate done. If the notch opens and the alert arrives, the app side is fine, and any remaining problem is the hook side, which notchfit doctor checks. This takes ten seconds and saves the annoying discovery that the notch is silent only when a two-hour task finishes.

3. Put your set state in a tmux status line or a prompt

notchfit status prints JSON, so any status bar that can run a command can show your current exercise and whether an agent is working. If your Claude Code sessions run in tmux over SSH, where the notch is not visible from the other machine, this is the way to keep an eye on both.

4. Finish sets without touching the trackpad

Bind notchfit done and notchfit skip to a shell alias or a keyboard shortcut in your terminal, and the whole workout runs from the keyboard. For people who find the mouse the slowest thing on their desk, this is the difference between using the app and ignoring it.

5. Start the workout from your agent's own hooks

Because the command is just a command, a Claude Code hook or a Codex hook of your own can call it. A SessionStart hook that runs notchfit start means the workout begins when the coding session does, with no tap. Keep such hooks asynchronous, as NotchFit's own are, so they never make Claude wait.

What the CLI does not do

It does not replace the integrations: the done and permission alerts still come from the Claude Code plugin and the Codex hooks, not from anything you type. It does not work without the app running, because it talks to the app's local server. It does not edit your plan for you (that is /notchfit:plan's job, or the offline Quick plan in the Plan tab) or change settings such as voice, chimes or whether the notch stays open while your AI works, which live in the app's Settings tab. And it is not a fitness tracker: NotchFit counts sets and streaks, not heart rate.

Should you bother?

If you tap the notch happily, no. The CLI exists for the minority of users whose hands do not leave the keyboard and whose screens are mostly terminal, and for anyone who likes to test and script the tools they own. For them, the five minutes it takes to learn start, done, status, simulate and doctor pays back on the first day the notch goes quiet and you want to know why. NotchFit is $20 once, macOS 14 or later, Apple Silicon and Intel, and the CLI comes with it.