Getting started with Codex: your first project, from folder to finished result
Start a useful Codex project with a clear brief, a bounded folder, a working result and a review you can perform even as a beginner.
The first win should be something you can open.
Begin with a task that leaves a useful file behind. A reading list with search, a little practice timer or a report built from sample data gives you a visible result and a manageable review. You can learn the environment without simultaneously designing an entire business.
Give the task a home
Use a new folder for your first local project, such as ai-reading-list. In the desktop app, a local project can attach a folder; in the CLI, the starting directory supplies the project context; in an editor, the open workspace does. Those surfaces have different controls, so use the official project guide for your setup. A web project with uploads is a different arrangement from direct access to local files.
Place only the materials needed for the exercise in that folder. Five public article links and a short description of the intended reader are enough. Ask Codex to report the working location and available files before starting. If the location is wrong, correct it before the project accumulates changes.
Describe the experience you want
Write about the person using the result. For a reading list: someone should be able to find a saved article by title or topic, open the original source, and see a helpful message when no result matches. Specify whether data should persist after a refresh. Those details shape the implementation more than a vague request for a beautiful app.
Let Codex choose routine implementation details after inspecting the environment. You can ask it to explain unfamiliar choices in plain language. If it proposes additional services, accounts or paid dependencies, ask what the smallest local version would require first.
A request you can adapt
Build a small local reading-list website in this folder. Use the five public links in reading-list.txt. Show title, topic and original link; add search and topic filters. Make it comfortable on a phone. Keep the content in a simple editable file. Test search, combined filters, no matches and refresh. Show me the running page and explain how to edit the list. Do not publish it.
Follow the work at the points that matter
You do not need to approve every line of code. Watch for decisions that change the project: a new service, a change in what is stored, or a feature that expands the scope. Correct misunderstandings with examples. “A topic filter should combine with search” is much more actionable than “the filters are weird.”
If the assistant stops at an explanation, ask it to create the files and run the result. If a command is blocked, ask for the specific reason and a concrete next step. A claim that a server started should be followed by a working address; a failed startup should remain a reported failure.
Do a five-minute acceptance pass
Find one known title, choose a topic, clear it, search for a word that is absent, and reload. Open an original link. Narrow the browser. Check that the visible result matches the supplied data. These are small but meaningful checks because they exercise the purpose of the tool.
Ask for a README containing the launch command, content location and current limitations. Save a known working version before the next expansion. Your second task can then be precise: add sorting, import a file, improve keyboard navigation or introduce a new view.
A request you can adapt
Before we add anything, summarize what works, the exact checks you performed, what failed or remains untested, and how I reopen the project tomorrow. Put the durable instructions in README.md.
Take this into your next task
A first Codex project is complete when you can open it, use the central interaction, change the input and understand how to return to it.
Questions people ask
Does a local Codex project need Git?
A folder can be useful without Git. Version control becomes valuable when you want to inspect changes and recover an earlier version. Start with a backed-up or disposable folder if Git is new to you.
Sources and editorial notes
Reviewed September 6, 2026. Product capabilities depend on the app, plan, region and workspace settings. Workflows and prompts are authored teaching material, not recorded model results or measured time-saving claims.
Keep going
- Build Your First Tool with Codex: A CSV Checker
- AGENTS.md: Give Codex Useful Project Instructions
- AI Showcase: Working Tools and Project Blueprints
Related Power of AI pages
Keep reading with Start here, everyday uses, the tool guide, the writing workshop, and sources and standards.