# Codex Hooks, rules and customization

> Codex: Instructions, prompts, memories, hooks, rules, imports, skills and subagents.

URL: https://docs.passion8.cc/en/docs/codex/customization-hooks-rules
Language: en
Publisher: Passion8

Customization has three layers: instructions explain how to work, controls constrain permitted behavior, and tools connect data and actions.

| Layer | Purpose | Files or entry points |
| --- | --- | --- |
| Instructions | Rules, style, workflow and completion criteria | AGENTS.md, prompts, memories, skills |
| Controls | Commands, approvals and lifecycle enforcement | Rules, hooks, sandbox, approvals |
| Tools | External data and operations | MCP, plugins and connectors |

## AGENTS.md

Use project instructions for:

- Directory structure and important modules.
- Install, start, test and build commands.
- Code style and architecture constraints.
- PR and review standards.
- Protected areas and completion criteria.

Codex loads applicable user and project instructions along the directory path. More specific instructions refine broader guidance.

```md title="AGENTS.md"
# Project instructions

## Commands
- npm run lint
- npm run typecheck
- npm run build

## Done when
- Relevant checks pass
- Diff is reviewed
- No unrelated refactor
```

Generate a draft:

```text
/init
```

## Custom prompts

Reusable prompts suit fixed instructions such as release checks, PR descriptions or log analysis. When the workflow also requires reference files, scripts, templates or multiple steps, a skill is a better package.

## Memories

| Mechanism | Scope | Suitable content |
| --- | --- | --- |
| AGENTS.md | Repository/directory | Project facts, commands and team standards |
| Memories | User/workspace where available | Preferences and recurring habits |
| Prompt | Current task/thread | One-off constraints |

Do not store credentials, private customer data or temporary tokens in memory.

## Hooks

Hooks run at lifecycle events and can implement checks or notifications. They can be loaded from hooks.json or inline TOML.

| Location | Scope |
| --- | --- |
| ~/.codex/hooks.json | User hooks |
| ~/.codex/config.toml | User inline hooks |
| .codex/hooks.json | Trusted-project hooks |
| .codex/config.toml | Trusted-project inline hooks |

```toml title=".codex/config.toml"
[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = './.codex/hooks/pre_tool_use_policy.sh'
timeout = 30
statusMessage = "Checking Bash command"
```

If one layer defines both forms, Codex can load both and warn. Prefer one representation per layer.

## Rules

Rules suit predictable command-prefix policy outside the ordinary sandbox boundary:

```python title=".codex/rules/default.rules"
prefix_rule(
    pattern = ["git", "push"],
    decision = "prompt",
    justification = "Pushing branches requires explicit review",
    match = ["git push origin feature"],
)
```

| Decision | Behavior |
| --- | --- |
| allow | Permit a matching action |
| prompt | Request approval |
| forbidden | Block it |

When several rules match, the more restrictive decision wins.

## Skills and plugins

Skills package repeatable workflows:

```text
$skill-creator
/skills
$readme-skill
```

A plugin is a distribution package that can include skills, MCP configuration, assets, app mappings and a manifest. Stabilize a useful workflow before packaging it for a team.

## Import

/import migrates supported Claude Code setup, project information or recent chats. Review imported settings instead of accepting all historical configuration unchanged.

1. Import project instructions or command rules first.
2. Check conflicts with existing AGENTS.md.
3. Decide whether hooks, skills and prompts should migrate.
4. Inspect effective configuration with /debug-config afterward.

## Subagents

Custom agent definitions can live in:

| Location | Scope |
| --- | --- |
| ~/.codex/agents/ | Personal agents |
| .codex/agents/ | Trusted-project agents |

Definitions include name, description and developer_instructions. Use focused roles for exploration, tests, review or migrations. Isolate concurrent edits with worktrees rather than assigning the same files to several agents.

## Adoption order

1. Write a short AGENTS.md.
2. Turn repeated instructions into prompts or skills.
3. Use rules for explicit command policies.
4. Use hooks for checks, audit and notifications.
5. Connect needed external tools with MCP.
6. Package stable reusable capabilities as plugins.

## Official references

- [AGENTS.md](https://developers.openai.com/codex/guides/agents-md)
- [Codex manual: hooks and rules](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: skills and plugins](https://developers.openai.com/codex/codex-manual.md)