Codex: Codex Getting Started
Last updated: 2026-08-31
Now that Codex is installed, let's start using it for real. This lesson walks you through your first task submission and the basic operation workflow.
📋 Prerequisites: Codex installed and logged in (see previous lesson)
1. What You Will Learn
- First run of Codex
- Basic task submission workflow
- Viewing and reviewing results
- Common interactions
2. First Run
(1) Prepare a Project
BASH
# Create a test project
mkdir my-first-codex && cd my-first-codex
# Initialize a simple Python project
echo 'def greet(name):\n return f"Hello, {name}!"' > app.py
(2) Launch Codex
BASH
codex
On first launch, you'll see a welcome screen. Select Yes, continue to proceed.
(3) Submit Your First Task
Enter the following in the input box:
TEXT
📖 Display only
Add unit tests to app.py using the pytest framework
Codex's execution process:
TEXT
📖 Display only
1. Reading app.py...
2. Creating test_app.py with pytest test cases
3. Running: pytest test_app.py
4. All tests passed ✓
▶ Example 1: Bob's First Use
Bob is a backend developer trying Codex for the first time:
BASH
cd bob-flask-api
codex
# Bob enters:
# "Add input validation to all API endpoints using marshmallow"
# Codex output:
# → Scanning 15 API endpoint files...
# → Installing marshmallow...
# → Creating schemas/ directory...
# → Adding validation to 15 endpoints...
# → Running tests: 34/34 passed ✓
3. Basic Operation Workflow
(1) Complete Workflow
graph TB
A[Enter project directory] --> B[Launch codex]
B --> C[Enter task description]
C --> D[Codex analyzes & understands]
D --> E[Execute operations]
E --> F[View results]
F --> G{Satisfied?}
G -->|No| H[Append instructions]
H --> D
G -->|Yes| I[End session]
(2) Task Submission Format
TEXT
📖 Display only
# Good task descriptions
codex "Fix the login bug in user.py, ensure tests pass"
codex "Refactor utils.js to TypeScript, keep functionality consistent"
codex "Add pagination to orders API, 20 items per page"
# Bad task descriptions
codex "Help me write code"
codex "Fix bug"
codex "Optimize something"
(3) Effective Prompt Principles
| Principle | Description | Example |
|---|---|---|
| Clear goal | State exactly what to do | "Add JWT authentication" not "change auth" |
| Provide context | Reference relevant files | "Follow the style in auth.py" |
| Include verification | Specify how to verify results | "Ensure all tests pass" |
| Step-by-step | Break complex tasks into steps | "Step 1: Create model; notify me when done" |
4. Interactive Operations
(1) Common Operations
| Operation | Description |
|---|---|
| Type text | Submit a new task or append instructions |
Y / N |
Confirm or reject Codex's operations |
Ctrl+C |
Interrupt current operation |
/help |
View help information |
/clear |
Clear conversation history |
/new |
Start a new session |
(2) Appending Instructions
After Codex completes a task, you can continue appending:
TEXT
📖 Display only
# First task
> Add logging to app.py
# Append
> Change log level to DEBUG
# Continue appending
> Output logs to file instead of console
▶ Example 2: Alice's Iterative Development
TEXT
📖 Display only
# Alice gradually refines features
> Create a FastAPI project skeleton
✓ Created main.py, routers/, models/
> Add user registration API
✓ Created /api/register endpoint
> Add email verification to registration API
✓ Added email verification flow
> Write integration tests
✓ Created test_register.py, 5 tests passed
5. Viewing and Reviewing Results
(1) Review Code Changes
After Codex modifies files, it displays a diff view:
DIFF
- def greet(name):
- return f"Hello, {name}!"
+ def greet(name: str) -> str:
+ """Greet a person by name."""
+ if not name:
+ raise ValueError("Name cannot be empty")
+ return f"Hello, {name}!"
(2) Check Test Results
BASH
# Codex auto-runs tests and displays results
Running pytest test_app.py...
✓ test_greet_normal - PASSED
✓ test_greet_empty - PASSED
✓ test_greet_type_hint - PASSED
3 passed, 0 failed
(3) Confirm or Rollback
- Confirm: Accept Codex's changes and proceed
- Rollback:
git checkout -- .to undo all uncommitted changes
6. Multi-File Operations
▶ Example 3: Project-Level Refactoring
TEXT
📖 Display only
> Migrate Express project to Fastify, replace all route definitions, ensure tests pass
# Codex execution process:
# → Scanning 45 files for Express patterns
# → Converting route definitions (32 routes)
# → Updating middleware (8 files)
# → Running test suite: 89/89 passed ✓
# → Updating package.json
# → Final test run: 89/89 passed ✓
7. Practical Tips
| Tip | Description |
|---|---|
Initialize project with git init |
Makes it easy to rollback Codex's changes |
| Run tests before submitting tasks | Ensure a working baseline |
| Small incremental submissions | One task at a time |
| Review every change | Don't blindly accept modifications |
| Use appended instructions effectively | Iteration is more reliable than getting it right in one shot |
❓ FAQ
Q What if Codex modifies the wrong file?
A Use
git checkout -- <file> to revert a specific file, or git checkout -- . to undo all changes. That's why we recommend initializing projects with git init first.Q What if a task takes too long?
A Press
Ctrl+C to interrupt, then resubmit with more specific instructions, or break the task into smaller steps.Q What if Codex misunderstands my intent?
A Directly append a clarifying instruction, e.g. "I meant X, not Y" — Codex will correct based on the updated context.
Q Can I communicate with Codex in Chinese?
A Yes, Codex supports multiple languages. However, English generally yields better results; for complex tasks, English descriptions are recommended.
Q Do I need to explain the project from scratch every time?
A No. Codex automatically reads project files as context. Conversation history within the same session is also preserved.
📖 Summary
- Basic workflow: Enter project → Launch codex → Enter task → Review results
- Effective Prompt: Clear goal + Provide context + Include verification
- Use appended instructions for iterative development
- Manage projects with git for easy rollback of incorrect changes
- Submit small increments and review every change
📝 Exercises
- Basic (⭐): Create a simple project and use Codex to add unit tests.
- Intermediate (⭐⭐): Complete a feature iteratively: create skeleton → add functionality → refine error handling.
- Advanced (⭐⭐⭐): Deliberately give Codex a vague instruction, observe how it interprets it, then use appended instructions to correct the result — document the entire process.
