Connect Codex

Staso hooks record supported Codex turns, tool activity, and Guard decisions. A Codex session must run after setup to produce a trace.

1. Install and configure

python3 -m pip install --upgrade staso
staso setup --target codex
staso status --target codex

Setup prompts for your Staso API key and workspace. It writes user hooks under ~/.codex/. Use --scope project for .codex/hooks.json in the current project. Review and trust each generated Staso hook command in Codex Settings → Hooks. Staso cannot grant that trust itself.

2. Run a task and inspect its trace

Ask Codex to inspect a harmless file and explain its contents. Open Traces → Traces in the selected Staso workspace and inspect the new session. Check that the prompt, any tool steps, and the completion belong to the same turn. Setup alone reports a pending first event.

Codex exposes 11 supported lifecycle events: SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SubagentStart, SubagentStop, and Stop. Staso keeps turns separate using their turn IDs. Model, token, cost, and timing fields are shown only when the host supplies enough evidence; missing values are not zero.

Guard and capture

PreToolUse checks supported proposals against an enabled, scoped policy. Audit records a would-block finding and lets the tool continue. Block can stop a matching proposal before execution. PermissionRequest leaves Codex's normal approval prompt intact. Setup's --no-guard disables Staso's check.

All five capture categories default on. Codex hooks do not expose a host system prompt or tool schema. To suppress request and tool arguments:

staso setup --target codex --no-capture-request --no-capture-tool-arguments

Suppressed evidence is unavailable to Guard. See capture controls.

Update or remove hooks

staso update
staso status --target codex
# To remove only these hooks:
staso uninstall --target codex

After an update, review and trust changed hook commands in Codex Settings. See Update Staso or troubleshooting.