Repository-Centered Codex Workflow

This environment no longer treats one enormous ChatGPT Project as the center of software work. The real project boundary is the local Git repository, and durable context lives in version-controlled files. The Codex app, CLI, and VS Code extension are simply different entrances to the same repository.

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

Add an agent-readable contract without publishing or depending on a private bootstrap project. Enter the target repository and inspect existing ownership first:

cd /path/to/repository
git status --short --branch
find . -maxdepth 2 -type f \
  \( -name 'AGENTS.md' -o -iname 'arch.md' -o -iname 'architecture.md' \) \
  -print

Then make the smallest reviewable change:

1. preserve an existing architecture source rather than creating a duplicate;
2. create AGENTS.md only when the repository lacks an equivalent contract;
3. link compatible-agent bridges to the same rules instead of copying them;
4. add .gitignore, .editorconfig, or editor settings only for a demonstrated gap;
5. inspect git diff before any commit, push, or deployment.

If a repository-specific bootstrap command exists, its public documentation should describe behavior rather than expose the helper repository's name or absolute path. It should default to dry-run/create-only behavior, report conflicting architecture candidates, refuse unsafe paths, and require explicit authorization before replacing files.

Useful project-owned files may include:

• AGENTS.md, the canonical repository contract;
• .agents/rules/project-guidance.md, a bridge for compatible agents;
• .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. A bootstrap convenience must never become authority to overwrite the project.

What Belongs in AGENTS.md

Codex reads personal guidance first and then project AGENTS.md files along the directory path; guidance closer to the working directory takes precedence. 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 in separate Git worktrees, never the same checkout.
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                       # this environment also provides cx
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

Under WSL, keep repositories in the Linux filesystem, such as $HOME/Projects, and launch the editor from the WSL terminal:

cd /path/to/repository
code .

VS Code should show WSL: ... in the lower-left corner. 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.

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. If the extension runs on the Windows side by mistake, enable this VS Code setting:

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

This is a VS Code setting, not a ~/.codex/config.toml key. Reload the VS Code window after changing it.

A Compact Task Template

There is no need to feed the model a huge context dump. Four sections are usually enough:

Goal
The observable outcome to implement.

Context
Repository, branch, relevant files, verified facts, and reproduction steps.

Constraints
What must not change; whether network, dependencies, commit, push, or deploy are allowed.

Done when
Required tests, dry-runs, diff checks, and acceptance behavior.

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 WSL directory and account, and check personal ~/.codex/config.toml against project .codex/config.toml.

A bootstrap process proposes a second architecture document. Stop and locate the existing source of truth, including nested documentation. Humans must resolve multiple candidates; automation must not guess or create a competing architecture.

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 Workspaces for Pi, Codex, and Antigravity CLI for managing those agents in persistent terminals. The Build Log records the surrounding environment history.

My reading · Opened notes are remembered in this browser.