Repository-Centered Codex Workflow

The center of software work should be the local Git repository, not a ChatGPT Project whose conversation keeps growing. The repository is the real project boundary, and context worth keeping lives in version-controlled files. The Codex app, CLI, and VS Code extension are simply three entrances to the same repository.

None of this is specific to Codex. When a repository has no CLAUDE.md, Claude Code reads AGENTS.md directly, and Antigravity CLI also treats AGENTS.md as workspace rules. The examples below use Codex; the repository contract, one chat per outcome and separate authorisation carry over to those agents unchanged.

The Core Model

Chat history is temporary working memory, not a project source of truth. A decision that should affect the next task belongs in AGENTS.md, architecture documentation, a README, a test, or an issue rather than a long conversation.

ChatGPT Projects remain useful for uploaded files, web sources, and related discussions, but they do not replace a local directory, Git state, and runnable tests. When coding in a Project feels indirect, start Codex from the repository.

First-Time Repository Adoption

The first time an agent enters a repository, give it a contract. AGENTS.md is exactly that: project rules written for the agent, covering how to install, how to test, what must not be touched, and what counts as done. Before writing one, check which rules and architecture documents already exist, then make the smallest reviewable change:

1. preserve the existing architecture source, the one architecture document the repository already treats as authoritative, instead of creating a duplicate;
2. create AGENTS.md only when the repository lacks an equivalent contract;
3. Codex, Claude Code and Antigravity CLI all read AGENTS.md directly, so a bridge file is usually unnecessary; add a one-line bridge that says “rules are in AGENTS.md” only for a tool that does not read it, and never copy the rules;
4. add .gitignore, .editorconfig, or editor settings only for a demonstrated gap;
5. inspect git diff before any commit, push, or deployment.

Useful project-owned files may include:

• AGENTS.md, the canonical repository contract;
• .gitignore, .editorconfig, and .gitattributes;
• one selected architecture document;
• optional project-owned VS Code settings.

For a mature repository, preserve uncommitted work and review every proposed file.

What Belongs in AGENTS.md

Under the official guidance discovery rules, Codex reads personal guidance first, then project guidance along the path from the project root to the current working directory; guidance closer to the working directory overrides earlier guidance. Codex reads at most 32 KiB of combined guidance by default, and the Claude Code docs advise keeping each CLAUDE.md under 200 lines. A project file should be brief and concrete, answering:

• What is the repository for, and where is the architecture source of truth?
• What are the install, test, build, and lint commands?
• Which directories, data, and generated files are out of scope?
• What must be read before code changes?
• Which checks define completion?
• Which push, deployment, migration, and destructive actions need approval?

Do not place a one-off task specification, temporary logs, or dozens of pages of background in AGENTS.md. Durable rules belong in the contract, domain knowledge in documentation, behavior in tests, and the current objective in the chat.

Codex App: The Long-Task Console

Use the Codex app for longer reasoning, cross-file implementation, independent reviews, or parallel work:

1. Open the local repository instead of creating a giant chat Project.
2. Start a chat for one verifiable outcome.
3. Have Codex inspect Git state, the nearest AGENTS.md, and architecture source.
4. For complex changes, establish a factual baseline before implementation.
5. Put parallel agents that write code in separate Git worktrees, never the same checkout; Multi-Agent Coordination explains what a worktree does and does not isolate.
6. Write durable decisions back to the repository when the task finishes.

Keep a conversation roughly the size of one branch or outcome. Start a new chat when direction changes, fork to compare another approach, and resume an old task when continuing it. Shorter contexts are easier to review and recover.

Codex CLI: The Default Repository Entry

The official installer and basic sign-in flow are:

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version
codex login
codex login status

Launch from the target directory; the CLI treats its starting directory as the project:

cd /path/to/repository
codex
codex -C /path/to/repository
codex exec "Run the tests and explain the first failure; do not edit files"
codex review
codex resume
codex doctor
codex update

The official CLI command reference lists these useful interactive commands:

Command	Purpose
/status	Inspect directory, model, permissions, and context
/permissions	Adjust approval and sandbox policy for this session
/model	Choose the model and, when available, its reasoning effort
/plan	Make a complex execution path reviewable
/review, /diff	Review current changes and the Git diff
/mention	Add a file to context explicitly
/new, /resume, /fork	Control the conversation lifecycle
/compact	Compress a long context and continue
/mcp, /apps, /plugins	Inspect connected capabilities

Keep workspace-write and on-request approval as the normal boundary. Do not use --dangerously-bypass-approvals-and-sandbox just to save a confirmation; elevate the specific action only when networking, cross-repository work, or publication requires it.

VS Code Extension: Work Beside the Code

After installing the official Codex extension, use the Codex sidebar icon or run Codex: Open Codex Sidebar from the Command Palette and sign in. The CLI and IDE normally share authentication and Codex configuration layers. Under WSL on Windows, keep the repository in your Linux home directory and run code . from the WSL terminal; see the official WSL guide.

The extension is best for:

• explaining the current selection or open files;
• making focused changes while viewing an inline diff immediately;
• adding a file or selection to the current thread;
• planning, reviewing, and running local work inside the editor;
• delegating longer work to the cloud and reviewing the result locally.

Useful entries include new chat, add file/selection to thread, and /plan, /review, /status, /model, /reasoning, /local, /worktree, and /cloud.

Opening Prompt and Authorization

Write each task you hand to an agent as a task packet: goal, context, constraints and done-when; context engineering shows the format.

A useful opening is:

First establish a factual baseline: confirm the repository root and Git state,
then read the nearest AGENTS.md and architecture source. Preserve unrelated
changes. Implement directly and run the relevant tests. Report changed files,
validation results, and residual risks. Do not commit, push, or deploy.

For diagnosis, say “read-only; do not fix.” For review, say “do not trust tests alone.” Authorize commit, push, PR, and deployment separately because each changes a different external state.

Troubleshooting

Codex lacks project context. Verify that it started in the correct directory, then put stable information in AGENTS.md or architecture documentation. Do not compensate for a wrong project boundary with an ever-growing prompt.

The conversation becomes slow and tangled. Start a new chat after completing an outcome. Use /compact, /resume, or /fork; do not make one thread carry an entire project lifecycle.

CLI and extension behave differently. Confirm that both use the same directory and account, and check personal ~/.codex/config.toml against project .codex/config.toml.

The real repository already has uncommitted changes. Never clean or overwrite them. Constrain the task, have Codex identify task-owned files, and use a separate worktree for parallel work.

See Herdr: A Persistent Terminal for Several Coding Agents for running several agents in persistent terminals. The Build Log records the surrounding environment history.

My reading