Playbooks · Coding agents

Build a small CLI tool end to end with an agent

A solo builder takes a small command-line tool from an empty folder to a working command, with Codex, one behaviour at a time.

Audience: Solo builder · Stack: A small command-line tool in any language you already know, in a git repo · Tool: Codex CLI (terminal)

Before you start

• A language and runtime you already know. A new language plus a new agent is two unknowns at once; this playbook assumes one.
• Codex CLI installed. The author README gives, for Mac or Linux, curl -fsSL https://chatgpt.com/codex/install.sh | sh, and also lists npm install -g @openai/codex and brew install --cask codex. Run codex and sign in as the README describes — with ChatGPT, or with an API key via the additional setup it links.
• A one-paragraph spec you wrote yourself: the command's name, its inputs, its output, and its error cases. If the spec fits on an index card, the tool is the right size for this playbook.
• An empty git repo with a README that states the spec. The agent builds to the spec; the README is how you check it did.

Steps

1. Start Codex in the project directory with codex, and paste the spec. Ask first for the project skeleton only: the entry point, the argument handling, and a help output — no real behaviour yet.
2. Run the skeleton yourself and check the help output. If the skeleton does not run, fix that before adding behaviour. A tool that cannot start cannot be tested.
3. Add one behaviour at a time, in the order a user would meet them: the main command first, then its most common option, then its error cases. After each behaviour, run the command by hand with a real input and a bad input.
4. For a behaviour that needs no supervision, you can run it non-interactively with codex exec "task", which the author docs describe as the non-interactive execution subcommand. Read its output and its diff before accepting it, the same as for an interactive session.
5. Keep a small set of example commands in the README — one for each behaviour — and run all of them before every commit. These examples are the tool's test suite until you add a real one.
6. When the spec is fully working, add the real test suite for the behaviours, if the project does not already have one, and run it. Then handle the edges: missing input, unreadable file, and a user interrupting the command.
7. Ship the tool the way its users will install it, and install it that way yourself on a clean machine or clean directory. If your install path only works from your project folder, it is not finished.

Worked example

A solo builder wants a tool called wordcount that counts words in a file, with an option to count lines instead, and a clear error for a missing file. The spec is three lines. Codex builds the skeleton with help output first; the builder runs it and checks the help text. Then the main count behaviour, then the lines option, then the missing-file error — each run by hand with a real file, an empty file, and a nonexistent path. The README collects the three example commands. A non-interactive run with codex exec "add the lines option" is used for one small addition and its diff is read before commit. The finished tool is installed from a clean directory and run there, which catches a relative-path mistake the project folder had hidden.

What can go wrong

• The agent builds everything at once and nothing runs. Fix: revert to the skeleton and add one behaviour at a time. The skeleton-first order is the recovery, not just the plan.
• The tool works in your project folder but not elsewhere. Fix: install and run it from a clean directory. Path assumptions are the classic end-to-end failure, and only a clean-directory run finds them.
• A non-interactive run produces a large diff you cannot review. Fix: do not accept it. Break the task into smaller codex exec runs, each producing a diff you can read in full.
• Error cases print a stack trace instead of a message. Fix: treat error output as part of the spec. A tool whose errors a user cannot act on is unfinished.

Limits

• Codex builds what your spec says. A vague spec produces a vague tool, and no amount of agent effort repairs a spec you never wrote.
• A handful of README examples is a smoke check, not a test suite. It catches regressions in the examples listed and nothing else.
• This playbook fits a small tool. A tool with many commands, configuration, or a plugin system needs design work first, and the one-behaviour-at-a-time loop will not supply it.

Time and cost: NOT_MEASURED. This page gives no time or cost figure because the tool docs fetched for it state none that applies to this task.

Verification

Tier: AUTHOR_DOCS_VERIFIED · verified 2026-10-23. The workflow on this page was not run end to end in a sandbox for this page; every command, flag, and capability claim below was checked against an author doc or author repo fetched on 2026-10-23.

• https://github.com/openai/codex
• https://developers.openai.com/codex

Cut from this page, with reason:

• No sandbox or approval flags named: the author repo points to separate security docs for those, and this playbook uses the default prompting behaviour — approve steps you have read — rather than asserting flag syntax.
• No model named: the task needs none, so none is recommended.
• No time or cost figure: NOT_MEASURED.

If a step here does not match what your installed tool shows, trust the tool's own docs for your version and stop before approving a change you cannot read.

Back to: Coding playbooks hub (../../guides/coding/) · Skills index (../../skills/)