Codex

OpenAI Codex is used for automated maintenance tasks in the Green Goods monorepo. The repo-scoped configuration is intentionally small: AGENTS.md is the primary context, CLAUDE.md is the fallback, the default model is GPT-5.5, the local environment delegates lifecycle work to repo scripts, and the workspace-write sandbox disables network access.

Configuration

config.toml

The main Codex configuration lives at .codex/config.toml:

# Use CLAUDE.md as context (AGENTS.md is the primary, CLAUDE.md is fallback)
project_doc_fallback_filenames = ["CLAUDE.md"]
project_doc_max_bytes = 40960

# Default model for automated tasks
model = "gpt-5.5"
model_reasoning_effort = "xhigh"

[features]
hooks = true

# Sandbox: no network access during agent execution
[sandbox_workspace_write]
network_access = false

Key settings:

• project_doc_fallback_filenames -- Codex reads AGENTS.md by default; falls back to CLAUDE.md for directories without an AGENTS.md
• project_doc_max_bytes -- Up to 40 KB of project guidance is loaded when fallback docs are needed
• model -- gpt-5.5 is the current project default for automation runs
• hooks = true -- project hooks are enabled for supported Codex surfaces; prompts are interpreted directly against AGENTS.md, package guides, and .plans/
• network_access = false -- The workspace-write sandbox has no internet access during execution

Environment Metadata (environment.toml)

The checked-in environment file declares the local environment identity and delegates setup/cleanup to the repo-owned lifecycle scripts:

version = 1
name = "green-goods"

[setup]
script = '''
set -e

# Trust this worktree's exact mise config, prepend mise and Bun shims, then:
npm run setup -- --profile isolated
'''

[cleanup]
script = '''
set -e

# Trust this worktree's exact mise config, prepend mise and Bun shims, then:
bun run dev:clean
'''

Codex worktrees use the same generic isolated setup profile as other container or worktree flows:

npm run setup -- --profile isolated

The environment file is intentionally a thin launcher, not a Codex-specific setup implementation. It prepends the repo's mise and Bun shim locations because Codex local-environment shells are not guaranteed to be login shells, and first trusts the exact worktree .mise.toml so shimmed npm/bun calls can load the repo tool versions; all workspace behavior lives in scripts/dev/setup.js and scripts/dev/clean.js. The isolated setup profile starts from Node/npm, can bootstrap Bun when network access is available, then uses the Bun workspace runtime once it is installed or confirmed. It avoids host-only effects such as Foundry installation, Docker checks, service starts/stops, browser launches, secret resolution, and sibling-worktree cleanup. Cleanup removes disposable artifacts from the current checkout only and does not touch secrets, dependencies, services, or sibling worktrees.

Hooks

No project Codex hooks are currently registered. The previous prompt-submit normalization hook was removed because it could infer task contracts from pasted source material instead of the user's actual request. The shared rules live in AGENTS.md, package-local AGENTS.md, .plans/, and the builder docs.

Use Cases

Codex is used for tasks that benefit from sandboxed, automated execution:

• Mechanical transforms -- Renaming variables, updating imports across files
• Test generation -- Generating initial test scaffolds from existing patterns
• Lint fixes -- Automated formatting and lint rule application
• Documentation updates -- Updating code references in docs after refactors

Scope Constraints

When running automated maintenance tasks via Codex (or any automated agent), constraints from AGENTS.md apply:

• Max 20 files changed per PR
• Never touch deployment scripts, contract upgrade scripts, or .env files
• Do not create new packages or top-level directories
• Do not modify CLAUDE.md, AGENTS.md, or files in .claude/
• All automated PRs must be created as drafts with appropriate labels

Skills Discovery

Codex discovers skills from its standard locations ($HOME/.agents/skills, bundled, admin paths, and the repo-scoped .agents/skills tree when present). Green Goods keeps Claude and Codex on the same shared skill surface through a generated mirror:

• Canonical source: .claude/skills
• Codex-visible mirror: .agents/skills
• Regenerate mirror: bun run skills:sync
• Check mirror drift: bun run check:skills

Do not hand-edit .agents/skills; changes there will be overwritten by the sync script. Do not replace .agents/skills with a symlink. A symlink would remove copy drift, but it also means accidental Codex skill imports or experiments under .agents/skills can mutate the canonical Claude tree directly.

For design-system work, Codex should still follow the repo design source path explicitly: start with AGENTS.md, then read the root DESIGN.md, the affected surface DESIGN.md, .agents/skills/design/ARCHITECTURE.md, and the relevant Storybook or package builder doc before editing UI.

Relationship to Claude Code

Codex and Claude Code serve complementary roles:

Aspect	Claude Code	Codex
Context source	CLAUDE.md + .claude/	AGENTS.md + .codex/
Execution	Local machine	Automated workspace task
Network	Full access	None (agent phase)
Model	Claude Opus/Sonnet/Haiku	GPT-5.5
Best for	Interactive development	Automated maintenance
Memory	Session artifacts + tool-local conventions	Thread/automation memory

Next page

Next best action

Review the external AI reference page without treating it as project-local automation.

Gemini

• Claude Code
• MCP Guide