In this course, we are moving beyond simple AI chatbots. You will learn to use Codex, a "repo-native" agent. This means the AI doesn't just look at a single snippet of code; it understands how an entire project (a repository) fits together. Throughout this path, you will learn to configure Codex to plan tasks, fix bugs, and resume work exactly where it left off.

To learn these skills, we need a real project to work on. We will be using a version of Excalidraw, a popular open-source digital whiteboard tool. It is a modern, complex application with many files, making it the perfect playground for testing our AI agent’s abilities.

At the heart of this agent is GPT-5-Codex, a specialized version of OpenAI’s language model. Unlike general-purpose models, GPT-5-Codex is trained on real engineering tasks and workflows. This allows it to:

• Understand Project Context: It doesn't just see the file you are in; it understands how files interact.
• Perform Engineering Work: It can generate code, refactor complex logic, write tests, and fix bugs.
• Handle Multi-step Instructions: You can give it high-level goals in plain English, and it will plan the necessary file changes.

To use Codex CLI on your own machine, you would typically follow these steps:

1. Install Codex CLI:

   If you encounter permission errors, it’s best to use a Node version manager like nvm.

2. Set your OpenAI API key:

   For persistent access, you can add this line to your shell configuration file (e.g., ~/.bashrc or ~/.zshrc), or place it in a .env file in your project directory.

3. Start Codex:

However, for the course, everything is already installed and configured for you—you just need to run codex to start the agent.

In the CodeSignal IDE, you will interact with Codex primarily through a Command-Line Interface (CLI). While Codex is available as a web assistant or editor extension, the CLI is the most direct way to use it for real-world automation and session management.

Everything is pre-installed and pre-configured for you. For Codex to work effectively, you must run it from the root directory of your project. This ensures the agent has access to all files, configuration scripts, and the full context of your application. If you run codex from a subdirectory, the agent’s visibility is effectively limited to that subtree, which can lead to incomplete repo maps, missed references, or less accurate plans.

When you run Codex commands, the agent analyzes your request, proposes a plan, and shows you a preview of changes. You stay in control, deciding whether to accept, modify, or reject the suggestions.

To get the best results, remember to be specific: instead of saying "Fix the code," say "Fix the crash in the renderCanvas function when the input is null."

When you open a large project like Excalidraw for the first time, the first task for any developer is to "map" the repository. Because you are running Codex at the root of the repo, it can "see" the entire structure. Instead of opening every folder manually, we can ask Codex to do it for us. We start by asking for a high-level overview.

By starting with this, Codex will look at the README.md and other root files to explain the project’s purpose. Once we have the overview, we ask for a map of the structure:

This helps you understand the "shape" of the project instantly, identifying folders like src for code or public for static assets.

Once we know the general structure, we need to find the "heart" of the application. In programming, the entry point is the file where the application starts running. We also want to find the core logic, which in Excalidraw's case, is the code that handles the drawing canvas.

We add these specific questions to our request:

Codex will look for files like index.tsx or App.tsx and search for folders with names like packages/utils or components/canvas to find where the drawing math happens.

A professional repository includes tools to build and test code. We can ask Codex to find the testing framework and the commands we need:

By looking at package.json, Codex might tell you, "This project uses Vitest for testing and has a script called npm start to run the app." This is vital for verifying that your changes don't break the project.

In this lesson, you learned how to use Codex as a repository-native agent to orient yourself. We covered:

• The power of GPT-5-Codex and its focus on engineering workflows.
• How to interact with Codex via the CLI from the project root for full context.
• Prompting Codex to map a project, find entry points, and identify testing tools.

In the upcoming practice session, you will use these exact steps to explore the Excalidraw repository yourself. You will give Codex instructions and see how it generates a detailed report of the project structure!