Codex

What It Does

• Installs Codex hook configuration for OpsCompanion
• Installs Codex skills, plugin wiring, and local hooks through the CLI setup flow
• Captures local agent session events and checkpoints
• Makes org, user, workspace, and integration context available through opc context
• Lets Codex search shared knowledge and memory with opc search
• Grounds debugging and investigation work with opc logs and opc traces

Status

Available now.

Install

First install the CLI:

brew tap opscompanion/opc
brew install opc

Then run the guided setup flow:

opc setup

Choose Codex during setup to install the right skills, plugin configuration, and hooks for this workspace.

Automations

Codex automations are a good fit when you want OpsCompanion-backed checks to run in the background on a schedule.

Use this as a simple starting point:

• Run opc setup first so Codex has the right OpsCompanion hooks and skills installed
• Create the automation from the Codex app sidebar under Automations
• Start with focused prompts that use opc --agent codex context, opc --agent codex logs, opc --agent codex traces, or opc --agent codex search
• Test the prompt manually in a regular Codex thread before putting it on a schedule

Example starter prompts:

Check the last 30 minutes of production errors for the API with `opc --agent codex logs "error" --service api --severity ERROR --since 30m`. Summarize anything important and archive the run if there is nothing actionable.

Use `opc --agent codex search "recent auth incidents"` and `opc --agent codex context` to prepare a short status update for this workspace.

For how scheduling, worktrees, inbox triage, and sandboxing work in the app, see Codex automations.

How It Works

The Codex integration uses local hooks generated by the CLI. Those hooks call opc capture, which stores local session events and creates checkpoints that can later be searched and shared across agents.

opc setup handles the full onboarding flow in one pass:

• Verifies your API key and working OpsCompanion endpoint
• Lets you pick Codex as the active agent
• Installs the Codex skills and plugin wiring
• Generates the local hook configuration for the workspace

Codex sessions can also call the CLI directly:

opc --agent codex context
opc --agent codex search "auth migration"
opc --agent codex logs "timeout" --service api --severity ERROR --since 1h
opc --agent codex traces "checkout" --service api --since 6h

What Gets Installed

Running opc setup and selecting Codex sets up the Codex-specific pieces needed for the workflow:

• Codex hook configuration in .codex/hooks.json
• Codex skills and plugin registration for the local environment
• The correct agent metadata so sessions are tagged as Codex activity
• Session lookup using the Codex environment, including CODEX_SESSION_ID

Recommended Workflow

1. Run opc setup
2. Select Codex during the guided flow so the CLI installs skills and hooks for you
3. Use opc context at the start of a task to understand the current environment
4. Search prior discoveries with opc search "<query>"
5. Investigate current system behavior with opc logs and opc traces
6. Save durable findings with opc remember "<decision or finding>"

Troubleshooting

If Codex is not picking up the integration:

1. Re-run opc setup
2. Confirm .codex/hooks.json exists in the workspace
3. Run opc --agent codex context to verify the CLI is configured
4. If needed, fall back to the legacy flow with opc init and opc install --agent codex

For the full CLI reference, see OPC - OpsCompanion CLI.