Codebase Onboarding

Starting on a new project? Codex can help you understand an unfamiliar codebase in minutes instead of days. Use it to explore structure, trace data flows, understand conventions, and find the code that matters.

When to Use This Workflow#

• Joining a new team or project
• Contributing to an open source repository
• Taking over a client project as a freelancer
• Reviewing a codebase before an acquisition or audit

Step 1: Get the Big Picture#

Start with a high-level overview:

cd ~/new-project
codex "Give me a high-level overview of this project. What does it do,
what frameworks does it use, and how is it organized?"

Codex reads your project files, package manifests, and configuration to build a mental model of the codebase.

Step 2: Understand the Architecture#

Drill into the structure:

codex "Map the architecture of this project. Show me:
- The main entry points
- How data flows from frontend to backend
- Which database/ORM is used
- Key third-party dependencies
- How authentication works"

## Step 3: Trace a Feature

Pick a specific feature and trace it end-to-end:

codex "Trace the user registration flow from start to finish.
Show me every file involved, the API endpoints, database operations,
and any email/notification triggers."

This gives you a concrete path through the codebase that you can follow in your editor.

Step 4: Find Key Files#

Ask Codex to identify the most important files:

codex "What are the 10 most important files in this project?
For each one, explain what it does and why it matters."

Step 5: Check for Gotchas#

Before you start making changes:

codex "What are the potential gotchas in this codebase?
Look for: unusual patterns, technical debt, security concerns,
missing tests, and things that might trip up a new developer."

Step 6: Set Up Your AGENTS.md#

Based on what you have learned, create an AGENTS.md for future sessions:

codex "Based on your understanding of this codebase, generate an
AGENTS.md file that covers: setup commands, testing commands,
coding conventions, and important directories."

Review and save the output as AGENTS.md in the project root.

Using Codex Cloud for Onboarding#

For repositories you have not cloned yet:

1. Go to chatgpt.com/codex
2. Connect your GitHub account
3. Select the repository
4. Ask your onboarding questions

Codex Cloud clones the repo into a sandbox and explores it for you — useful when you want to understand a project before committing to cloning it locally.

Pro Tips#

• Use session resume — Save your onboarding session and come back to it: codex resume
• Attach a screenshot — If you have a running app, screenshot a page and ask "What code renders this?"
• Check the tests — "Walk me through the test suite structure" reveals what the team considers important
• Read the CI config — "Explain the CI/CD pipeline" shows the deployment and quality gates

## Next Steps

• Bug Fixing — Debug issues in your new codebase
• AGENTS.md Guide — Set up project conventions
• Features Overview — See all Codex capabilities