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.
[features]
hooks = true
approval_policy = "on-request"
sandbox_mode = "workspace-write"- 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=trueSmoke 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