your coding agent should be able to rebuild your app

This is a real request you can type into Claude Code on a Mac with NotchNull installed:

Use the notchnull skill: add a widget with my open pull requests, and show a red wing beside the notch while CI is failing.

The agent writes one JSON file, renders the notch to a PNG to check its work, and the change is live without restarting anything. No plugin API, no settings screen built for that exact case.

Most apps can't do this, and it's not because the agents aren't good enough. It's because the app was built for a person holding a mouse. Its state lives behind a UI, its errors show up as a toast, and the only way to see if a change worked is to look at the screen.

I built NotchNull and ukiyo the other way around. One is a MacBook notch, the other is a game engine in C#. Very different apps, and they ended up following the same five rules.

1. State is files the agent can read

Every NotchNull setting lives in ~/.notchnull/settings.json, and every widget is its own file in widgets/. The Settings window and the file stay in sync both ways, and the app watches the folder and applies changes while it runs.

In ukiyo, scenes, entities and components are plain C#. There's no editor state hidden somewhere else. What the agent writes is exactly what runs.

If the truth lives in a database behind the UI, the agent has to guess. If it lives in a file, the agent reads it.

2. The app says what it made of your files

An agent that edits a file and gets no answer will tell you it's done anyway. So NotchNull writes status.json: each widget's state, its data and its error, and any setting it couldn't parse. The agent reads that instead of guessing.

ukiyo does the same with typed errors and structured snapshots at any tick. A failure is something the agent can read, not a red message on a screen it can't see.

3. The agent can see the result

This is the piece that makes the rest work. notchnull render out.png --tab widgets draws the notch with the real files to an image, so the agent sees what you'll see and fixes it before saying it's done.

In ukiyo, ukiyo_capture returns real frames from the renderer, and a running game answers on localhost: pause, step, snapshot, inject input, patch the scene. The agent works on the game while it runs, not on a description of it.

Without this, every visual change is a guess and you're the one who checks it.

4. Agents break things, so undo is built in

NotchNull copies your files to backups/ the first time a new version runs and before any preset is applied. notchnull restore puts the last copy back. ukiyo can save at any tick and rewind a live game.

I don't trust an agent more than I trust myself, and I break things too. Undo is what makes it safe to say yes to the agent quickly.

5. When files aren't enough, the source is open

Files cover most requests. "A radial gauge" or "a new section in Settings" don't fit in a JSON file, so they need the Swift source. NotchNull is open source and its skill maps out where everything lives, so the agent changes the app itself and rebuilds it.

A closed app stops right there. You get the settings someone else decided you'd need.

What this costs

More than a normal app. The file format is a public contract now, so I can't rename a key without breaking someone's widgets. Rendering to a PNG means the app has to draw without a window. Every setting needs a reference the agent can read; NotchNull generates settings.reference.md from the app itself so it can't drift.

And ukiyo is pre-alpha. The rules hold up in a notch and in a small platformer. I don't know yet if they hold up in a large game.

Try it on yours

Pick one app you build and ask your agent to change something a user would want. Watch where it gets stuck. It's usually one of these five: it can't find the state, it can't tell if it worked, it can't see the result, it's afraid to break something, or the code isn't there.

Both apps are on GitHub: NotchNull and ukiyo. If you've built something agents can change, I'd like to see how you did it.