How Claude Supervised Codex

This is a genuine account of the process used throughout this build, written so you can run something similar yourself, either with Codex or any other AI coding tool. In the source repository, this same content lives in docs/how-i-supervised-codex.md.

The core loop, repeated for every milestone

1. Write one task, in detail, in plain text. Not “build the dashboard”, but an exact list of files to create, exactly what each function should do, what to name things, and what the definition of done is. The definition of done was usually a specific command that must run with zero errors.
2. Explicitly tell it what not to do. The single most useful constraint used throughout this project was: do not attempt anything needing internet access, since the sandbox it runs in has none, and do not try to fake success. Removing that ambiguity meant it correctly stopped and reported what it could not do instead of pretending it had happened.
3. Run it, unattended, and check on it periodically rather than staring at a live stream, since these tasks can take many minutes.
4. When it finishes, read its own summary of what it did, but treat that summary as a claim to verify, not as a fact.

How verification actually happened, concretely

This is the part that mattered most, and the part that is easiest to skip if you are in a hurry.

• Actually run the type checker, npx tsc --noEmit, rather than trusting that it reported doing so correctly.
• Actually open and read the real files it wrote, not just the diff summary it printed, since a summary can describe code slightly differently than what was actually written.
• Actually run the thing, end to end, with real inputs, wherever that was possible. A build succeeding is not the same as a feature working. Many bugs in this project were only found by looking at real output data, not by any static check.
• Actually query the database directly to confirm a write really happened, rather than trusting an API response that claimed success.
• When something failed, read the actual error, form a real hypothesis about the cause, and test that hypothesis, rather than re-running the same thing and hoping.

How work was broken into tasks

Work was broken down roughly in this order, each task building on a verified previous step:

1. Project scaffold: framework, folder structure, and empty stub files. This was deliberately small and low-risk, since everything else depended on this being right.
2. Database setup and schema. This was defined before feature code, since changing the data shape later is more disruptive than changing UI code later.
3. The core automation logic, the news agent pipeline. This was built and proven to actually work end to end before touching the dashboard, since a dashboard with nothing real to show is not very useful to test with.
4. The dashboard: read-only views first, then editable settings, once there was real data to display.
5. Deployment, attempted only once the local version was proven to work, so deployment-specific failures could be isolated as deployment problems rather than logic problems.
6. Extra features: editable prompts, a second AI provider, scheduling, and real publishing. These were added one at a time, each with its own verify-then-commit cycle, once the core system was solid.

Why commits happened the way they did

Each commit represents one verified, working unit, with a commit message describing not just what changed but what was actually checked.

This matters for a practical reason: if something breaks later, you want to be able to look at git history and trust that any given commit was real and working at the time, not guess whether it might have been an untested work-in-progress.

What to do differently if you run this process yourself

• Do not accept “it compiles” as done. It is a necessary check, not a sufficient one.
• Whenever a background service is involved, such as a database, scheduler, or external API, assume the agent's sandbox cannot fully test it, and plan to run that specific piece yourself afterward.
• When a fix does not fully work, do not just retry the same approach. Look at what actually happened, the real error, real log, or real response body, before deciding on the next attempt.
• Expect environment differences to bite you, this machine versus Vercel's build machine or an interactive terminal versus a scheduled job, more often than you expect logic bugs. Several real bugs in this project were entirely about environment differences, not incorrect code.