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, the workspace-write sandbox disables network access, and hooks add repo-specific context and policy checks around tool use.

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"

[features]
hooks = true

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

[shell_environment_policy]
inherit = "all"
exclude = ["AWS_*", "AZURE_*", "ANTHROPIC_*", "OPENAI_API_KEY"]

[shell_environment_policy.set]
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"

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
• shell_environment_policy -- The shell inherits normal environment variables but excludes broad cloud/API credential patterns and sets the Claude agent-teams experiment flag for compatibility with repo automation

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. .mise.toml pins Node 22 and Bun 1.3; 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.

Indexer-generated files are not baked into the Codex environment launcher. Envio v3 writes generated TypeScript declarations to packages/indexer/.envio/; codegen uses the root Bun workspace and does not install a nested generated package. During a no-network agent phase, codegen is available after the frozen root dependency install has completed:

node scripts/dev/ci-local.js --generate-indexer
# or
cd packages/indexer && bun run codegen

Hooks

Project Codex hooks are enabled through .codex/hooks.json:

• SessionStart loads Green Goods Codex context on startup, resume, and compaction.
• PreToolUse checks Bash commands and edit/write operations before they run.
• PostToolUse adds Green Goods post-edit context after file edits.
• Stop checks final stop context before Codex finishes a turn.

These hooks are policy and context checks, not prompt rewriting. 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). In Green Goods, .agents/skills is a symlink to the canonical .claude/skills, so Claude Code and Codex share one skill tree — there is no generated mirror and nothing to sync:

• Canonical source: .claude/skills
• Codex-visible path: .agents/skills → symlink → .claude/skills

Edit skills in .claude/skills; Codex sees the same files through the symlink (it officially follows symlinked skill folders). Do not convert .agents/skills back into a real directory or a second copy — that reintroduces the copy drift this symlink removes.

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