Codex Hooks and Programmatic Access Tokens: How OpenAI Is Making Codex Easier to Automate Around Your Code
OpenAI is positioning Codex as an automatable platform. Hooks let you inject scripts at key points in the agent loop -- validators, secret scanning, conversation logging, per-repo behavior. Programmatic access tokens give Business and Enterprise teams scoped credentials they can use in CI, release jobs, and internal automations, created from the ChatGPT admin console with finite expirations and revocation. Both are live in the official Codex developer docs.
OpenAI Developers summarized this thread directly: "Codex is getting easier to automate and customize around your code." Two pieces underpin that claim. Hooks inject scripts at key points in the Codex agent loop -- validators, secret scanners, conversation logging, per-repo behavior. Programmatic access tokens give ChatGPT Business and Enterprise teams scoped credentials for CI, release, and internal automations, created from the admin console with finite expirations and revocation.
For context on where Codex CLI itself surfaces hooks, our coverage of Codex CLI 0.129.0's /hooks browser is the relevant CLI-side anchor; for the headless app-server entry point most automation will pair with, see Codex CLI 0.130.0's codex remote-control.
Key Takeaways
- Hooks are an extensibility framework, not a single feature. They inject scripts at lifecycle points: before/after work, prompt-time, tool calls, turn stop.
- Hooks are enabled by default and configured in
hooks.jsonorconfig.toml. The/hooksslash command inspects, reviews, trusts, and disables them. - Only command handlers execute today. Async, prompt, and agent handlers are parsed but skipped. Only supported tool paths are intercepted.
- Enterprise-managed hooks can be enforced via
requirements.toml, letting platform or security teams require specific validators or scanners across an org. - Programmatic access tokens are scoped credentials for ChatGPT Business and Enterprise workspaces, created in the admin console under Access tokens.
- Tokens are tied to user + workspace, with finite expirations recommended and revocation supported. Use them for
codex exec, CI jobs, release pipelines, and scheduled work. - Permissions are managed separately from general Codex local permission. Automation gets its own permission surface, not a developer's interactive grants.
What Hooks Actually Do
The official Hooks docs describe an extensibility framework, not a single feature. The patterns called out:
- Logging and analytics. Forward agent activity to internal observability systems for review, audit, or quality scoring.
- Block pasted API keys. Pre-prompt hooks that scan input for credentials and refuse to forward them to the model.
- Persistent memories. Hooks that read and write durable state across runs, materializing repo-specific or directory-specific behavior.
- Validation at turn stop. Run a validator (typecheck, lint, custom rule) when the agent finishes a turn and surface failures.
- Directory-based prompting. Customize behavior per repo or per directory so the agent treats different parts of a codebase with different policies.
Hooks are enabled by default. Configuration lives in hooks.json at the appropriate scope or in config.toml. The /hooks slash command in the CLI is where you inspect what is configured, review what would run, trust new hooks, or disable ones you don't want.
Hooks: Lifecycle Surface
The lifecycle surface that hooks address, paraphrased from the docs:
| Lifecycle point | Example use |
|---|---|
| Before work | Scan prompts for secrets; gate the session on policy |
| Tool call | Wrap or instrument tool invocations |
| Turn stop | Run validators (typecheck, lint, custom rules) after each turn |
| After work | Log conversations to internal systems; create memories |
| Per directory | Apply repo-specific or directory-specific behavior |
Known Caveats Today
The docs are explicit about a gap between what the framework parses and what currently runs:
- Only command handlers execute. Async, prompt, and agent handlers are parsed in config but skipped at runtime.
- Only supported tool paths are intercepted. Hooks do not blanket-intercept every internal action.
That gap is the thing to watch. If you're designing a security or compliance posture around hooks, build for command handlers today, but architect so additional handler types can plug in without re-doing the integration.
Enterprise Enforcement via requirements.toml
The enterprise lever is requirements.toml. Platform and security teams can enforce a baseline set of hooks across the organization -- mandatory validators, mandatory secret scanners, mandatory loggers -- rather than relying on individual developer configurations. Combined with the /hooks inspection surface, developers can see exactly what's enforced versus what they've configured locally.
What Programmatic Access Tokens Solve
Hooks are the in-loop extensibility surface. Access tokens are the "is this Codex run actually you?" surface. Per the official access-tokens docs:
Codex access tokens let trusted automation run Codex local with a ChatGPT workspace identity.
Concretely, that's the difference between an automated codex exec job impersonating a developer's session versus running with its own scoped credential tied to a workspace. The docs name the workflows:
codex execjobs (interactive or scripted)- Local scripts that drive Codex
- CI and scheduled jobs
- Enterprise workflows that need to invoke Codex programmatically
Where Tokens Come From
Tokens are created in the ChatGPT admin console under Access tokens. They're available to ChatGPT Business and Enterprise workspaces. Each token is tied to a user and a workspace, and the docs recommend finite expirations and explicit revocation.
Permission Separation
The single most important architectural point in the access-tokens doc: permissions for tokens are managed separately from the general Codex local permission. The interactive permission grants a developer accumulates over time (which paths Codex can write, which networks it can hit, which tools it can use) are not automatically extended to an automation job carrying their token.
Practically, that means an automation token is a fresh permission surface. Provision it deliberately for the job at hand rather than copying the developer's interactive grants.
Token Hygiene
The docs spell out the standard list, and it's worth quoting in working form:
- Store tokens in a secret manager. Never inline them in a script.
- Keep tokens out of logs (including CI logs, especially failed-build artifacts).
- Rotate on a schedule. Don't let any single token outlive its useful lifetime.
- Prefer finite expirations over indefinite ones.
- Tie tokens to the narrowest workflow that needs them; don't share one token across unrelated automations.
How a Reader Uses This
Two concrete shapes:
Pattern 1: Secret-Scan Hook + CI Token
A platform team that wants developers to use Codex but is worried about leaked credentials:
- Author a pre-prompt hook that scans user-submitted prompts for high-confidence credential patterns (API keys, OAuth refresh tokens, SSH private keys).
- Enforce it via
requirements.tomlso every developer in the workspace has it active. - Provision a separate programmatic access token for the CI job that runs nightly Codex
codex execvalidation against the main branch. - Scope the CI token's permissions narrowly -- it does not need the same path/tool grants as a human developer.
Pattern 2: Per-Repo Memory + Validation
A team with multiple repos that want different agent behavior in each:
- Use directory-based hooks to load repo-specific prompts and policies when Codex starts a session in that directory.
- Add a turn-stop hook that runs the repo's preferred validator (typecheck, lint, test) and surfaces failures back to the agent.
- Add an after-work hook that updates a memory file with the day's work for that repo, so the next session resumes with context.
- None of this requires programmatic tokens -- this is all interactive-session extensibility.
When to Reach for Access Tokens Instead of Just Hooks
| You want to... | Hooks | Access tokens |
|---|---|---|
| Modify in-session behavior (validators, scanners, memory) | Yes | No |
| Enforce org-wide rules across interactive sessions | Yes (via requirements.toml) | No |
| Run Codex from a CI pipeline | Maybe (hooks still apply) | Yes -- needed for non-interactive auth |
Run scheduled codex exec jobs as a service | No | Yes |
| Audit which automation ran which Codex action | No | Yes -- usage ties back to workspace |
How This Fits With the Recent Codex Surface Expansion
OpenAI has been moving Codex onto more surfaces and into more workflows. The pattern across recent months:
- April 16, 2026: Mac computer use, browser comment mode, thread automations -- Codex on more surfaces.
- May 7, 2026: Codex CLI 0.129.0 --
/hooksbrowser in the CLI to inspect lifecycle hooks. - May 9, 2026: Codex CLI 0.130.0 --
codex remote-controlfor headless operation. - Now: Hooks framework and programmatic access tokens documented as the official automation surface.
The earlier releases shipped the CLI-level affordances (lifecycle hooks, headless entry point). This is the part where OpenAI tells developers how the automation surface is intended to be used, with enterprise-grade auth attached.
Caveats
- Handler-type gap. Only command handlers run today; async, prompt, and agent handlers are parsed but skipped. Don't design critical paths around handler types that aren't executing yet.
- Tool-path coverage. Hooks only intercept supported tool paths. The framework is not a universal interceptor of every Codex internal action.
- Business/Enterprise only. Programmatic access tokens require a ChatGPT Business or Enterprise workspace. Individual Pro/Plus users do not get them.
FAQ
See structured FAQ in the schema header for question-level details: what hooks do, what handlers run today, how enterprise enforcement works, what access tokens are, and how their permissions are separated.
Sources
- Codex Hooks docs: https://developers.openai.com/codex/hooks
- Codex Access tokens docs: https://developers.openai.com/codex/enterprise/access-tokens
- Codex changelog: https://developers.openai.com/codex/changelog
Frequently Asked Questions
What did OpenAI announce about Codex automation?
OpenAI Developers framed it as 'Codex is getting easier to automate and customize around your code.' Two pieces underpin that. Hooks are an extensibility framework that injects scripts into the Codex agent loop at lifecycle points -- before/after work, prompt-time, tool calls, turn stop. Programmatic access tokens are scoped credentials for Business and Enterprise workspaces, created in the ChatGPT admin console, usable in CI/release/internal automations, with finite expirations and revocation.
What are Codex hooks?
Hooks are an extensibility framework for Codex. You inject scripts into the agentic loop at key points: validators that run before or after work, prompt-time hooks that scan inputs for secrets, hooks that log conversations to internal systems, and hooks that create memories or customize behavior per repo or directory. Hooks are enabled by default. Configuration lives in a `hooks.json` or in `config.toml`, and a `/hooks` slash command in the CLI lets you inspect, review, trust, or disable them.
What hook handlers actually run today?
Per the official docs, only command handlers run today. Async, prompt, and agent handlers are parsed but skipped at this point. Hooks only intercept supported tool paths. That is the gap to watch as the framework matures -- the surface area parsed in config is broader than the surface area that currently executes.
How are enterprise hooks managed?
Enterprise-managed hooks can be enforced via a `requirements.toml` file. That's the lever for a security or platform team that wants to require specific validators or secret-scanners across an organization, rather than relying on individual developers to opt in. The /hooks CLI inspection surface lets developers see what's enforced versus locally configured.
What are Codex programmatic access tokens?
Codex access tokens let trusted automation run Codex local with a ChatGPT workspace identity. They are available to ChatGPT Business and Enterprise workspaces. Use cases include `codex exec` jobs, local scripts, CI and scheduled jobs, and enterprise workflows. Tokens are created in the ChatGPT admin console under Access tokens, tied to a user and workspace, with finite expirations recommended and revocation supported.
How are access-token permissions managed?
Per the docs, permissions for access tokens are managed separately from the general Codex local permission. That separation is intentional: a developer's interactive Codex permissions are not the same as what an automation job should be allowed to do. Treat tokens like any other secret -- store them in a secret manager, keep them out of logs, rotate on a schedule, and prefer short expirations.