---
title: "Codex hooks and Cursor hooks: how to use them for team coordination · Cork"
description: "How Codex and Cursor hooks work as of October 2026, where the config lives, how to block or brief an agent, and how to use hooks to coordinate a team's agents."
canonical: "https://corkcli.com/blog/codex-cursor-hooks-team-coordination"
last_updated: "2026-11-14"
published: "2026-10-03"
author: "Kevin Vera"
---

# Codex hooks and Cursor hooks: how to use them for team coordination

How Codex and Cursor hooks work as of October 2026, where the config lives, how to block or brief an agent, and how to use hooks to coordinate a team's agents.

By Kevin Vera · October 3, 2026 · [Guides](https://corkcli.com/blog/c/guides) · 6 min read

Codex and Cursor both run hooks: small programs the agent calls at fixed points (session start, before a tool runs, after a file edit) with a JSON payload on stdin. For team coordination you use them in three places: at session start to hand the agent context about what teammates are doing, before an edit to block or warn when the target is already being changed, and after an edit to report what changed. Codex reads hooks from `.codex/hooks.json` or `config.toml`, Cursor from `.cursor/hooks.json`, and both treat exit code 2 as "block this action".

## Where hooks live in Codex and Cursor

As of October 2026, the two tools use similar ideas with different file names and event names.

| | Codex | Cursor |
|---|---|---|
| Project config | `<repo>/.codex/hooks.json` or `[hooks]` in `<repo>/.codex/config.toml` | `<repo>/.cursor/hooks.json` |
| User config | `~/.codex/hooks.json` or `~/.codex/config.toml` | `~/.cursor/hooks.json` |
| Org level | Managed hooks | Enterprise `hooks.json` in a system path, plus team hooks from the dashboard (Enterprise) |
| Before a tool runs | `PreToolUse` | `preToolUse` (also `beforeShellExecution`, `beforeMCPExecution`, `beforeReadFile`) |
| After an edit | `PostToolUse` | `afterFileEdit` (also `postToolUse`) |
| Session start | `SessionStart` | `sessionStart` |
| Prompt submitted | `UserPromptSubmit` | `beforeSubmitPrompt` |
| Block | Exit code 2 with a reason on stderr, or JSON with `permissionDecision: "deny"` | Exit code 2, or JSON with `"permission": "deny"` |

Two details matter for teams. Codex loads project hooks only when the project's `.codex/` layer is trusted, and you review and trust each hook definition through the `/hooks` command. Cursor runs project hooks from the project root, so commands should use paths such as `.cursor/hooks/check.sh`, and a hook that crashes or times out fails open (the action goes through) unless you set `"failClosed": true`.

## A Codex hook that guards edits

Codex fires `PreToolUse` and `PostToolUse` for shell commands, for file edits made through `apply_patch`, and for MCP tool calls. For edits, the matcher can be `apply_patch`, `Edit` or `Write`. This `.codex/hooks.json` runs a check before every edit and a reporter after it:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "apply_patch",
        "hooks": [
          { "type": "command", "command": ".codex/hooks/check-claims.sh", "timeout": 10 }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "apply_patch",
        "hooks": [
          { "type": "command", "command": ".codex/hooks/report-edit.sh", "timeout": 10 }
        ]
      }
    ]
  }
}
```

The hook reads JSON on stdin (it includes `session_id`, `cwd`, `hook_event_name` and the tool input). To stop the edit, exit with code 2 and write the reason to stderr; Codex shows that reason to the model so it can adapt. If you omit `timeout`, Codex waits up to 600 seconds for most events, so set a short timeout on anything that calls a network service.

To give the agent context at the start of a session or with each prompt, return `additionalContext` inside `hookSpecificOutput` from a `SessionStart` or `UserPromptSubmit` hook. Codex treats that text as extra developer context and, by default, spills output above roughly 2,500 tokens to disk with a preview, so keep briefings short.

## A Cursor hook that guards edits

Cursor's `hooks.json` needs a `version` field, and each event maps to a list of commands. Matchers filter by tool type (`Shell`, `Read`, `Write`, `Grep`, `Delete`, `Task`, or `MCP:<tool_name>`):

```json
{
  "version": 1,
  "hooks": {
    "sessionStart": [
      { "command": ".cursor/hooks/brief.sh", "timeout": 10 }
    ],
    "preToolUse": [
      { "command": ".cursor/hooks/check-claims.sh", "matcher": "Write", "timeout": 10 }
    ],
    "afterFileEdit": [
      { "command": ".cursor/hooks/report-edit.sh" }
    ]
  }
}
```

A `preToolUse` hook answers with JSON on stdout: `"permission"` set to `allow`, `deny` or `ask`, plus an optional `user_message` (shown to you) and `agent_message` (sent to the agent). A `sessionStart` hook can return `additional_context` to inject text into the conversation and `env` to set session variables. `afterFileEdit` receives the absolute `file_path` and the list of `edits` with `old_string` and `new_string`, which is exactly what a reporter needs.

## What a coordination hook should actually do

Hooks are plumbing. The coordination comes from what the scripts check against. A workable minimum for a small team:

1. **Shared claims.** Keep a record of who is editing what: a file in a shared location, a lock branch, or a small service. The `PreToolUse` or `preToolUse` script looks up the target path and denies the edit with a clear message ("billing/invoice.ts is being changed by Dana's agent; pull first") when someone else holds it.
2. **Report every edit.** The post-edit hook writes the path, the session and a timestamp to the same record, so the next check is accurate.
3. **Brief at session start.** The session-start hook prints recent changes and active claims as `additionalContext` (Codex) or `additional_context` (Cursor), so the agent starts informed instead of discovering conflicts later.
4. **Fail safely.** Decide per hook whether a crash should block. In Cursor that is `failClosed`. In either tool, if you want to be strict, have the script itself exit 2 with a reason when it cannot reach the claims record, rather than relying on how a crash is treated.
5. **Keep it fast.** These hooks run on every edit. Cache lookups and keep the payload small; a slow hook is a slow agent.

The hard parts are the ones no single hook solves: deciding what counts as "the same code" (a file is coarse; a function is closer), notifying an agent that is mid-task when a teammate renames something it calls, and keeping the record correct across several machines. Many teams start with file-level claims and add the rest only when they feel the pain.

## How Cork helps

Cork ships these hooks for you. Its hooks in Claude Code, Codex and Cursor run the protocol with no extra model calls: at session start and on each prompt the agent gets a briefing with the exact signatures, callers and recent changes of the code it is about to touch; a write gate holds an edit against code another agent is changing right now until your agent has their version; and when a teammate renames a function or changes a signature your code depends on, your agent hears it on its next step and the change becomes a [semantic lint](https://corkcli.com/blog/semantic-lint) rule your agents are checked against. Any MCP client can also reach the same server at https://mcp.corkcli.com.

Cork is the [coordination layer](https://corkcli.com/blog/coordination-layer-ai-coding-agents) for multiplayer coding agents: it keeps Claude Code, Codex and Cursor agents, on one machine or across a team's machines, from overwriting each other on one codebase, and hands each agent what the others already learned.

Cork Free covers unlimited agents and repos on one machine with no account; the paid plan adds teammates' machines. Install it once for every repo on the machine:

```bash
curl -fsSL https://corkcli.com/install.sh | sh
```

## Frequently asked questions

### Does Codex support hooks like Claude Code?

Yes. As of October 2026, Codex supports `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop` and other events, configured in `hooks.json` or `config.toml`, and project hooks run only after you trust them with `/hooks`.

### Can a Cursor hook block the agent from editing a file?

Yes. A `preToolUse` hook matched to `Write` can return `"permission": "deny"` with an `agent_message`, or exit with code 2. Crashes and timeouts fail open unless the hook sets `"failClosed": true`.

### Can I share one hook script between Codex, Cursor and Claude Code?

The scripts can share logic, but each tool sends a different stdin payload and expects different output fields, so wrap one core script with a thin adapter per tool.

### Where should I commit hook config for a team?

Commit `.codex/hooks.json` and `.cursor/hooks.json` with the scripts they call. Keep personal hooks in `~/.codex` or `~/.cursor`.

## Sources

- <https://learn.chatgpt.com/docs/hooks>
- <https://cursor.com/docs/agent/hooks>
- <https://code.claude.com/docs/en/hooks>

## Related reading

- [Best Warp Oz alternatives in 2026](https://corkcli.com/blog/warp-oz-alternatives): Warp Oz alternatives compared as of October 2026: Cursor cloud agents, Claude Code cloud sessions, Codex, GitHub Copilot, Devin, and Cork for coordination.
- [MCP servers for coordinating coding agents: what they are and how to use one](https://corkcli.com/blog/mcp-servers-coordinating-coding-agents): What an MCP server for coordinating coding agents does, how it differs from hooks, and how to connect one to Claude Code, Codex, Cursor and Gemini CLI.
- [Best Factory (Droids) alternatives in 2026](https://corkcli.com/blog/factory-droids-alternatives): Factory Droids alternatives compared as of October 2026: Devin, Amp, Cursor cloud agents, OpenAI Codex, Warp Oz, and Cork as the coordination layer.
- [Parallel AI coding agents on a team: how to split who works on what](https://corkcli.com/blog/split-work-parallel-ai-coding-agents-team): How a team splits work across parallel AI coding agents: slice by code ownership, name shared files, one branch per agent, small tasks, and live coordination.

[All articles](https://corkcli.com/blog.md) · [Cork in Markdown](https://corkcli.com/index.md) · [llms.txt](https://corkcli.com/llms.txt)

This page in HTML: https://corkcli.com/blog/codex-cursor-hooks-team-coordination