Setting Up Codex

Workloom manages Codex configuration files, agent definitions, and sandbox policies from canonical packages. The unique challenge with Codex: AGENTS.md is nestable and mergeable across package boundaries, and Workloom handles multi-package merging automatically with deterministic ordering.

What Workloom Renders for Codex

When you run wl pull on a workspace targeting Codex, Workloom generates:

File	Purpose	Ownership
`AGENTS.md`	Merged agent definitions from all packages	Workloom-managed
`.codex/config.toml`	Sandbox settings, trust policies, provider config	Workloom-managed
`.codex/skills/**`	Reusable skill definitions	Workloom-managed
`.codex/agents/*.md`	Agent behavior files	Workloom-managed

All generated files carry Workloom ownership metadata. Developer modifications trigger drift detection.

How Nested AGENTS.md Merge Works

Codex supports nested AGENTS.md files—agents can inherit from parent directories. Workloom respects this hierarchy:

AGENTS.md           # Root-level agents (highest precedence)
apps/web/AGENTS.md  # Web app specific agents
services/api/AGENTS.md  # API service agents

When multiple packages define agents, Workloom merges them using nearest-ancestor precedence:

Nearest ancestor wins. A package's AGENTS.md in apps/web/ takes precedence over a root-level AGENTS.md if you're working in apps/web/.
Alphabetical within same level. Multiple packages at the same directory level merge in alphabetical order by scope + name (e.g., @acme/base-agents before @acme/web-agents).
Section separators. Each package's contribution is marked with a comment section:

<!-- @acme/base-agents@1.0.0 -->
## Core Agents
...

<!-- @acme/web-agents@2.1.0 -->
## Web-Specific Agents
...

Multi-Package Merge Strategy

When a workspace includes multiple packages for Codex:

{
  "packages": [
    { "packageId": "@acme/base-agents@1.0.0" },
    { "packageId": "@acme/web-agents@2.1.0" },
    { "packageId": "@acme/security-agents@1.4.2" }
  ]
}

Workloom generates a single merged AGENTS.md with content ordered as:

@acme/base-agents (alphabetically first)
@acme/security-agents
@acme/web-agents (alphabetically last)

Each section is marked with its source package and version. If the same agent is defined in multiple packages, the last one in merge order wins (alphabetically last package).

Sandbox Settings in config.toml

Codex sandbox policies control what tools the AI can use. Workloom projects these into .codex/config.toml:

[sandbox]
# Trust class: tool_permission (requires approval)
allow_file_writes = true
allow_subprocess = true
allow_browser = true

# Restricted permissions
allow_network = false
deny_patterns = [
  "*.env",
  "**/secrets/**",
  ".git/config"
]

[experimental]
# These require extra approval
enable_mcp = true
mcp_servers = ["my-remote-server"]

Any tool_permission assets in sandbox settings require explicit operator approval before projection.

Example: Base Package

Create a canonical package with core Codex agents:

{
  "scope": "@acme",
  "name": "base-agents",
  "version": "1.0.0",
  "trustClass": "passive_text",
  "assets": [
    {
      "name": "agents-md",
      "type": "instruction",
      "provider": "codex",
      "trustClass": "passive_text",
      "path": "AGENTS.md",
      "content": "# Codex Agents\n\n## Core Workflow Agent\n\nResponsible for coordinating team tasks.\n\n### Capabilities\n\n- File editing\n- Test running\n- Git operations\n\n## Code Review Agent\n\nAnalyzes pull requests and suggests improvements.\n"
    },
    {
      "name": "sandbox-config",
      "type": "settings",
      "provider": "codex",
      "trustClass": "tool_permission",
      "path": ".codex/config.toml",
      "config": {
        "sandbox": {
          "allow_file_writes": true,
          "allow_subprocess": true,
          "allow_browser": false,
          "allow_network": false
        }
      }
    }
  ]
}

Example: Web-Specific Package

Add a second package for web-specific agents:

{
  "scope": "@acme",
  "name": "web-agents",
  "version": "2.1.0",
  "trustClass": "passive_text",
  "assets": [
    {
      "name": "web-agents-md",
      "type": "instruction",
      "provider": "codex",
      "trustClass": "passive_text",
      "path": "apps/web/AGENTS.md",
      "content": "# Web App Agents\n\n## React Component Agent\n\nSpecialized in React patterns and component design.\n\n## Testing Agent\n\nWrites Jest tests for React components.\n"
    }
  ]
}

Example: Workspace with Multi-Package Codex Setup

Create a workspace that brings both together:

{
  "workspaceId": "wksp_codex_web_01",
  "orgId": "org_acme",
  "name": "Web App with Codex",
  "binding": {
    "type": "git-repository",
    "gitRemote": "git@github.com:acme/web-app.git"
  },
  "targets": [
    {
      "id": "root",
      "path": ".",
      "providers": ["codex"],
      "packages": [
        {
          "packageId": "@acme/base-agents@1.0.0",
          "channel": "stable"
        },
        {
          "packageId": "@acme/web-agents@2.1.0",
          "channel": "stable"
        }
      ]
    }
  ],
  "revision": 1,
  "projectionPolicy": {
    "codex": "generated_local"
  }
}

Rendered AGENTS.md with Multi-Package Merge

After wl pull, Workloom generates:

# Merged Codex Agents

<!-- @acme/base-agents@1.0.0 -->

# Codex Agents

## Core Workflow Agent

Responsible for coordinating team tasks.

### Capabilities

- File editing
- Test running
- Git operations

## Code Review Agent

Analyzes pull requests and suggests improvements.

<!-- @acme/web-agents@2.1.0 -->

# Web App Agents

## React Component Agent

Specialized in React patterns and component design.

## Testing Agent

Writes Jest tests for React components.

The merge preserves section markers so you can trace each agent back to its source package and version.

Sandbox Trust Gates

When your package includes tool_permission assets like sandbox settings:

wl pull --dry-run
# Output: Trust gate blocked: tool_permission assets in package "@acme/base-agents@1.0.0"
# The following permissions would be granted:
#   - allow_file_writes: true
#   - allow_subprocess: true
# Approval required. Run: wl approve tool-permission base-agents-sandbox

Review the sandbox policy, then approve:

wl approve tool-permission base-agents-sandbox
wl pull  # Now succeeds

Drift Detection

If a teammate manually edits AGENTS.md:

wl status
# Workloom Status Report
# Workspace: Web App with Codex
# Drift detected in 1 file:
#   AGENTS.md (state: owned_locally_modified)

See what changed:

wl diff
# AGENTS.md differs from desired state
# (unified diff showing changes)

Restore to the merged canonical version:

wl restore AGENTS.md
# Restored AGENTS.md to desired state

Package Resolution and Precedence

When a workspace references multiple packages with conflicting agents, merge order wins:

Scenario	Result
Same agent in two packages, alphabetically	Last package (alphabetically) wins
Agent in `AGENTS.md` and nested `apps/web/AGENTS.md`	Nested one takes precedence for that directory
No conflicts	All agents merged cleanly

Example: If both @acme/base-agents and @acme/web-agents define a "Code Review Agent", the one from @acme/web-agents will appear last in the merged file and become the active definition.

Common Patterns

Shared Base + Target-Specific Packages

{
  "targets": [
    {
      "id": "root",
      "path": ".",
      "providers": ["codex"],
      "packages": [
        { "packageId": "@acme/base-agents@1.0.0" }
      ]
    },
    {
      "id": "frontend",
      "path": "apps/web",
      "providers": ["codex"],
      "packages": [
        { "packageId": "@acme/base-agents@1.0.0" },
        { "packageId": "@acme/web-agents@2.1.0" }
      ]
    },
    {
      "id": "backend",
      "path": "services/api",
      "providers": ["codex"],
      "packages": [
        { "packageId": "@acme/base-agents@1.0.0" },
        { "packageId": "@acme/api-agents@1.2.0" }
      ]
    }
  ]
}

Each target gets:

Root: Base agents only
Frontend: Base + web-specific agents
Backend: Base + API-specific agents

Workloom renders AGENTS.md independently per target with the correct merge for each location.

CI/CD Integration

In your CI pipeline, ensure Codex configuration stays in sync:

wl sync --check
# Exit code 0: All Codex files in sync
# Exit code non-zero: Drift detected

With your workspace locked file:

wl sync --check --locked
# Only apply locked versions, fail on any drift

Next Steps

Learn about packages and assets — define your own Codex agents
Understand multi-package merge — detailed merge algorithm
Set up CI/CD integration — drift detection in your workflows

What Workloom Renders for Codex​

How Nested AGENTS.md Merge Works​

Multi-Package Merge Strategy​

Sandbox Settings in config.toml​

Example: Base Package​

Example: Web-Specific Package​

Example: Workspace with Multi-Package Codex Setup​

Rendered AGENTS.md with Multi-Package Merge​

Sandbox Trust Gates​

Drift Detection​

Package Resolution and Precedence​

Common Patterns​

Shared Base + Target-Specific Packages​

CI/CD Integration​

Next Steps​