Codex hooks

Advanced engineering path for repo-local Codex hooks and project config when you need direct ownership instead of the packaged Codex plugin.

What this is

Use this guide only when engineers need direct control of repo-local .codex hooks while OSuite captures the governed runtime boundary through project-owned files.

This is a local runtime adapter, not the packaged Codex Plugin.

If you are rolling out Codex broadly, use Codex Plugin.

Install the local adapter

Enable project-scoped Codex hooks.

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[features]
hooks = true

Install the hook assets.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/osuite_pretool.py\"",
            "statusMessage": "OSuite policy preflight"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/osuite_posttool.py\"",
            "statusMessage": "OSuite evidence capture"
          }
        ]
      }
    ]
  }
}

Bind the runtime to your workspace.

OSUITE_BASE_URL=https://studio.osuite.ai
OSUITE_API_KEY=<workspace-api-key>
OSUITE_AGENT_ID=codex-runtime
OSUITE_RUNTIME_ADAPTER_ID=codex_hooks
OSUITE_HOOK_MODE=observe
OSUITE_SETTINGS_SCOPE=project
OSUITE_TRUSTED_PROJECT_REQUIRED=true

Smoke test

Run one harmless Bash command through Codex such as pwd or git status.

The expected control-plane result is:

one runtime_session_id
one governed action with runtime_family=tool_hook_runtime
runtime event receipts in OSuite
replay and proof surfaces attached to the action

Codex hooks

What this is

Install the local adapter

Smoke test

On this page