DEV Community: AgentKit Drawer

A Codex AGENTS.md template for OpenAI Codex CLI

AgentKit Drawer — Wed, 21 Oct 2026 02:03:31 +0000

OpenAI Codex reads AGENTS.md before it does any work. That file is the Codex CLI agent instructions for the repo: stack, commands, hard never-dos, and what “done” means. A short, specific file gets followed. A 600-line essay gets skimmed.

This guide is a Codex AGENTS.md template you can paste today, plus how Codex actually discovers those files, and how that differs from CLAUDE.md and Cursor rules.

What Codex reads

Codex builds an instruction chain once per run (in the TUI, once per session):

Global: ~/.codex/AGENTS.override.md if it exists, otherwise ~/.codex/AGENTS.md. Personal defaults, not repo rules.
Project: from the repo root (usually the Git root) down to the current working directory. In each directory it prefers AGENTS.override.md, then AGENTS.md. At most one file per directory.
Merge: files concatenate root → cwd. Closer files appear later, so they override broader guidance.

Empty files are skipped. Combined project instructions cap at about 32 KiB by default (project_doc_max_bytes). Keep the root file short; put specialist rules in nested directories instead of one giant README. Official discovery notes: Custom instructions with AGENTS.md.

Codex does not read CLAUDE.md or .cursor/rules/*.mdc. If those are your only instruction files, Codex guesses.

Minimal copy-paste template

Drop this at the repo root as AGENTS.md. Fill every <<FILL>>. Codex’s /init can scaffold a starter; edit that result the same way — exact commands beat vague vibes.

AGENTS.mdcopy

# AGENTS.md
<!-- OpenAI Codex CLI agent instructions. Fill every <<FILL>>. -->

## Project
- App: <<FILL: name and one-line purpose>>
- Stack: <<FILL: e.g. Next.js 15 App Router, Supabase, Stripe, pnpm>>
- Layout: <<FILL: where app/, lib/, tests, and generated types live>>

## Commands
- Dev: <<FILL: e.g. pnpm dev>>
- Test: <<FILL>>
- Lint: <<FILL>>
- Typecheck: <<FILL>>

## Hard rules
- Never print, log, or commit secrets. Never prefix secrets with NEXT_PUBLIC_.
- Never disable tests, typecheck, RLS, or other safety checks to make something pass.
- Keep diffs small. Never edit generated files by hand.
- For auth, payments, or migrations: write a short plan and wait for go.

## Workflow
1. Restate the goal in one line and list the files you will touch.
2. Make one small change, then run the tests / typecheck you listed.
3. Report what you verified, and what you could not verify.

## Done means
The commands above pass, the change is described in plain words, and you did not expand the scope.

Paste a safety section from the free agent-guardrails.md (MIT) when the agent will call tools or read untrusted content. For Next.js + Supabase, the free nextjs-supabase-rls.mdc is a Cursor-shaped rule; copy the bullets into AGENTS.md (or a nested supabase/AGENTS.md) so Codex sees them too.

How this differs from CLAUDE.md and Cursor rules

File	Who reads it	Shape	Use it for
AGENTS.md	OpenAI Codex CLI, Cursor, and other AGENTS.md-aware tools	Plain Markdown; nested files concatenate root → cwd	Shared source of truth: stack, commands, never-dos, done criteria
CLAUDE.md	Claude Code	Markdown; can import files with `@path`	A thin file that starts with `@AGENTS.md`, then Claude-only notes
*.cursor/rules/.mdc**	Cursor	Markdown + YAML frontmatter (`globs`, `alwaysApply`)	Path-scoped rules that load only when matching files are in context

Recommended layout: write AGENTS.md first so Codex has instructions. Add a one-line CLAUDE.md that imports it. Add scoped Cursor .mdc files for auth, RLS, or Stripe — do not paste the whole essay into every format. Full comparison: AGENTS.md vs CLAUDE.md vs Cursor rules. Claude-specific template: CLAUDE.md template.

Nested files and overrides

When a subdirectory has different commands or never-dos, put a second AGENTS.md there. Codex running from that directory loads the root file, then the nested one. If you need to replace the directory’s file without deleting it, use AGENTS.override.md in that folder — Codex will take the override and ignore the sibling AGENTS.md.

layout sketchcopy

repo/
  AGENTS.md                      # shared source of truth (Codex + others)
  CLAUDE.md                      # @AGENTS.md + Claude-only notes
  .cursor/rules/                 # Cursor-only, path-scoped
  services/payments/
    AGENTS.md                    # payments commands and never-dos

Free files (MIT)

All of these live in the public eli-alvarado/agentkit-drawer repo:

agent-guardrails.md — injection defense, ask-vs-act, uncertainty
nextjs-supabase-rls.mdc — RLS bullets you can mirror into AGENTS.md
godot-jam-timeline.md and agents-md-game-modding.md — game-shaped AGENTS.md starters

FAQ

What file does OpenAI Codex read?

Codex CLI reads AGENTS.md (and AGENTS.override.md when present) before it starts work. Personal defaults can live in ~/.codex/AGENTS.md. It does not read CLAUDE.md or Cursor .mdc rules.

Does Codex read CLAUDE.md or .cursor/rules?

No. Keep shared rules in AGENTS.md. Point Claude Code at that file with @AGENTS.md. Keep Cursor path rules in .cursor/rules/*.mdc.

Where should the Codex AGENTS.md template live?

Repo root, next to your lockfile. Nested AGENTS.md files refine the root file for a subdirectory. Codex concatenates from the Git root down to the working directory.

What is AGENTS.override.md?

In a given directory, it wins over AGENTS.md. Use it for a local or temporary override without deleting the shared file. Codex still takes only one instruction file per directory.

How is this different from Cursor rules?

AGENTS.md is unscoped plain Markdown. Cursor .mdc files add frontmatter so a rule loads only for matching paths. Shared facts belong in AGENTS.md; path-scoped extras belong in Cursor rules.

Want the whole drawer?

The Vibe Starter Rules Pack ($19) ships a ready AGENTS.md + CLAUDE.md pair, 8 scoped Cursor rules, 12 slash-command prompts, and launch checklists for Next.js + Supabase + Stripe — the file Codex actually reads, plus the tool-specific extras. The Agent Builder Prompt Pack ($29) is the system-prompt and eval kit for Codex-class agents.

Buy Vibe Starter · $19
Buy Agent Builder · $29

Not ready for a full pack? Start with One-File Agent Rules ($9), one universal AGENTS.md for any stack, or get the free Starter AGENTS.md by email.

Launch week: 30% off any kit with code LAUNCH at Stripe checkout, through Oct 28, 2026. 14-day refund.

Originally published at agentkitdrawer.com.

Claude Code subagents, hooks and slash commands: a working setup

AgentKit Drawer — Wed, 21 Oct 2026 01:56:55 +0000

CLAUDE.md tells Claude Code what to do. Subagents, hooks and slash commands are how you make it actually happen: focused reviewers with limited tools, shell scripts that enforce your rules instead of hoping the model remembers them, and one-word commands for your workflow.

Subagents: `.claude/agents/*.md`

A subagent is a Markdown file with YAML frontmatter: name, a description that tells Claude when to delegate (write “Use PROACTIVELY after…” to get it used automatically), and an optional tools list. Each subagent runs in its own fresh context, so it does not clutter the main conversation, and it does not see that conversation either: pass it the exact files and goal.

Least privilege: a reviewer or security auditor gets Read, Grep, Glob only. If it cannot edit, it cannot “fix” things you did not ask for.
One job each: planner, code-reviewer, test-writer, debugger, security-auditor, docs-writer covers most teams.
Output contracts: “Report MUST / SHOULD / NIT with path:line” beats “review the code”.

Run /agents in Claude Code to list, create and edit them.

Hooks: rules the model cannot skip

Hooks live in .claude/settings.json under "hooks". Each event (PreToolUse, PostToolUse, Stop, and others) has a matcher on the tool name (Bash, Edit|Write) and a command. The hook gets the tool call as JSON on stdin. Exit code 2 blocks the action and sends your stderr message back to Claude; exit 0 allows it.

PreToolUse on Bash: block rm -rf, git push --force, git reset --hard, curl | sh, pushes to main.
PreToolUse on Read|Edit|Write: refuse .env, *.pem and lockfiles, while still allowing .env.example.
PostToolUse on Edit|Write: run your formatter on the edited file. Never block here.
Stop: run tests when code changed; exit 2 keeps Claude working. Check stop_hook_active to avoid loops.

Hooks run with your user's permissions. Read every script before enabling it and keep them in version control. Pair them with permissions.deny entries in the same file for a second layer.

Slash commands: `.claude/commands/*.md`

Each file becomes /filename. Use $ARGUMENTS for what you type after the command, and frontmatter such as description, argument-hint and allowed-tools. Good commands chain your subagents: /feature = plan → implement → test-writer → tests → code-reviewer → summary.

Free snippet: copy it

.claude/hooks/block-dangerous-bash.shcopy

#!/usr/bin/env bash
# PreToolUse (matcher: Bash). Exit 2 = block; stderr is shown to Claude.
cmd=$(jq -r '.tool_input.command // ""')
deny=(
  'rm -rf /' 'rm -rf ~' 'rm -rf \*' 'rm -rf \.' 'git push --force' 'git push -f' 'git reset --hard'
  'git clean -fd' 'DROP DATABASE' 'DROP TABLE' 'TRUNCATE ' 'supabase db reset' 'prisma migrate reset'
  'alembic downgrade base' 'chmod -R 777' 'mkfs' 'dd if=' ':(){'
)
for p in "${deny[@]}"; do
  if printf '%s' "$cmd" | grep -qiF -- "${p//\\/}"; then
    echo "Blocked by .claude/hooks/block-dangerous-bash.sh: '$p' is destructive. Explain why it's needed and ask the human to run it." >&2
    exit 2
  fi
done
if printf '%s' "$cmd" | grep -qE '(curl|wget)[^|]*\|\s*(ba|z)?sh'; then
  echo "Blocked: piping a download into a shell. Download, inspect, then ask." >&2; exit 2
fi
if printf '%s' "$cmd" | grep -qE 'git push[^&;|]*\b(main|master)\b'; then
  echo "Blocked: pushing to main/master. Push a branch and open a PR." >&2; exit 2
fi
exit 0

FAQ

Where do Claude Code subagents live?

Project subagents go in .claude/agents/ as Markdown files with YAML frontmatter (name, description, optional tools). Personal ones go in ~/.claude/agents/. Use /agents to manage them.

How do I block dangerous commands in Claude Code?

Add a PreToolUse hook with matcher Bash in .claude/settings.json. The script reads the tool call JSON from stdin and exits with code 2 to block it; its stderr is shown to Claude. Add matching permissions.deny rules as a second layer.

What does exit code 2 mean in a Claude Code hook?

Exit 2 blocks the action (for PreToolUse) or tells Claude to keep working (for Stop), and stderr is fed back to Claude. Exit 0 allows. Other codes are non-blocking errors shown to you.

How do I make Claude Code run tests before it finishes?

Use a Stop hook that runs your test command when code changed and exits 2 on failure. Check the stop_hook_active field in the input and exit 0 when it is true, so the hook cannot loop forever.

Do subagents see the main conversation?

No. Each subagent starts with a fresh context window and only gets the task you hand it, so include file paths and the goal in the delegation.

Want the whole drawer?

The Claude Code Kit ($24) ships a fill-in CLAUDE.md, 6 least-privilege subagents, 10 slash commands, a settings.json with permissions and hook wiring, and 4 tested hooks (dangerous Bash, secret files, lockfiles, format, tests-before-stop).

Buy Claude Code Kit · $24
Buy FastAPI Kit · $19

Not ready for a full pack? Start with One-File Agent Rules ($9), one universal AGENTS.md for any stack, or get the free Starter AGENTS.md by email.

Launch week: 30% off any kit with code LAUNCH at Stripe checkout, through Oct 28, 2026. 14-day refund.

Originally published at agentkitdrawer.com.

AGENTS.md vs CLAUDE.md vs .cursor/rules: which file does your AI agent read?

AgentKit Drawer — Wed, 21 Oct 2026 01:56:14 +0000

Different AI coding tools look for different instruction files. If you only keep rules in one tool's format, the others guess. If you copy the same wall of text into every format, the copies drift. This guide maps what each file is for, and a setup that stays maintainable.

The short answer

AGENTS.md is the cross-tool open convention. OpenAI Codex, Cursor, and many other agents read it as plain Markdown project instructions.
CLAUDE.md is Claude Code's project memory file. It can pull in other files with @path syntax (for example @AGENTS.md).
Cursor project rules live in .cursor/rules/*.mdc with YAML frontmatter (description, globs, alwaysApply). The legacy single-file .cursorrules format is deprecated; prefer .mdc rules.
Windsurf stores Cascade rules as Markdown under .windsurf/rules/.

Comparison

File	Who reads it	Shape	Best for
AGENTS.md	Codex, Cursor, and other AGENTS.md-aware tools	Plain Markdown at the repo root (and optionally nested)	Shared source of truth: stack, commands, hard rules, definition of done
CLAUDE.md	Claude Code	Markdown; can import other files with `@path`	Claude-specific notes on top of shared AGENTS.md
*.cursor/rules/.mdc**	Cursor	Markdown + frontmatter (`description`, `globs`, `alwaysApply`)	Path-scoped rules that load only when matching files are in context
.cursorrules (legacy)	Older Cursor setups	Single root file, no frontmatter	Migrate away; use `.mdc` rules or AGENTS.md
.windsurf/rules/	Windsurf Cascade	Markdown files with activation modes (always / glob / manual)	Same ideas as Cursor rules, in Windsurf's layout

What each file is for

AGENTS.md

AGENTS.md is a simple open format: a README for agents. Put durable project guidance here: how to build and test, folder layout, conventions, and the never-do list. Keep it short enough that tools will follow it. Codex discovers project AGENTS.md files along the path from the repo root to your working directory; closer files can refine broader ones. Copy-paste starter: Codex AGENTS.md template.

CLAUDE.md

Claude Code loads CLAUDE.md at the start of a session. Use @path/to/file anywhere in that file to import more Markdown. Relative paths resolve from the file that contains the import. A common pattern is a one-line import of shared rules, then a few Claude-only notes:

CLAUDE.mdcopy

@AGENTS.md

# Claude Code notes
- Prefer the project package scripts over ad-hoc commands.
- Before touching auth, payments, or migrations: write a short plan and wait for go.

For a fuller template, see the free CLAUDE.md guide.

Cursor `.cursor/rules/*.mdc`

Each rule is an .mdc file under .cursor/rules/. Frontmatter controls when it loads:

alwaysApply: true — included in every chat.
globs with alwaysApply: false — attached when matching files are in context.
description without globs — Cursor can pull the rule in when it looks relevant.
Neither description nor globs — manual via @rule-name.

Plain .md files in that folder are ignored by the rules system (no frontmatter). Prefer small scoped rules over one giant file. Example RLS rule (also free on GitHub as nextjs-supabase-rls.mdc):

.cursor/rules/30-database-rls.mdccopy

---
description: Migrations and row-level security
globs: supabase/**
alwaysApply: false
---
- For each new table: enable RLS + policies in the same migration.
- Policies use (select auth.uid()); separate policies per command.
- Never disable RLS to "make it work". Fix the policy instead.

More Next.js + Supabase detail: Cursor rules for Next.js + Supabase. For a Python backend skeleton (venv, pytest, type hints), see Cursor rules for Python.

Windsurf `.windsurf/rules/`

Cascade reads Markdown rules from .windsurf/rules/, with activation similar in spirit to Cursor (always on, glob, or manual). Keep those files thin and mirror the ideas already in AGENTS.md. See Windsurf rules.

Recommended setup: one source of truth

Write AGENTS.md first. Stack, commands, hard rules, workflow, definition of done.
Add a thin CLAUDE.md that starts with @AGENTS.md, then only Claude-specific notes.
Add scoped Cursor rules for paths that need extra precision (auth, RLS, Stripe, env). Do not paste the entire AGENTS.md into every .mdc.
If you use Windsurf, port the same scoped ideas into .windsurf/rules/ without inventing a third full copy of the essay.
Delete or migrate .cursorrules so you are not maintaining a legacy file Agent mode may ignore.

When a rule misbehaves, fix it in the source of truth (AGENTS.md or the one scoped rule), not in three places.

layout sketchcopy

repo/
  AGENTS.md                 # shared source of truth
  CLAUDE.md                 # @AGENTS.md + Claude-only notes
  .cursor/rules/
    00-core.mdc             # alwaysApply: true (short)
    30-database-rls.mdc     # globs: supabase/**
    40-stripe.mdc           # globs: app/api/stripe/**
  .windsurf/rules/          # optional mirror for Cascade
    database-rls.md

Free files you can drop in today

nextjs-supabase-rls.mdc — Cursor rule for Supabase RLS
agent-guardrails.md — guardrail snippets for AGENTS.md or system prompts
agents-md-game-modding.md — AGENTS.md template for mods and small game tools
godot-jam-timeline.md — 48-hour jam timeline for agents

FAQ

Do I need AGENTS.md, CLAUDE.md, and .cursor/rules all at once?

Only if you use more than one tool. Shared rules live in AGENTS.md. Claude Code gets a thin CLAUDE.md with @AGENTS.md. Cursor gets scoped .mdc files when you need path-based loading. Do not duplicate the essay.

Is .cursorrules still supported?

It is legacy. Prefer .cursor/rules/*.mdc with frontmatter, and migrate remaining content into those files or into AGENTS.md.

Can Claude Code read AGENTS.md?

Its native file is CLAUDE.md. Import shared rules with @AGENTS.md so you maintain one copy. Imports are expanded when the session starts.

What goes in AGENTS.md vs a Cursor rule?

AGENTS.md: stack, commands, never-dos, done criteria. Cursor .mdc: path-scoped guidance via globs so auth, migrations, or webhooks only load when those files are in context.

Where do Windsurf rules live?

Under .windsurf/rules/ as Markdown. Keep them aligned with AGENTS.md rather than inventing a separate doctrine.

Want the whole drawer?

Skip the setup. The Claude Code Kit ($24) ships a fill-in CLAUDE.md, 6 least-privilege subagents, 10 slash commands, settings.json permissions and 4 tested hooks. The Vibe Starter Rules Pack ($19) ships a ready AGENTS.md + CLAUDE.md pair, 8 scoped .cursor/rules, 12 slash-command prompts and launch checklists for Next.js + Supabase + Stripe.

Buy Claude Code Kit · $24
Buy Vibe Starter · $19
See all 5 kits

Not ready for a full pack? Start with One-File Agent Rules ($9), one universal AGENTS.md for any stack, or get the free Starter AGENTS.md by email.

Launch week: 30% off any kit with code LAUNCH at Stripe checkout, through Oct 28, 2026. 14-day refund.

Originally published at agentkitdrawer.com.

DEV Community: AgentKit Drawer

A Codex AGENTS.md template for OpenAI Codex CLI

What Codex reads

Minimal copy-paste template

How this differs from CLAUDE.md and Cursor rules

Nested files and overrides

Free files (MIT)

FAQ

Want the whole drawer?

Claude Code subagents, hooks and slash commands: a working setup

Subagents: .claude/agents/*.md

Hooks: rules the model cannot skip

Slash commands: .claude/commands/*.md

Free snippet: copy it

FAQ

Want the whole drawer?

AGENTS.md vs CLAUDE.md vs .cursor/rules: which file does your AI agent read?

The short answer

Comparison

What each file is for

AGENTS.md

CLAUDE.md

Cursor .cursor/rules/*.mdc

Windsurf .windsurf/rules/

Recommended setup: one source of truth

Free files you can drop in today

FAQ

Want the whole drawer?

Subagents: `.claude/agents/*.md`

Slash commands: `.claude/commands/*.md`

Cursor `.cursor/rules/*.mdc`

Windsurf `.windsurf/rules/`