Starting Projects with Codex App

You just got the green light on a new service. The product spec is a Notion doc, the deadline is two weeks, and you need a project with TypeScript, a database, tests, CI, and deployment config before you write a single line of business logic. Setting all that up by hand takes a full day. Setting it up in the Codex App takes one thread.

What You’ll Walk Away With

• A repeatable process for bootstrapping any project type in the Codex App
• A production-quality AGENTS.md file that makes every future Codex task smarter
• Local environment configuration so worktrees install dependencies automatically
• Your first worktree thread — running isolated from your main checkout

The Workflow

Step 1: Create Your Project in the Codex App

Open the Codex App and add a new project. Point it at the directory where your repository lives (or will live). If you are starting from scratch, create the directory first and initialize a git repository — Codex needs a git repo to enable worktree mode.

mkdir ~/projects/billing-service && cd ~/projects/billing-service
git init

In the Codex App, click the project selector in the sidebar and add ~/projects/billing-service. You now have a project workspace where every thread inherits the right context.

Step 2: Scaffold the Project in a Local Thread

Choose Local mode for the initial scaffolding since you want the files written directly into your working directory. Send your first prompt with specific constraints — Codex works best when you tell it what “done” looks like.

Tip

Copy-paste prompt for project scaffolding:

Create a Node.js/TypeScript project for a billing service with:

Tech stack: Express, Drizzle ORM, PostgreSQL, Vitest, Docker Compose
Structure:
- src/routes/ for API endpoints
- src/lib/db/ for schema and queries
- src/middleware/ for auth and validation
- tests/unit/ and tests/integration/

Include:
- tsconfig.json with strict mode
- Dockerfile and docker-compose.yml with PostgreSQL
- .github/workflows/ci.yml with lint, type-check, test
- ESLint flat config with TypeScript rules
- A basic health check endpoint at GET /health

Do NOT generate placeholder business logic. Only infrastructure and tooling.

After Codex generates the files, open the review pane (the diff icon) to inspect what it created. Stage the changes you want, revert anything you do not, and commit directly from the App.

Step 3: Write Your AGENTS.md

This is the single most impactful file in your repository for Codex productivity. Every cloud task, automation, GitHub interaction, and local thread reads AGENTS.md to understand your project. Invest five minutes here and every future task gets better.

Tip

Copy-paste prompt for AGENTS.md generation:

Create an AGENTS.md file at the root of this project. Include:

1. Project overview: what this service does and its tech stack
2. Setup: how to install dependencies and start the dev server
3. Testing: the exact commands to run unit and integration tests
4. Linting: the lint and type-check commands
5. Code style: our conventions (named exports, async/await, Drizzle for DB)
6. Review guidelines: what to flag during code review (no raw SQL, validate all inputs, no console.log in production code)

Keep it concise. Codex reads this on every task, so optimize for signal, not length.

A good AGENTS.md looks like this:

# Billing Service

Express/TypeScript billing API with PostgreSQL via Drizzle ORM.

## Setup
npm install
docker compose up -d  # starts PostgreSQL
npm run db:migrate
npm run dev           # starts on port 3000

## Testing
npm run test           # Vitest unit tests
npm run test:integration  # requires running PostgreSQL

## Linting
npm run lint           # ESLint
npm run type-check     # tsc --noEmit

## Code style
- Named exports only
- async/await over raw promises
- Drizzle ORM for all database access (no raw SQL)
- Zod schemas for input validation on every route

## Review guidelines
- Flag any raw SQL queries
- Flag missing input validation
- Flag console.log (use structured logger)
- Verify error responses do not leak internal details

Step 4: Configure Your Local Environment

Local environments tell Codex what setup scripts to run when creating a worktree. Without this, every worktree starts bare — no node_modules, no database, no ability to run tests.

In the Codex App, go to your project settings and create a local environment with a setup script:

npm install
docker compose up -d --wait
npm run db:migrate

Now every worktree thread automatically installs dependencies and starts PostgreSQL before Codex begins work. This is what makes parallel development actually work — each worktree is self-contained.

Step 5: Launch Your First Worktree Thread

With infrastructure in place, test the full workflow. Select Worktree mode in the thread composer and choose your main branch as the starting point. Codex creates an isolated git worktree under $CODEX_HOME/worktrees/ so nothing touches your local checkout.

Tip

Copy-paste prompt for first feature in a worktree:

Implement a POST /api/invoices endpoint that:
- Accepts { customerId, items: [{ description, amount }] }
- Validates input with Zod
- Inserts an invoice record and line items using Drizzle
- Returns the created invoice with a generated invoice number
- Includes a unit test for the validation logic and an integration test for the database insert

Follow the patterns in AGENTS.md. Run tests after implementation.

When Codex finishes, you have three options for the worktree changes:

1. Create branch here — promotes the worktree to a named branch. Push and open a PR directly from the App.
2. Sync with local — applies the changes back to your local checkout. Use this when you need to verify against your running dev server.
3. Keep iterating — send follow-up prompts in the same thread to refine the implementation.

When This Breaks

Worktree setup script fails silently. If your local environment setup script has an error (for example, PostgreSQL did not start), Codex continues but cannot run tests. Check the integrated terminal (Cmd + J) to see the setup script output. Fix the script and start a new worktree thread.

AGENTS.md is too long. If your AGENTS.md exceeds a few hundred lines, Codex spends tokens reading instructions instead of doing work. Keep it focused on commands and conventions. Move detailed architecture docs to separate files and reference them only when relevant.

Git submodules in the project. Worktrees do not automatically initialize git submodules. Add git submodule update --init to your local environment setup script if your project uses them.

Scaffolding prompt generates too many opinions. If Codex generates files you did not ask for (README badges, contributing guides, excessive boilerplate), add an explicit constraint: “Do NOT create files I did not list. Only generate the files specified above.”

What’s Next

Understanding Codebases with Codex Use Codex across surfaces to map architecture and onboard to unfamiliar code

Building Features with Parallel Agents Spin up multiple worktree threads to develop features in parallel