Skip to content
agents.cli

Course · Codex · Getting started

Getting started

You’ve inherited a repo. A friend built budgetcli over a few weekends - a small self-hosted budgeting API for tracking accounts, importing bank statements, and flagging overspend - and now it runs with your own money in it. It mostly works. It’s lightly documented. And you already suspect the original author got something subtly wrong.

Here’s the one fact that makes this hour worth taking slowly: Codex has never seen this codebase either. Every time it starts a turn, it knows exactly nothing about budgetcli that it hasn’t just read inside that same turn. That’s not a bug in the tool - it’s the starting condition of every agent you’ll ever point at a repo you didn’t write, and closing that gap, turn by turn, is what this entire course is about. This first hour is where you learn to feel the gap and work around it, on a bug small enough that a wrong move costs you nothing.

The audience here is the engineer who already lives in an editor - VS Code, a JetBrains IDE, an inline completion humming in the gutter - and is eyeing a terminal agent with reasonable suspicion. You don’t have to give any of that up. By the end of the hour Codex is sitting next to your editor, not replacing it, and you’ve used it to fix a real bug in code you didn’t write.

What a week of closing that gap is worth

Section titled “What a week of closing that gap is worth”

The destination is worth stating in numbers before you’ve installed anything, so you know exactly what you’re working toward.

Onboarding a fourth bank’s CSV export into budgetcli - cold, the way you’re about to start working in this very chapter - takes about 11 back-and-forth turns on a Monday, and somewhere in those turns the agent reintroduces the same money bug three separate times: it parses a currency amount as a float, when every amount in budgetcli is stored as an integer number of cents. (A previous author wasn’t consistent about that rule either - which is exactly how the agent keeps finding a plausible-looking excuse to break it again.) By Friday, the same class of job takes 2 turns, and the bug doesn’t come back once. The entire difference is 32 lines in one file, one saved profile, and one skill - nothing exotic, and nothing you can’t build yourself over the course of the week.

That gap - 11 turns and three repeats down to 2 turns and zero - is what every later chapter is buying you. Chapter 1 doesn’t close it. Chapter 1 is where you learn to see one turn clearly enough to notice, later, exactly which piece is still missing.

About the numbers in this course

Section titled “About the numbers in this course”

Every token count in this course comes from one of two estimators, used the same way every time and never varied: 10 tokens per line of Python for code, and 4 characters per token for prose and Markdown - the second one matters later, when you’re pricing an AGENTS.md file instead of a source file. Both are rules of thumb, not measurements - the real number depends on the model’s tokenizer and everything else riding in the same prompt - but they’re close enough to reason with, and always flagged as estimates when they appear. Beyond those two estimators, a number in this course is one of two other things: a fact about budgetcli itself, true because we’re defining the teaching repo that way, or a quoted fact about Codex with a source behind it. What you will not see here is an invented measurement of Codex - a made-up latency, a made-up price, a benchmark this course didn’t run. If a claim about Codex’s actual behavior isn’t backed by Codex’s own docs, it isn’t in this course.

One more assumption, stated once so every later chapter can point back to it: arithmetic here assumes a 200,000-token context window. That’s a round, substitutable number, not a claim about any specific model’s exact limit - swap in whatever your model’s window actually is and the reasoning still holds.

Last thing, said once here so no later chapter has to repeat it: every terminal-style prompt-and-reply block you’ll read in this course, including the ones a page from now, is a reconstruction written to show the shape of a real run - not a captured transcript. Treat them as accurate about what Codex does and how a turn unfolds, not as a screenshot of one specific session.

The code estimator already tells you something before you’ve written a line of code: budgetcli’s whole Python source is a little over six thousand lines - call it 62,000 estimated tokens. Against a 200,000-token window, that’s about 31% of the whole thing. You could hand Codex the entire repo, every file, in a single message, and it would fit with room to spare. You still shouldn’t. Learning why not, one turn at a time, is most of what this chapter and the next one teach.

The hour we’ll follow

Section titled “The hour we’ll follow”

budgetcli imports transactions from bank CSV exports, and you’ve already noticed it mangles some dates - a statement that clearly says one day lands in the database as another. That’s your warm-up ticket: small, real, and verifiable against a CSV you can read with your own eyes. We’ll go from zero to that fix shipped, in five moves:

None of it is hard. The point of doing it as one continuous task - on a repo you’ve genuinely just inherited - is that the habits you pick up here are the same ones every later chapter leans on: read before you edit, approve before it writes, and treat every change as a proposal you review rather than a result you accept. On code you didn’t write and don’t fully trust yet, those habits aren’t optional polish. They’re the whole game, and everything after this chapter is just sharper versions of the same four moves.