DEV Community: Eliran Kotzero

Hooks in Claude Code, Cursor and Codex: enforce what rules can't

Eliran Kotzero — Wed, 11 Nov 2026 07:16:06 +0000

Originally published on KitQuarry. Written by Eliran Kotzero for KitQuarry.

In short: a rule asks the agent to do something; a hook makes the tool do it. Claude Code, Cursor and Codex all run your scripts at fixed points: before a shell command, after a file edit, and when the agent wants to stop. That's where "never force-push", "format everything" and "run the tests before you say done" belong. Below are three small Python scripts that work in all three tools, the config for each, and the gotchas that make a hook quietly do nothing.

Why rules aren't enough

Instruction files are context. Claude Code's permissions docs put it plainly: "Permission rules are enforced by Claude Code, not by the model. Instructions in your prompt or CLAUDE.md shape what Claude tries to do, but they don't change what Claude Code allows." A long or crowded rules file makes it worse (see why a long CLAUDE.md gets ignored).

Hooks are the other half. The Claude Code hooks guide describes them as "deterministic control: certain actions always happen rather than relying on the LLM to choose to run them." Keep the rule as the explanation and add a hook for the handful of things that must happen every time:

Block a command before it runs (force-push, reset --hard, DROP TABLE).
Fix up after an edit (run the formatter, so style never comes up in review).
Refuse "done" while the checks fail, and send the agent back to work.

The same three hooks in each tool

Job	Claude Code	Cursor	Codex
Before a shell command	`PreToolUse`, matcher `Bash`	`beforeShellExecution` (or `preToolUse`, matcher `Shell`)	`PreToolUse`, matcher `Bash`
After the agent edits a file	`PostToolUse`, matcher `Edit` or `Write` (one regex, see config below)	`afterFileEdit`	`PostToolUse`, matcher `apply_patch` (or `Edit` / `Write`)
When the agent wants to stop	`Stop`	`stop`	`Stop`
How to block	Exit 2 + reason on stderr, or JSON `permissionDecision`	JSON `"permission": "deny"`, or exit 2	Exit 2 + reason on stderr, or JSON `permissionDecision`
How to keep it working	Stop hook exits 2	Return a `followup_message`	Stop hook exits 2 (becomes a new prompt)

Codex's hook format is close to Claude Code's: the same core event names, the same matcher + hooks nesting and the same hookSpecificOutput JSON. Cursor has its own flatter format, and it also reads Claude Code's hooks (more on that below).

Where hooks live and when they run

	Claude Code	Cursor	Codex
Project file	`.claude/settings.json` (`.claude/settings.local.json` for just you)	`.cursor/hooks.json`	`.codex/hooks.json` or `[hooks]` in `.codex/config.toml`
Personal file	`~/.claude/settings.json`	`~/.cursor/hooks.json`	`~/.codex/hooks.json` or `~/.codex/config.toml`
Before it runs	Interactive sessions hold back hooks until you accept the workspace trust dialog. `-p` and SDK runs treat the folder as trusted	Project hooks run only in a trusted workspace	Project hooks load only in a trusted project, and you review and trust each hook in `/hooks`. A changed hook is skipped until you trust it again
See what's loaded	`/hooks` (read-only)	Hooks tab in Customize, Hooks output channel	`/hooks`
Turn hooks off	`"disableAllHooks": true`	Remove the entries (the docs list no global switch)	`hooks = false` under `[features]`, or disable one hook in `/hooks`

All three merge hooks from every level instead of letting one file replace another, so a personal hook and a project hook for the same event both run. Hooks run with your user's permissions, so read the hooks in a repo you didn't write before you trust it. Claude Code's docs warn that claude -p runs a repository's committed hooks without asking.

Setup: one folder of scripts, three small configs

Put the scripts in the repo, outside any one tool's folder, so all three tools and all your teammates use the same code:

scripts/agent-hooks/guard_commands.py   # before shell commands
scripts/agent-hooks/format_edited.py    # after file edits
scripts/agent-hooks/require_checks.py   # when the agent wants to stop
.claude/settings.json                   # Claude Code
.cursor/hooks.json                      # Cursor
.codex/hooks.json                       # Codex

Each script reads the event JSON on stdin and works out which tool called it. Cursor sends a cursor_version field with every hook and expects JSON back; Claude Code and Codex accept exit code 2 with the reason on stderr. They need only Python 3 and git.

Hook 1: block risky commands

scripts/agent-hooks/guard_commands.py:

#!/usr/bin/env python3
"""Block risky shell commands. Claude Code / Codex PreToolUse hook, Cursor beforeShellExecution hook."""
import json, re, shlex, sys

PATTERNS = [  # (regex, why), checked against each part of a command line
    (r"\bgit\b.*\bpush\b.*\s(--force(?![\w-])|-f\b)", "force push (use --force-with-lease, and ask first)"),
    (r"\bgit\b.*\breset\b.*\s--hard\b", "git reset --hard discards uncommitted work"),
    (r"\bgit\b.*\bclean\b.*\s-[a-zA-Z]*f", "git clean -f deletes untracked files"),
    (r"\bgit\b.*\s--no-verify\b", "--no-verify skips the repo's git hooks"),
    (r"(?i)\b(drop\s+(table|database|schema)|truncate\s+table)\b", "destructive SQL"),
]

def risky_rm(part):
    try:
        words = shlex.split(part)
    except ValueError:
        words = part.split()
    if not words or words[0].rsplit("/", 1)[-1] != "rm":
        return None
    flags = [w for w in words[1:] if w.startswith("-")]
    if not any(f == "--recursive" or (not f.startswith("--") and "r" in f.lower()) for f in flags):
        return None
    for t in (w for w in words[1:] if not w.startswith("-")):
        if t in (".", "*") or t.startswith(("/", "~", "$")) or ".." in t:
            return f"recursive rm of {t} (too broad or outside the project)"
    return None

data = json.load(sys.stdin)
command = data.get("command") or (data.get("tool_input") or {}).get("command") or ""
if isinstance(command, list):
    command = " ".join(command)
parts = [p.strip() for p in re.split(r"&&|\|\||[;|\n]", command)]
parts = [re.sub(r"^((sudo|command)\s+|\w+=\S*\s+)+", "", p) for p in parts if p]
why = next((w for p in parts for rx, w in PATTERNS if re.search(rx, p)), None)
why = why or next((r for r in map(risky_rm, parts) if r), None)
if why is None and re.search(r"\b(curl|wget)\b.*\|\s*(sudo\s+)?(ba|z)?sh\b", command):
    why = "piping a download into a shell"

cursor = "cursor_version" in data  # Cursor sends this field to every hook
if why is None:
    if cursor:
        print(json.dumps({"permission": "allow"}))
    sys.exit(0)
msg = f"Blocked by a project hook: {why}. Don't work around it. Tell the user the exact command and why you need it."
if cursor:
    print(json.dumps({"permission": "deny", "user_message": f"Blocked: {why}", "agent_message": msg}))
    sys.exit(0)
print(msg, file=sys.stderr)
sys.exit(2)

It splits the command line at &&, ||, ; and pipes, so cd src && rm -rf ../.. is caught too. It blocks force-pushes (but not --force-with-lease), reset --hard, clean -f, --no-verify, DROP/TRUNCATE in SQL, piping a download into a shell, and recursive rm of /, ~, $VAR, .., . or *. rm -rf node_modules dist still runs. The message tells the agent to stop and ask you, rather than just saying "blocked" and leaving it to try another way. Edit PATTERNS to match your own never-list.

Claude Code, in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/agent-hooks/guard_commands.py" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/agent-hooks/format_edited.py" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/agent-hooks/require_checks.py", "timeout": 300 }
        ]
      }
    ]
  }
}

A hook that exits 2 blocks the call before permission rules are checked, so the guard holds even if you allow Bash wholesale. The reverse isn't true: a hook can't approve a call that a deny or ask rule catches. Claude Code also offers an if field ("Bash(git *)") to skip spawning the script for unrelated commands, but its docs call that filter best-effort, so the script above checks every command itself.

Cursor, in .cursor/hooks.json (project hooks run from the project root, so the path is relative to it):

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      { "command": "python3 scripts/agent-hooks/guard_commands.py", "failClosed": true }
    ],
    "afterFileEdit": [
      { "command": "python3 scripts/agent-hooks/format_edited.py" }
    ],
    "stop": [
      { "command": "python3 scripts/agent-hooks/require_checks.py", "timeout": 300, "loop_limit": 3 }
    ]
  }
}

failClosed: true blocks the command if the script crashes or times out. Without it, Cursor lets the command through. For commands it doesn't block, the script returns allow, as Cursor's own block-git.sh example does. That doesn't auto-approve anything: a Cursor team member confirmed on the forum in March 2026 that only deny is enforced from these hooks today, and allow and ask are ignored, so your normal approval settings still apply. Rely on deny and nothing else.

Codex, in .codex/hooks.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          { "type": "command", "command": "python3 \"$(git rev-parse --show-toplevel)/scripts/agent-hooks/guard_commands.py\"", "statusMessage": "Checking command" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "^apply_patch$",
        "hooks": [
          { "type": "command", "command": "python3 \"$(git rev-parse --show-toplevel)/scripts/agent-hooks/format_edited.py\"" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "python3 \"$(git rev-parse --show-toplevel)/scripts/agent-hooks/require_checks.py\"", "timeout": 300 }
        ]
      }
    ]
  }
}

The Codex docs suggest resolving repo-local hook paths from the git root, because Codex may start in a subfolder. ^Bash$ covers both shell commands and unified exec sessions. After you add the file, open /hooks and trust the hooks, or they won't run.

Hook 2: format what the agent edits

scripts/agent-hooks/format_edited.py runs Prettier (from the repo's node_modules), ruff format or gofmt on edited files, and skips any formatter that isn't installed. Change FORMATTERS to your stack.

#!/usr/bin/env python3
"""Format files after the agent edits them. Claude Code / Codex PostToolUse hook, Cursor afterFileEdit hook."""
import json, os, pathlib, shutil, subprocess, sys

data = json.load(sys.stdin)
root = pathlib.Path(data.get("cwd") or (data.get("workspace_roots") or [os.getcwd()])[0])
root = pathlib.Path(subprocess.run(["git", "rev-parse", "--show-toplevel"], cwd=root,
                                   capture_output=True, text=True).stdout.strip() or root).resolve()
prettier = root / "node_modules" / ".bin" / "prettier"
FORMATTERS = {  # extension -> command; a formatter that isn't installed is skipped
    (".js", ".jsx", ".ts", ".tsx", ".json", ".css", ".md"): [str(prettier), "--write"],
    (".py",): ["ruff", "format"],
    (".go",): ["gofmt", "-w"],
}

path = data.get("file_path") or (data.get("tool_input") or {}).get("file_path")
if path:  # Claude Code Edit/Write and Cursor afterFileEdit name the file
    files = [path]
else:  # Codex apply_patch doesn't: format every modified or new file instead
    out = subprocess.run(["git", "ls-files", "-z", "-m", "-o", "--exclude-standard"], cwd=root,
                         capture_output=True, text=True).stdout
    files = [str(root / name) for name in out.split("\0") if name]

for f in files:
    p = pathlib.Path(f)
    if not p.is_file() or root not in p.resolve().parents:
        continue
    for exts, cmd in FORMATTERS.items():
        if p.suffix in exts and shutil.which(cmd[0]):
            subprocess.run(cmd + [str(p)], cwd=root, capture_output=True)
if "cursor_version" in data:
    print("{}")
sys.exit(0)

Claude Code sends the absolute path in tool_input.file_path for Edit and Write, and Cursor's afterFileEdit sends file_path, so only that file is formatted.
Codex edits files with apply_patch and sends the patch text, not a path, so the script formats every modified or new file git reports. That includes files you changed by hand.
It runs after the edit has happened and always exits 0, so it never blocks the agent.
Claude Code doesn't run an Edit|Write hook when a Bash command rewrites a file (a sed -i, a codegen script). Its docs point to the FileChanged event for that.

Hook 3: don't let the agent stop while checks fail

scripts/agent-hooks/require_checks.py runs one command when the agent tries to finish. If it fails, the agent gets the last 40 lines of output and is sent back to work. Set CHECK to your fastest meaningful check, because it runs every time the agent stops, including after a plain question.

#!/usr/bin/env python3
"""Stop hook: keep the agent working while the checks fail. Claude Code, Codex and Cursor."""
import json, os, subprocess, sys

CHECK = "npm test"  # your fastest meaningful check, e.g. "npm run typecheck && npm test"

data = json.load(sys.stdin)
cursor = "cursor_version" in data
root = data.get("cwd") or (data.get("workspace_roots") or [os.getcwd()])[0]

def done():
    if cursor:
        print("{}")
    sys.exit(0)

if data.get("stop_hook_active") or (cursor and data.get("status") != "completed"):
    done()  # already pushed back once this turn, or the run was aborted or errored
if not subprocess.run(["git", "status", "--porcelain"], cwd=root, capture_output=True, text=True).stdout:
    done()  # nothing changed, e.g. the agent only answered a question

result = subprocess.run(CHECK, shell=True, cwd=root, capture_output=True, text=True)
if result.returncode == 0:
    done()
tail = "\n".join((result.stdout + result.stderr).strip().splitlines()[-40:])
msg = f"`{CHECK}` fails. Fix the code, not the tests, then finish. Output:\n{tail}"
if cursor:
    print(json.dumps({"followup_message": msg}))
    sys.exit(0)
print(msg, file=sys.stderr)
sys.exit(2)

Each tool keeps the agent going in its own way: Claude Code and Codex on exit code 2 (Codex turns the reason into a new prompt), Cursor when the hook returns a followup_message. Each also has a loop guard. Claude Code and Codex set stop_hook_active once a Stop hook has already sent the agent back, and the script then lets it stop, so you get one retry instead of an endless loop. Cursor caps follow-ups with loop_limit (5 by default; the config above sets 3). The script also skips the check when git status is clean. For the Claude Code details (the eight-block cap, testing a Stop hook by hand) see the "make done mean the tests passed" section of why a long CLAUDE.md gets ignored.

Using your Claude Code hooks in Cursor

Cursor loads hooks from .claude/settings.json, .claude/settings.local.json and ~/.claude/settings.json when Include Third-Party Plugins, Skills, and Other Configs is on (Cursor Settings → Agents → Third-Party Imports; on by default). It maps PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, PreCompact and UserPromptSubmit to its own events, maps the tool names Bash to Shell and Edit to Write, and accepts Claude Code's JSON responses. Notification and PermissionRequest aren't supported.

Two consequences:

A repo with only .claude/settings.json already gets these hooks in Cursor. The scripts should work on that path too, because every Cursor hook input includes cursor_version, but we tested only the native .cursor/hooks.json input format.
If you also add .cursor/hooks.json, Cursor runs the hooks from both files. For the guard that's harmless (any deny wins); for the formatter and the stop check it's double work. Pick one source per hook. Cursor-only options such as failClosed, loop_limit and beforeShellExecution go in the native file.

Why a hook silently does nothing

Exit 1 isn't a block. In Claude Code, any exit code other than 0 or 2 is a non-blocking error and the action goes ahead; the docs say "If your hook is meant to enforce a policy, use exit 2." Cursor fails open on crashes, timeouts and exit codes other than 2 too.
Failures fail open by default. A wrong path, a missing python3 or a timeout lets the command run. Set "failClosed": true in Cursor, or "onFailure": "block" on the handler in Claude Code (v2.1.295 or later). The Codex hooks page doesn't document an equivalent switch for command hooks.
The hook isn't trusted or isn't loaded. Check /hooks in Claude Code and Codex, or the Hooks tab and output channel in Cursor. In Codex, editing a hook definition marks it for review again.
Wrong path for the tool. Cursor runs project hooks from the project root and user hooks from ~/.cursor/. Claude Code gives you $CLAUDE_PROJECT_DIR. Codex may start in a subfolder, hence git rev-parse --show-toplevel.
Stray output. Claude Code reads stdout as JSON only if it's a single JSON object with nothing around it, and Codex treats plain text from a Stop hook that exits 0 as invalid. Print nothing, or exactly one object.
The work happened somewhere the hook doesn't watch. Codex doesn't hook hosted tools such as web search. Cursor cloud agents run project hooks but not ~/.cursor/hooks.json. Claude Code cloud sessions don't read your local ~/.claude/settings.json.
Windows. Cursor runs hook commands through PowerShell on Windows, and python3 may not exist there. Use py -3 or python; Codex also takes a commandWindows override.

Hooks are guardrails, not a sandbox

The guard matches text. A Python one-liner that calls shutil.rmtree() on the same folder doesn't contain rm -rf, and a commit message that mentions push -f gets blocked by mistake. Codex's docs say it directly: "Treat tool hooks as a useful guardrail, not a complete enforcement boundary." For limits that must hold, use each tool's permission rules and sandbox. We cover those settings for secrets in how to stop Claude Code, Cursor and Codex reading your .env file. Use hooks to make the team's never-list and definition of done automatic, and keep a short security rule so the agent knows why.

Test a hook before you trust it

Pipe the JSON each tool sends into the exact command from your config and check the exit code and output:

# Claude Code / Codex shape: expect exit 2 and the reason on stderr
echo '{"tool_name":"Bash","tool_input":{"command":"git push --force origin main"}}' \
  | python3 scripts/agent-hooks/guard_commands.py; echo "exit $?"

# Cursor shape: expect {"permission": "deny", ...} and exit 0
echo '{"cursor_version":"x","command":"git reset --hard HEAD~3"}' \
  | python3 scripts/agent-hooks/guard_commands.py; echo "exit $?"

We ran the three scripts this way on a sample repo, using each tool's documented input format and the exact command strings from the three configs: 27 commands through the guard for each tool, the formatter for a Claude Code edit, a Cursor edit and a Codex patch started from a subfolder, and the stop check with a clean tree, a passing change, a failing change and a repeat stop. All passed. We didn't run them inside Claude Code, Cursor or Codex, so watch /hooks or Cursor's Hooks output channel the first time each one fires.

A ten-minute setup

Copy the three scripts into scripts/agent-hooks/ and set PATTERNS, FORMATTERS and CHECK for your repo.
Add the config for each tool you use and commit it, so teammates and worktrees get the same hooks.
Trust the hooks: accept the workspace trust dialog in Claude Code, trust the workspace in Cursor, and trust each hook in Codex's /hooks.
Run the two test commands above, then ask the agent to force-push and confirm it's blocked.
Leave one line per hook in your rules file ("force-pushes are blocked by a hook; ask me instead") so the agent understands the block instead of fighting it.

FAQ

What's the difference between a rule and a hook?

A rule (CLAUDE.md, AGENTS.md, a Cursor .mdc file) is text the model reads and usually follows. A hook is a script the tool itself runs at a fixed point, such as before a shell command or when the agent wants to stop, whatever the model decided. Use rules to explain what you want and hooks for the few things that must happen every time.

Do Claude Code hooks work in Cursor?

Yes, by default. Cursor loads hooks from .claude/settings.json, .claude/settings.local.json and ~/.claude/settings.json when Include Third-Party Plugins, Skills, and Other Configs is on, and maps PreToolUse, PostToolUse, Stop and the other main events to its own. Bash maps to Shell and Edit to Write. If you also add .cursor/hooks.json, hooks from both files run.

Does Codex support hooks?

Yes. Codex reads hooks from hooks.json or inline [hooks] tables in config.toml, in ~/.codex or a project's .codex folder. Project hooks load only in a trusted project, and every non-managed hook must be reviewed and trusted in /hooks before it runs. The events and JSON shapes follow Claude Code's closely: PreToolUse, PostToolUse, Stop, SessionStart and more.

How do I block a command in a Claude Code hook?

Register a PreToolUse hook with the matcher Bash. The script reads the command from tool_input.command on stdin, and to block it either exits with code 2 and writes the reason to stderr, or exits 0 and prints a JSON permissionDecision of "deny". Exit code 1 doesn't block: Claude Code treats it as a non-blocking error and runs the command.

Are hooks a security boundary?

No. A command hook matches text, so a script that does the same thing under another name gets through, and by default a hook that crashes or times out lets the action proceed. Codex's docs call tool hooks a useful guardrail, not a complete enforcement boundary. Use permission rules and the sandbox for hard limits, and hooks for team policy and checks.

Sources

Official docs, checked 2026-11-01.

If you want a starting point, KitQuarry's free sampler is on GitHub: ai-coding-rules-sampler. It has a short CLAUDE.md/AGENTS.md, security rules and three skills (plan-feature, review-changes, record-decisions) for Claude Code, Cursor, Codex and Windsurf. MIT, free. (I made it.)

Too many agent skills? What they cost in context and how to prune

Eliran Kotzero — Sun, 08 Nov 2026 07:11:55 +0000

Originally published on KitQuarry. Written by Eliran Kotzero for KitQuarry.

In short: an installed skill costs context in two ways. Its name and description sit in a listing the model sees on every turn. Its full SKILL.md enters the conversation once it's used and stays there. The listing has a budget (1% of the context window in Claude Code, 2% in Codex by default), and when it overflows, descriptions get cut and skills stop triggering. Audit what's installed, turn off what you don't use, make side-effect skills manual-only, move repo-specific skills into the repo, and keep every description short with the trigger words first.

How skills load

All three tools follow the Agent Skills standard and use progressive disclosure: the model starts with a short entry per skill and reads the rest only when it picks one.

Tool	At session start	When a skill is used	Listing budget
Claude Code	Name and description of every skill Claude can invoke	Rendered `SKILL.md` enters the conversation and stays across turns	Scales at 1% of the context window; each entry capped at 1,536 characters
Codex	Name, description and file path	Reads the full `SKILL.md`	At most 2% of the context window, or 8,000 characters if unknown
Cursor	Discovers skills and presents them to Agent, which decides when they're relevant	Loads the skill; resources load on demand	Not documented

So the skill you never use isn't free. Claude Code's docs put it plainly: every skill in the listing adds to your context on every turn, whether or not Claude ever uses it.

What actually costs context

Part of a skill	When it costs context
`name` + `description` (+ `when_to_use` in Claude Code)	Every turn, for every skill the model can invoke on its own
Body of `SKILL.md`	From the moment it's invoked. In Claude Code it stays in the conversation on later turns, so every line is a recurring cost
Supporting files (`references/`, `examples.md`)	Only when the agent reads them
Scripts (`scripts/`)	Executed, not loaded. Only their output reaches the context
Manual-only skills (`disable-model-invocation: true`)	Claude Code leaves the description out of the listing entirely, so nothing until you type `/name`
Skills preloaded into a Claude Code subagent	The full content is injected when that subagent starts

The listing is where too many skills hurt. In Claude Code every skill name always stays in it, but when the descriptions don't fit the budget, Claude Code drops descriptions, starting with the skills you invoke least. A skill listed by name only loses the keywords Claude matches against, so it stops triggering on its own. Codex works the same way in its own terms: it shortens descriptions first, and with a large skill set it may leave some skills out of the initial list and show a warning.

After auto-compaction, Claude Code re-attaches each invoked skill but keeps only its first 5,000 tokens, within a combined 25,000-token budget filled from the most recently used skill. Invoke many skills in one long session and the older ones can drop out entirely.

How many skills is too many?

None of the three tools publishes a maximum count, and the number that matters isn't the count. It's whether the descriptions you rely on still fit. Signs you're past it:

Claude Code: run /doctor for an estimate of the listing's context cost and its biggest contributors. The Skills row in /context shows the listing's size after the budget is applied. When the listing exceeds its budget, a warning goes to the debug log (claude --debug).
Codex: a warning that some skills were left out of the initial list.
Any tool: a skill that used to trigger now only runs when you call it by name.

You can raise the budget (skillListingBudgetFraction, for example 0.02 for 2%, or SLASH_COMMAND_TOOL_CHAR_BUDGET in Claude Code; skills.max_context_tokens, up to 10,000 tokens, in Codex). That trades context for discoverability. Pruning usually gets you more.

Step 1: audit what's installed

Skills come from more places than most people check. Claude Code loads them from enterprise, personal (~/.claude/skills), project (.claude/skills, from the launch folder up to the repo root), nested subfolders, --add-dir directories, plugins (as /plugin-name:skill-name), and skills synced from your claude.ai account (~/.claude/skills/synced/). Codex reads .agents/skills from the launch folder up to the repo root, ~/.agents/skills, /etc/codex/skills and its bundled system skills. Cursor reads .agents/skills, .cursor/skills and their ~/ versions, and for compatibility also .claude/skills, .codex/skills, ~/.claude/skills and ~/.codex/skills.

Claude Code: /skills lists every skill and groups synced ones under claude.ai sync. /skill-doctor (v2.1.252 or later) shows what each skill costs and how often it's used, flags skills that have never been invoked, and says where to turn them off. Start with the ones that cost the most.
Codex: run /skills to see what's available.
Cursor: open Customize in the sidebar, then Skills.

For a quick look across all three tools' folders, this script lists every SKILL.md visible from the current folder (personal folders, then project folders up to the repo root), sorted by description length, and marks manual-only skills:

#!/usr/bin/env python3
"""List agent skills visible from this folder, with description size and body length."""
import pathlib, re, subprocess

home, cwd = pathlib.Path.home(), pathlib.Path.cwd()
try:
    root = pathlib.Path(subprocess.run(["git", "rev-parse", "--show-toplevel"],
                        capture_output=True, text=True, check=True).stdout.strip())
except Exception:
    root = cwd
dirs = [home / d for d in (".claude/skills", ".agents/skills", ".cursor/skills", ".codex/skills")]
p = cwd
while True:  # project folders from here up to the repo root
    dirs += [p / d for d in (".claude/skills", ".agents/skills", ".cursor/skills", ".codex/skills")]
    if p == root or p == p.parent:
        break
    p = p.parent

rows, seen = [], set()
for d in dirs:
    found = (list(d.glob("*/SKILL.md")) + list(d.rglob("SKILL.md"))) if d.is_dir() else []
    for f in sorted(found):
        if f.resolve() in seen:
            continue
        seen.add(f.resolve())
        text = f.read_text(errors="replace")
        m = re.match(r"---\n(.*?)\n---\n?(.*)", text, re.S)
        meta, body = (m.group(1), m.group(2)) if m else ("", text)
        desc = re.search(r"^description:\s*(.*)$", meta, re.M)
        manual = re.search(r"^disable-model-invocation:\s*(true|yes|on|1)\s*$", meta, re.M | re.I)
        rows.append((str(d).replace(str(home), "~").replace(str(root), "."), f.parent.name,
                     len(desc.group(1).strip().strip("\"'")) if desc else 0, body.count("\n") + 1, "manual" if manual else ""))

print(f"{'location':<40} {'skill':<26} {'desc':>5} {'lines':>6}")
for loc, name, dl, lines, flag in sorted(rows, key=lambda r: -r[2]):
    print(f"{loc:<40} {name:<26} {dl:>5} {lines:>6} {flag}")
auto = sum(r[2] for r in rows if not r[4])
print(f"\n{len(rows)} skills, {auto} description characters in auto-invocable skills")

Run it with python3 list_skills.py from your project. It reads single-line description: values only, follows symlinked skill folders and counts each target once. It can't see plugin, bundled or enterprise skills, or nested skills below the current folder, so use /skill-doctor for the full Claude Code picture. We tested it on a sample repo; it doesn't call any of the tools.

Step 2: turn off or remove what you don't use

Where the skill comes from	To remove it	To keep it but hide it
Claude Code personal or project	Delete `~/.claude/skills/<name>/` or `.claude/skills/<name>/`	`skillOverrides`, or `disable-model-invocation: true`
Claude Code plugin	`/plugin uninstall` or disable it in `/plugin`	Not covered by `skillOverrides`; manage it in `/plugin`
Synced from claude.ai	Turn it off for your claude.ai account (deleting the folder makes the next sync download it again)	Same
Claude Code bundled	`disableBundledSkills: true`	`"off"` in `skillOverrides`
Codex local	Delete the folder	`[[skills.config]]` with `enabled = false`, then restart
Cursor	Delete the folder	`disable-model-invocation: true`

Claude Code's skillOverrides has four states. In the /skills menu, highlight a skill and press Space to cycle them, then Esc to save to .claude/settings.local.json:

Value	Listed to Claude	In the `/` menu
`"on"`	Name and description	Yes
`"name-only"`	Name only	Yes
`"user-invocable-only"`	Hidden	Yes
`"off"`	Hidden	Hidden

// .claude/settings.local.json
{
  "skillOverrides": {
    "old-helper": "off",
    "release-notes": "user-invocable-only",
    "legacy-context": "name-only"
  }
}

# ~/.codex/config.toml
[[skills.config]]
path = "/home/you/.agents/skills/old-helper/SKILL.md"
enabled = false

Step 3: make side-effect skills manual-only

Deploy, commit, release and "send a message" skills shouldn't fire on their own anyway. Marking them manual-only also takes them out of the budget in Claude Code, where the description is no longer in context at all.

---
name: deploy
description: Deploys the current branch to staging or production. Only when the user asks to deploy.
disable-model-invocation: true
---

Cursor reads the same field: the skill is included only when you type /skill-name. In Codex, set allow_implicit_invocation: false under policy in the skill's agents/openai.yaml; explicit $skill invocation still works. The Codex docs don't say whether that also removes it from the initial list.

Step 4: consolidate and slim the rest

Merge overlapping skills. Three skills for "write tests", "add coverage" and "fix failing tests" compete for the same requests. One skill with a clear description and three sections in its body costs one listing entry.
Keep each skill to one job. That's the Codex docs' first best practice, and it's what lets a short description be accurate. Merging overlaps and keeping one job per skill aren't in conflict: merge skills that do the same job, split skills that do several.
Move reference material out of SKILL.md. Keep the body under 500 lines and put API details or long examples in files it links to. They load only when the agent reads them.
Write the body as instructions, not explanation. In Claude Code an invoked body stays in context across turns, so the docs suggest stating what to do rather than narrating how or why.
Turn always-loaded procedures into skills. The reverse problem also exists: a multi-step procedure in CLAUDE.md or an always-on rule loads every session, while a skill's body loads only when it's used.

Step 5: short, trigger-first descriptions

The description does two jobs: it's what the model matches your request against, and it's the part every skill pays for on every turn. Claude Code caps each entry's combined description and when_to_use at 1,536 characters, and Codex shortens descriptions when the list is crowded. Both docs say the same thing: put the key use case and trigger words first.

description: This skill is a comprehensive helper that can assist with many aspects of testing, including writing new tests, reviewing existing tests, improving coverage, and general quality work across the codebase.

description: Writes and runs unit tests for changed code. Use when the user asks to add tests, raise coverage, or reproduce a bug with a failing test. Not for end-to-end tests.

The second is shorter and names the requests people actually type. For the full pattern and a test loop, see how to write a SKILL.md that actually triggers.

Step 6: scope skills to where they're used

A personal skill loads in every project on your machine. If you use it in one repo, move it there.

Personal folders (~/.claude/skills, ~/.agents/skills, ~/.cursor/skills): only skills you want in every repo.
Project folders (.claude/skills, .agents/skills): skills for this repo, committed so the team gets them.
Nested folders for one package in a monorepo. Claude Code doesn't load skills in a .claude/skills below the launch folder at startup; they load the first time Claude reads or edits a file in that subdirectory. Cursor scopes a nested .cursor/skills or .agents/skills to files in its directory. Codex scans from the launch folder up to the repo root, so a skill in services/payments/.agents/skills is picked up when you start Codex in that service.
paths frontmatter (Claude Code and Cursor): glob patterns that limit when a skill is used. Claude Code loads it automatically only when working with matching files; Cursor surfaces it only then.

---
name: migration-rules
description: Rules for writing database migrations. Use when creating or editing a migration.
paths:
  - "db/migrations/**"
---

A ten-minute cleanup

Run /skill-doctor in Claude Code (or the script above) and list skills you haven't used in a month.
Delete or turn off each one. For plugin skills, disable the plugin.
Add disable-model-invocation: true to every skill with side effects.
Merge skills that answer the same requests.
Move repo-specific personal skills into their repos, and package-specific ones into nested folders.
Rewrite each remaining description: what it does, then "Use when..." with real phrasings, under a few hundred characters.
Check /context or /doctor again, then test the skills you kept in a fresh session.

The same thinking applies to instruction files: see why a long CLAUDE.md gets ignored, and for keeping one set of rules across tools, AGENTS.md vs CLAUDE.md. MCP servers have their own per-tool files, covered in one MCP server, three configs.

FAQ

How many Claude Code skills is too many?

None of the three tools publishes a maximum. The limit that matters is the skill listing budget. In Claude Code it scales at 1% of the context window, and when the listing overflows, Claude Code drops descriptions, starting with the skills you invoke least. Once a skill's description is gone, Claude can't match your request to it. Run /doctor for the listing's cost and /skill-doctor to find skills you never use.

Do installed skills use context even if I never use them?

Their listing entry does. Claude Code's docs say every skill in the listing adds to your context on every turn, whether or not Claude uses it. The SKILL.md body loads only when the skill is invoked. A skill with disable-model-invocation: true is left out of the listing, so it costs nothing until you call it.

How do I turn off a skill without deleting it?

In Claude Code, set it to "off" or "name-only" in skillOverrides, or use the /skills menu, which saves to .claude/settings.local.json. Plugin skills ignore skillOverrides, so disable the plugin with /plugin. In Codex, add a [[skills.config]] entry with the SKILL.md path and enabled = false to ~/.codex/config.toml, then restart Codex.

How much of the context window can Codex's skill list use?

By default the initial list uses at most 2% of the model's context window, or 8,000 characters when the window size is unknown. With many skills, Codex shortens descriptions first and may leave some skills out with a warning. skills.max_context_tokens sets a different budget, up to 10,000 tokens.

Should skills be personal or per project?

Keep only skills you use in every repo in ~/.claude/skills or ~/.agents/skills. Put repo-specific skills in that repo's .claude/skills or .agents/skills, and module-specific ones in a nested folder. Claude Code loads nested skills only once it works on files there, and Cursor scopes nested skills to their directory.

Sources

Official docs, checked 2026-10-30.

One MCP server, three configs: Claude Code, Cursor and Codex

Eliran Kotzero — Wed, 04 Nov 2026 07:06:40 +0000

Originally published on KitQuarry. Written by Eliran Kotzero for KitQuarry.

In short: all three tools speak MCP, but each keeps its servers in a different file. Claude Code uses .mcp.json at the repo root, Cursor uses .cursor/mcp.json, and Codex uses [mcp_servers.<name>] tables in .codex/config.toml. The JSON files look alike, but two details break copy-paste: Claude Code needs "type": "http" on remote servers, and every tool writes environment variables differently. Below is the same two-server setup written for each tool, the differences that matter, and how to check that each one loaded.

Where each tool looks

	Claude Code	Cursor	Codex
Project file (commit it)	`.mcp.json` at the project root	`.cursor/mcp.json`	`.codex/config.toml`, trusted projects only
Personal file	`~/.claude.json` (user scope, and local scope per project)	`~/.cursor/mcp.json`	`~/.codex/config.toml`
Format	JSON, `mcpServers`	JSON, `mcpServers`	TOML, `[mcp_servers.<name>]`
Env variable in a value	`${VAR}` or `${VAR:-default}`	`${env:VAR}`	Name the variable in a field such as `bearer_token_env_var`
See what loaded	`claude mcp list`, `/mcp`	Customize, MCP Logs in the Output panel	`codex mcp list`, `/mcp`

Sources: the Claude Code MCP docs, the Cursor MCP docs and the Codex MCP docs, all checked on 2026-10-29. Some third-party guides still say Codex has no project-level MCP config. The current Codex docs say it does: put the tables in .codex/config.toml in the repo, and Codex loads them once you trust the project.

The same setup, written three ways

The example has two servers: Context7, a local stdio server that the Codex docs use as their example (npx -y @upstash/context7-mcp), and team-docs, a stand-in for a remote HTTP server that needs a bearer token. mcp.example.com and TEAM_DOCS_TOKEN are placeholders; swap in your server's URL and auth. The token value never appears in a file. Each developer sets TEAM_DOCS_TOKEN in their own shell.

We checked that all three files parse (JSON and TOML). We didn't run them inside the three tools, so test them in yours before you rely on them.

Claude Code: `.mcp.json`

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "team-docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TEAM_DOCS_TOKEN}"
      }
    }
  }
}

An entry with a url needs a type ("http", "sse" or "ws"). Claude Code reads an entry without one as a stdio server, so it skips a url-only entry and reports has a "url" but no "type". The docs accept "streamable-http" as another name for "http".
${VAR} and ${VAR:-default} expand in command, args, env, url and headers. If a variable is unset and has no default, the config still loads, claude mcp list shows a missing-variable warning, and the literal ${VAR} text is used.
In a remote server's url and headers, some credential variables always read as empty, including ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN and NPM_TOKEN. That stops a repo's .mcp.json from sending your own credentials to a server it names. Use a variable name of your own, like TEAM_DOCS_TOKEN.
Claude Code sets CLAUDE_PROJECT_DIR inside a stdio server's environment. To use it in command or args of .mcp.json, write ${CLAUDE_PROJECT_DIR:-.}, because the variable isn't set in Claude Code's own environment.

Cursor: `.cursor/mcp.json`

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "team-docs": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TEAM_DOCS_TOKEN}"
      }
    }
  }
}

Variables use ${env:NAME}. Cursor also offers ${userHome}, ${workspaceFolder} (the folder that contains .cursor/mcp.json), ${workspaceFolderBasename} and ${/}. They resolve in command, args, env, url and headers.
Remote servers are written as url plus optional headers, as in Cursor's own examples. Cursor's stdio field table lists "type": "stdio" as required, so the example includes it.
Stdio servers can load more variables from a file with envFile (for example "${workspaceFolder}/.env"). Remote servers can't use envFile.

Codex: `.codex/config.toml`

# .codex/config.toml  (loaded only in a trusted project)
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.team-docs]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "TEAM_DOCS_TOKEN"

Codex doesn't use ${...} placeholders in these fields. It takes the variable's name instead: bearer_token_env_var for an Authorization bearer token, env_http_headers for other headers read from the environment, and env_vars to forward named variables to a stdio server. env sets fixed values.
Codex loads project .codex/ layers only when you trust the project. In an untrusted project it skips them, including project config, hooks and rules. With several .codex/config.toml files, the one closest to your working directory wins (config basics).
The ChatGPT desktop app, Codex CLI and IDE extension share this configuration, so setting it up once covers all three.
Per-server controls that the other two don't put in this file: enabled_tools and disabled_tools, default_tools_approval_mode (auto, prompt, writes or approve), startup_timeout_sec (default 10) and tool_timeout_sec (default 60).

Adding servers from the command line

# Claude Code: write the server into .mcp.json for the team
claude mcp add --transport http --scope project team-docs https://mcp.example.com/mcp
claude mcp add --transport stdio --scope project context7 -- npx -y @upstash/context7-mcp

# Codex: add a stdio server to your Codex config
codex mcp add context7 -- npx -y @upstash/context7-mcp

# Check what loaded
claude mcp list
codex mcp list

In claude mcp add, everything after -- is the server's own command, so its flags aren't read as Claude's. Without --scope, Claude Code uses local scope: the server goes into your entry for this project inside ~/.claude.json, not into .mcp.json, and your teammates won't see it. For a remote server in Codex, the docs show codex mcp add <name> --url <url>, and codex mcp login <name> starts an OAuth sign-in. Cursor adds servers through Customize or by editing mcp.json.

Which definition wins

Claude Code: local scope beats project scope, which beats user scope. Duplicates are matched by name, and the whole entry from the winning scope is used, with no field-by-field merge. A personal local copy of team-docs therefore hides the team's version completely.
Codex: CLI flags first, then project .codex/config.toml files (closest first), then a selected profile, then ~/.codex/config.toml.
Cursor: the docs list the project and global files but don't say which wins when both define the same server name. Give team servers names you won't reuse in your global file.

Approvals and trust

A committed MCP config runs commands on every machine that opens the repo, so each tool puts a gate in front of it:

Claude Code asks you to approve servers from .mcp.json in an interactive session. Until then, claude mcp list shows them as pending approval. A repo can't approve its own servers: approval settings committed to .claude/settings.json are ignored until you trust the folder. claude mcp reset-project-choices resets your choices. In claude -p runs and Agent SDK sessions there's no prompt, and Claude Code loads project servers without asking, so add a server to disabledMcpjsonServers or use --strict-mcp-config if you don't want it there.
Codex ignores .codex/config.toml until you trust the project.
Cursor asks for approval before it runs an MCP tool by default, and MCP follows the same run modes as terminal commands.

Read a server's source before you approve it, and give it a narrowly scoped token. If you're also keeping agents away from secrets files, our .env guide covers the file-access side for all three tools.

Keeping three files in sync

There's no shared MCP file that all three tools read, so you maintain three. A few habits keep that manageable:

Use the same server names in every file, so a rule like "use team-docs for internal API questions" in AGENTS.md or CLAUDE.md means the same thing in each tool.
Commit references, never values. Keep a .env.example or a short README table that lists the variables each developer needs.
When you change a server, change all three files in the same commit. A short note in your instruction file helps, the same way we suggest pointing CLAUDE.md at AGENTS.md in one source of truth.
Third-party sync tools exist. If you use one, check its output against the formats above, especially "type" on remote servers and the variable syntax.

Checklist

Write .mcp.json, .cursor/mcp.json and .codex/config.toml with the same server names.
Add "type": "http" to every remote server in .mcp.json.
Replace every secret with a variable: ${VAR}, ${env:VAR}, or a Codex *_env_var field.
Run claude in the repo and approve the project servers, then check claude mcp list.
Trust the project in Codex, then check codex mcp list or /mcp.
In Cursor, check the servers are on in Customize and look at MCP Logs in the Output panel if one fails.

Setting up instruction files too? The free sampler ships rules and skills in the formats Claude Code, Codex, Cursor, Windsurf and Copilot each expect. The AI Coding Rules Pack adds the full rule set and workflow skills.

FAQ

Where does each tool keep project MCP servers?

Claude Code reads .mcp.json at the project root. Cursor reads .cursor/mcp.json in the project. Codex reads [mcp_servers.<name>] tables in .codex/config.toml, but only in a project you've trusted. The personal versions are ~/.claude.json, ~/.cursor/mcp.json and ~/.codex/config.toml.

Can I copy Cursor's mcp.json into Claude Code's .mcp.json?

Not as is. Both use an mcpServers object, but Claude Code treats an entry with no "type" as a stdio server, so a remote server with only a "url" is skipped with an error until you add "type": "http". Environment variables also differ: Cursor writes ${env:NAME}, Claude Code writes ${NAME} or ${NAME:-default}.

Does Codex support project-level MCP servers?

Yes. Current Codex docs let you add [mcp_servers.<name>] tables to .codex/config.toml in the repo. Codex loads project .codex/ layers only for trusted projects, and the config closest to your working directory wins. The ChatGPT desktop app, Codex CLI and IDE extension share this configuration.

How do I keep API keys out of a committed MCP config?

Commit only variable references. In Claude Code use ${TOKEN} in .mcp.json, in Cursor use ${env:TOKEN}, and in Codex name the variable with bearer_token_env_var, env_http_headers or env_vars instead of writing the value. Each developer sets the variable in their own shell. Codex stores an OAuth client secret in config.toml, so keep that kind of setup in your personal ~/.codex/config.toml.

Why does my project MCP server not show up in Claude Code?

Claude Code asks you to approve project servers from .mcp.json in an interactive session. Until you do, claude mcp list shows the server as pending approval. Run claude in the folder and accept the trust dialog and the server prompt. To ask again later, run claude mcp reset-project-choices.

Sources

Official docs, checked 2026-10-29.

How to stop Claude Code, Cursor and Codex reading your .env file

Eliran Kotzero — Sun, 01 Nov 2026 07:05:32 +0000

Originally published on KitQuarry. Written by Eliran Kotzero for KitQuarry.

In short: .gitignore doesn't keep secrets away from a coding agent, and neither does a line in CLAUDE.md or AGENTS.md. Each tool has its own control. Claude Code uses Read deny rules plus the sandbox, Cursor uses .cursorignore plus a hook for terminal commands, and Codex uses a permission profile with deny globs. Each one leaves a gap, listed below. The real fix is not having production keys in the working tree.

Why "don't read .env" in your rules isn't enough

A rule in CLAUDE.md, AGENTS.md or a Cursor rule is guidance. The model usually follows it, but nothing enforces it. The Claude Code permissions docs say it directly: permission rules are enforced by Claude Code, not by the model, and instructions in your prompt or CLAUDE.md shape what Claude tries to do without changing what Claude Code allows. The same split exists in Cursor and Codex. Keep the rule (our security rules checklist covers what to write), and add the tool-level block below so a slip doesn't put a key into the conversation.

Three things people try that don't work:

.gitignore. It keeps the file out of commits. The agent works on your disk, so it can still open the file.
.claudeignore. Claude Code doesn't read it. Per the docs, the file has no effect, and its entries belong in Read deny rules.
A made-up settings shape. A "read": {"deny": [...]} block under permissions isn't the documented format. Deny rules are strings in permissions.deny, in the form Tool(specifier).

Claude Code: Read deny rules, then the sandbox

1. Deny the files

Put this in the project's .claude/settings.json and commit it, so everyone on the repo gets it:

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(!.env.example)",
      "Read(*.pem)",
      "Read(*.key)"
    ]
  }
}

How these match, per the path pattern docs:

Patterns use gitignore syntax. A bare filename matches at any depth, so Read(.env) is the same as Read(**/.env): any .env at or under the folder you started Claude in. It doesn't cover a .env in a parent folder or another project.
A rule starting with ! carves an exception out of the rules listed before it in the same file. Here, .env.example stays readable so Claude can still see which variables exist.
A Read deny rule also blocks the Edit and Write tools on that path, including creating the file.
Deny rules are checked first. An allow rule can't reopen a path a deny rule blocks, and a deny in any settings file wins.

To cover every project on your machine, put rules in ~/.claude/settings.json with a // (filesystem root) or ~/ (home) anchor. A single leading / in user settings means ~/.claude/, not your project, so Read(/secrets/**) there blocks ~/.claude/secrets. The docs give Read(//**/.env) as the pattern for any .env on the filesystem.

2. Know what deny rules don't cover

The docs are explicit. Read deny rules apply to Claude's built-in file tools (Read, Grep, Glob, best effort), @file mentions, IDE selection context, the Bash file commands Claude Code recognizes (cat, head, tail, sed, tee) and redirect targets like < .env. They don't apply to:

a command that reads files without naming them, such as grep -r API_KEY . run from the folder that holds .env;
a script that opens the file itself, like python3 -c "print(open('.env').read())" or your app's dev server printing its config.

3. Turn on the sandbox for shell commands

The sandbox is the OS-level layer for Bash commands and every process they start (Seatbelt on macOS, bubblewrap on Linux and WSL2; native Windows runs commands unsandboxed). It's off by default. Run /sandbox in a session, or set sandbox.enabled in settings. By default sandboxed commands can still read most of the machine, but the sandbox docs say paths from your permission rules, including Read and Edit deny rules, are merged into the sandbox configuration. So with the sandbox on, the .env rules above also apply to that Python one-liner.

A user-level setup in ~/.claude/settings.json:

{
  "permissions": {
    "deny": [
      "Read(//**/.env)",
      "Read(//**/.env.*)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)"
    ]
  },
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false,
    "credentials": {
      "envVars": [
        { "name": "OPENAI_API_KEY", "mode": "deny" },
        { "name": "STRIPE_SECRET_KEY", "mode": "deny" }
      ]
    }
  }
}

allowUnsandboxedCommands: false turns off the escape hatch where Claude retries a failed command outside the sandbox. Without it, that retry prompts you in Manual mode, runs with no prompt in bypassPermissions mode, and goes to the classifier in auto mode.
credentials.envVars with "mode": "deny" unsets those variables before each sandboxed command runs. There's no built-in credential list, so name the ones you have. To strip credentials from every subprocess (Bash, hooks, stdio MCP servers), set CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 (env vars docs).
Hooks, MCP servers and status-line commands run outside the sandbox with your full access, so review what you install.
On Linux and WSL2, the sandbox docs warn that a wildcard placed right after the filesystem root (their example: /**/*.pem) blocks nothing at the sandbox level. The user-level //**/.env rules still guard Claude's file tools, but rely on the project-level rules, which are anchored in the project, for the sandbox, and test them.

Check it: run /permissions to see your deny rules and which file each came from. Then ask Claude to show you the contents of .env, and to run a one-line script that prints it. Both should fail.

Cursor: .cursorignore, plus a hook for the terminal

1. Ignore the files

Per the ignore file docs, files in .cursorignore are blocked from Agent, Tab and @-mention references. It uses gitignore syntax, including ! to re-include a file:

# .cursorignore  (gitignore syntax)
.env
.env.*
!.env.example
*.pem
*.key

To cover every project, add the same patterns (**/.env, **/.env.*, **/*.pem, **/*.key) to the global ignore list in your user settings. The docs note it's empty by default.

Don't skip this because the docs also list .env* in Cursor's default ignore list. In a forum thread (March 2026), a Cursor team member explained that .gitignore and the default ignore list applied to indexing, not to the agent's Read tool or Tab, and pointed to .cursorignore as the control for agent access. An explicit entry works either way.

2. Cover the terminal with a hook

The same docs say the terminal and MCP tools used by Agent can't honor .cursorignore, so cat .env in a shell command still works. The agent security docs add that terminal commands need your approval by default. If you've allowlisted commands or use a run mode that approves them for you, add a beforeShellExecution hook. Cursor runs it before each shell command and accepts allow, deny or ask.

.cursor/hooks.json in the project:

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": ".cursor/hooks/block-secrets.py",
        "matcher": "\\.env|\\.pem|\\.key|id_rsa|id_ed25519",
        "failClosed": true
      }
    ]
  }
}

The matcher is a regex tested against the full command string, so the hook only runs for commands that mention a secret-looking name. Every other command never reaches it and keeps its normal approval flow. failClosed: true blocks the command if the script crashes or times out. Without it, Cursor lets the command through on those failures.

.cursor/hooks/block-secrets.py (run chmod +x on it; project hooks run from the project root):

#!/usr/bin/env python3
"""Cursor beforeShellExecution hook: deny shell commands that name a secrets file."""
import json, re, sys

cmd = json.load(sys.stdin).get("command", "")
# .env, .env.local, config/.env.production, *.pem, *.key, id_rsa, id_ed25519
SECRET = re.compile(r"(?<![\w.-])(\.env(\.[\w-]+)*|[\w.-]+\.(pem|key)|id_(rsa|ed25519))(?![\w.-])")
SAFE = {".env.example", ".env.sample", ".env.template"}
hits = [m.group(0) for m in SECRET.finditer(cmd) if m.group(0) not in SAFE]

if hits:
    print(json.dumps({
        "permission": "deny",
        "user_message": f"Blocked: command touches {', '.join(sorted(set(hits)))}",
        "agent_message": "That command reads or writes a secrets file, which is blocked. Use .env.example "
                         "for variable names and ask the user for anything else you need.",
    }))
else:
    print(json.dumps({"permission": "ask"}))  # no secret named: leave the decision to Cursor's normal approval

It denies the command when it names .env, .env.local, config/.env.production, a .pem or .key file, or an SSH key. .env.example and lookalikes such as .envrc fall through to ask, which hands the decision back to Cursor's normal approval. Writing to .env (cp .env.example .env) is denied too, so do that step yourself. We tested the script on 13 sample commands with Python 3, using the input format from the hooks reference, but not inside Cursor itself. Watch the Hooks output channel the first time it fires. On Windows, Cursor runs hook commands through PowerShell, so the shebang line won't work there. Change the command to call python explicitly.

It's a text match, so it has the same blind spot as Claude Code's deny rules: a script that opens .env without naming it in the command isn't caught. Treat it as a guard against the common case, not a boundary.

Codex: a permission profile with deny globs

Codex enforces file access with its sandbox, and the permission profile docs describe how to deny reads inside a writable workspace. Profiles are marked beta. Put this in ~/.codex/config.toml:

# ~/.codex/config.toml
default_permissions = "no-secrets"

[shell_environment_policy]
ignore_default_excludes = false   # drop env vars whose names contain KEY, SECRET or TOKEN

[permissions.no-secrets]
description = "Workspace writes, no .env or key files"
extends = ":workspace"

[permissions.no-secrets.filesystem]
glob_scan_max_depth = 4
"~/.ssh" = "deny"

[permissions.no-secrets.filesystem.":workspace_roots"]
"**/.env" = "deny"
"**/.env.*" = "deny"
"**/*.pem" = "deny"
"**/*.key" = "deny"

extends = ":workspace" keeps the built-in workspace profile (writes in the workspace, with .git, .agents, .codex and .aws kept read-only) and adds your rules. deny blocks reads and writes and wins over broader read or write entries.
On Linux, WSL and native Windows, an unbounded ** deny glob needs glob_scan_max_depth. Matches are listed when each sandboxed process starts, so a long-running process (a dev server, a watcher) can read a matching file created after it started.
.env.* also matches .env.example. The docs say read and write globs are less portable than deny globs, so rather than try to reopen it, keep the example file under another name such as env.example if Codex needs to see it.
Profiles don't combine with the older settings. If sandbox_mode appears in any loaded config, or you pass --sandbox, Codex uses the old sandbox settings and ignores default_permissions.
Profiles govern the local commands Codex runs in its sandbox. MCP servers, connectors, the browser and commands you approve to run outside the sandbox use their own controls, so don't approve an escalation that reads .env.
shell_environment_policy handles the other leak. Per the advanced config docs, ignore_default_excludes defaults to true, which means Codex does not drop variables named like *KEY*, *SECRET* or *TOKEN* from the commands' environment unless you set it to false.

Check it: start a new session, ask Codex to print .env, and confirm it can't show you the contents.

The fix that doesn't depend on any tool

Every control above has a gap, and they all assume you remembered to set them up on this machine. Make the file less worth stealing:

Keep production secrets off your laptop's working tree. Use development-only keys locally, with low limits and no access to real customer data.
Load real secrets at run time from your platform's secrets store or a secrets manager, not from a file in the repo.
Commit a .env.example with every variable name and no values. The agent gets what it needs to write code without seeing a key.
Rotate any key an agent has printed. Once a value is in a transcript, treat it as exposed.
Watch for copies. Worktree setups often copy .env into each new checkout. Commit .claude/settings.json, .cursorignore and .cursor/hooks.json so every worktree gets them, and keep the Codex profile in ~/.codex/config.toml, where it applies to whatever workspace you open. See parallel agents with git worktrees.

Five-minute checklist

Claude Code: Read(.env), Read(.env.*) and Read(!.env.example) in .claude/settings.json; /sandbox on; strict sandbox mode in user settings.
Cursor: .env and .env.* in .cursorignore and in the global ignore list; the beforeShellExecution hook if any commands run without your approval.
Codex: a :workspace-based profile with .env deny globs, selected with default_permissions; ignore_default_excludes = false.
Keep the "never read or print secrets" line in your always-on rules as the explanation, not the enforcement.
Test each tool by asking it to show you .env. Then rotate anything that ever leaked.

Rules files tell the agent what you want, and settings make it stick. The same split applies to tests and formatting; see why a long CLAUDE.md gets ignored for a Stop hook that blocks "done" while tests fail.

Want the rule side done? The free sampler (no email) includes our always-on security rule (no secrets in code, tests or logs; read them from env and validate at startup) in formats for Claude Code, Codex, Cursor, Windsurf and Copilot. The AI Coding Rules Pack adds a /security-audit skill that checks a diff against that checklist.

FAQ

How do I stop Claude Code from reading my .env file?

Add Read deny rules to .claude/settings.json, for example Read(.env) and Read(.env.*), which match at any depth under the folder you start Claude in. A .claudeignore file has no effect. Deny rules cover Claude's file tools and the Bash commands Claude Code recognizes, such as cat and head, but not a script that opens the file itself, so also turn on the sandbox with /sandbox; Claude Code merges Read deny rules into the sandbox's filesystem rules.

Does Cursor read .env files by default?

Don't rely on the default. The docs list .env* in Cursor's default ignore list, but a Cursor team member explained on the forum that the default list and .gitignore applied to indexing, not to the agent's file reads. Put .env and .env.* in .cursorignore or in the global ignore list. Neither stops the agent's terminal or MCP tools, so add a beforeShellExecution hook for commands that name the file.

How do I block .env files in Codex?

Use a permission profile in ~/.codex/config.toml that extends :workspace and sets a deny glob such as "**/.env" = "deny" under :workspace_roots, then select it with default_permissions. Profiles are beta, don't combine with sandbox_mode, and only govern the local commands Codex runs in its sandbox.

Is .gitignore enough to keep secrets away from an AI coding agent?

No. .gitignore keeps a file out of git, not out of the agent's reach: the agent works on your disk and can open the file anyway. In Cursor, staff described .gitignore as an indexing control. Use each tool's own deny mechanism: Read deny rules in Claude Code, .cursorignore in Cursor, and deny globs in a Codex permission profile.

What's the safest way to keep API keys away from coding agents?

Don't have production keys in the working tree at all. Use development-only keys locally, load real secrets from a secrets manager at run time, commit a .env.example with names but no values, and rotate any key an agent has printed. The tool settings in this article reduce accidents; they aren't a vault.

Sources

Official docs, checked 2026-10-27.

Stale AGENTS.md and CLAUDE.md: why agents follow them, how to catch it

Eliran Kotzero — Wed, 28 Oct 2026 07:12:22 +0000

Originally published on KitQuarry. Written by Eliran Kotzero for KitQuarry.

In short: when AGENTS.md or CLAUDE.md disagrees with the code, coding agents tend to believe the file. Add one precedence line to your user-level instructions ("when docs and code disagree, follow the existing code and tell me"), put a short check in CI that fails when a path, script or import in those files no longer exists, keep one source of truth with @AGENTS.md, and delete lines the agent doesn't need.

Why a stale instruction file is worse than none

An instruction file is read at the start of every session, so every line in it carries weight. That's the point when the file is right. When it's wrong, the agent starts every task with a confident, outdated description of your project. The usual ways it goes stale are boring:

Renamed paths. "Handlers live in src/handlers/" after you moved them to src/api/. The agent creates new files in the old place, or recreates the folder.
Dead commands. "Run npm run typecheck before finishing" after the script was folded into lint. The agent either fails the step or invents a replacement.
Removed dependencies and old conventions. "Use moment for dates" or "use print() for progress messages" after the codebase moved on. The agent adds the old library back, or rewrites working code to match the file.
Contradictions between files. A root file says one thing and a nested one, or a .claude/rules/ file, says another. The Claude Code docs warn that Claude may then pick one arbitrarily.

What the new research says

This topic took off on X this week because of a paper posted to arXiv on 22 October 2026: "Stale Instruction Files Override the Code in Coding Agents: A One-Sentence Fix" by Xiaonan Xu and Wenjing Wu. The authors built 40 small Python projects where the instruction file asked for one convention and the code used another (for example print versus logging), then had Claude Code and Codex CLI add a feature, 320 runs in total. Their reported results:

Without any fix, 90.1% of the agents' choices followed the stale file.
Claude Code pointed out the conflict in 79 of 80 runs and still followed the file.
Codex CLI rewrote existing code to match the file in 20 of 80 runs, and the project's tests then failed in 17 of them.
One sentence in the user-level instruction file moved code-following from 4.2% to 91.4%, stopped the rewrites, and raised the test pass rate from 89.4% to 100%.

Their explanation: the instruction file reaches the model as an instruction, while the code arrives as tool output, which models are trained to trust less. Keep the scope in mind. These are synthetic Python projects, two agents, and the authors' own runs. Still, the fix costs one line.

Fix 1: add a precedence line

This is the sentence the paper used, word for word:

When a repository's documentation and its existing code disagree, follow the conventions used in the existing code, and in your final reply point out each inconsistency you found between the documentation and the code.

The paper put it in the user-level file, not the project one: ~/.claude/CLAUDE.md for Claude Code and ~/.codex/AGENTS.md for Codex. That's a good default, because it works in every repo without anyone first finding the stale line. Two details:

For Codex, the docs say ~/.codex/AGENTS.override.md is used instead of ~/.codex/AGENTS.md when it exists, so put the line in whichever one you actually use.
For a team, you can add a project version near the top of the shared AGENTS.md, e.g. "The code and package.json scripts are the source of truth; if this file disagrees with them, follow them and tell me". The paper only tested the user-level placement, so treat the project copy as a sensible extra, not a measured result.

One caveat: "code wins" is wrong in the middle of a migration, when the file describes where you're going and the old code is what you're leaving. Say so explicitly: "We're moving from moment to date-fns. New code uses date-fns; don't rewrite old call sites unless asked."

Fix 2: fail CI when the file points at something that's gone

The precedence line covers conventions. Paths and commands can be checked mechanically. This script scans every AGENTS.md and CLAUDE.md in the repo (or the files you pass it) and reports:

code-formatted paths like `src/api/` or `scripts/seed.ts` that don't exist, relative to the file or the repo root;
@path imports outside code spans (Claude Code's import syntax) whose target is missing;
npm run / pnpm / yarn / bun run scripts missing from package.json;
make targets missing from the Makefile.

Save it as scripts/check_agent_docs.py and run it from the repo root. It needs only Python 3, no packages:

#!/usr/bin/env python3
"""Fail when AGENTS.md / CLAUDE.md point at a path, @import, package.json script or make target that is gone."""
import json, pathlib, re, sys

ROOT = pathlib.Path.cwd()
files = [pathlib.Path(a) for a in sys.argv[1:]] or [
    p.relative_to(ROOT) for p in ROOT.rglob("*.md")
    if p.name in ("AGENTS.md", "CLAUDE.md") and not {"node_modules", ".git"} & set(p.parts)]
pkg, mk = ROOT / "package.json", ROOT / "Makefile"
scripts = json.loads(pkg.read_text()).get("scripts", {}) if pkg.exists() else {}
targets = set(re.findall(r"^([\w.-]+):", mk.read_text(), re.M)) if mk.exists() else set()
ALLOW = {".env", ".env.local"}   # fine to be missing: gitignored or created on demand (add PLAN.md etc.)
BUILTIN = {"install", "i", "ci", "add", "remove", "dlx", "exec", "create", "init", "update", "upgrade", "audit"}
EXT = r"\.(md|mdc|json|jsonc|ya?ml|toml|ini|cfg|env|lock|txt|sh|py|js|jsx|ts|tsx|mjs|cjs|go|rs|rb|java|kt|swift|gd|tscn|sql|css|html)$"
PATH = re.compile(r"^(\.{1,2}/)?[\w.-]+(/[\w.-]+)*/?$")
CMD = re.compile(r"\b(?:npm run|npm|pnpm run|pnpm|yarn run|yarn|bun run)\s+([\w:.-]+)")
problems = []

def exists(f, s):
    return (f.parent / s).exists() or (ROOT / s).exists()

for f in files:
    text = f.read_text()
    blocks = re.findall(r"```[^\n]*\n(.*?)```", text, re.S)
    prose = re.sub(r"```.*?```", "", text, flags=re.S)
    spans = [s.strip() for s in re.findall(r"`([^`\n]+)`", prose)]
    for s in spans:                                    # `src/api/`, `scripts/seed.ts`, `.env.example`
        if PATH.match(s) and ("/" in s or re.search(EXT, s)) and s not in ALLOW and not exists(f, s):
            problems.append(f"{f}: path `{s}` does not exist")
    for imp in re.findall(r"(?<![\w`])@([\w./-]*\w)", re.sub(r"`[^`\n]+`", "", prose)):
        if ("/" in imp or "." in imp or imp.isupper()) and not (f.parent / imp).exists():
            problems.append(f"{f}: import @{imp} does not exist")
    for line in spans + [l for b in blocks for l in b.splitlines()]:
        for name in CMD.findall(line):
            if name not in BUILTIN and not name.startswith("-") and name not in scripts:
                problems.append(f"{f}: script `{name}` is not in package.json")
        for name in re.findall(r"\bmake\s+([\w.-]+)", line):
            if name not in targets:
                problems.append(f"{f}: make target `{name}` is not in the Makefile")

print("\n".join(sorted(set(problems))) or f"OK: {len(files)} instruction file(s) checked")
sys.exit(1 if problems else 0)

Given this AGENTS.md, plus a CLAUDE.md that imports a file that was deleted:

# AGENTS.md
- API handlers live in `src/api/`. Old handlers were in `src/handlers/`.
- Setup steps are in `docs/setup.md`.
- Before you finish, run `npm run lint`, `npm test` and `npm run typecheck`.

```bash
pnpm dev
make deploy
```

it prints the following and exits with status 1. We tested it on exactly this sample repo with Python 3.13, then fixed each line and got OK: 2 instruction file(s) checked and exit 0:

$ python3 scripts/check_agent_docs.py
AGENTS.md: make target `deploy` is not in the Makefile
AGENTS.md: path `docs/setup.md` does not exist
AGENTS.md: path `src/handlers/` does not exist
AGENTS.md: script `typecheck` is not in package.json
CLAUDE.md: import @docs/claude-extra.md does not exist
$ echo $?
1

Notice the src/handlers/ result: "Old handlers were in src/handlers/" gets flagged too. That's deliberate. A history note about a path that's gone is just more stale text for the agent to act on; delete it. Paths that are allowed to be missing, like a gitignored .env, go in the ALLOW set at the top. If a line really must mention a missing path, write it without backticks. The script also flags a package name such as @scope/pkg written outside backticks; that's correct, because Claude Code treats any @path outside a code span as an import, in AGENTS.md files it reads too.

Run it as a pre-commit hook:

printf '#!/bin/sh\nexec python3 scripts/check_agent_docs.py\n' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

or as a GitHub Actions job, so it also catches the commit that renames a folder without touching the docs:

name: agent-docs
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: python3 scripts/check_agent_docs.py

It's deliberately simple. It won't catch a wrong convention ("use print()"), a wrong flag, or a script that exists but now does something else. For those, use the precedence line and the review below.

Claude Code also has a built-in review: /doctor prompt-audit (v2.1.283 or later). Per the memory docs, it looks for instructions written for older models, references to files or commands that don't exist, and files that contradict each other, across CLAUDE.md, CLAUDE.local.md, AGENTS.md and the rules, skills and subagents under .claude/. It proposes edits and changes nothing until you say so. Use it for the judgment calls; keep the script for CI, where nothing should depend on a model.

Fix 3: one source of truth, so the copies can't drift

Two copies of the same rules guarantee that one goes stale. Claude Code reads CLAUDE.md, and Codex, Cursor, Windsurf and Copilot read AGENTS.md. Recent Claude Code versions (v2.1.277+) can read AGENTS.md directly, but by default only when there's no CLAUDE.md. The docs' table is clear:

Your repo has	Claude Code reads
`AGENTS.md`, and no `CLAUDE.md` or `CLAUDE.local.md` in the working directory or above it	`AGENTS.md`
`AGENTS.md` and a `CLAUDE.md` or `CLAUDE.local.md` in the working directory or above it	The `CLAUDE.md` files only
A `CLAUDE.md` that imports `AGENTS.md`	`CLAUDE.md`, with `AGENTS.md` included through the import

Note "or above it". A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in any parent folder, say a forgotten one in ~/code/, counts, and Claude then stops reading your AGENTS.md by default. Only ~/.claude/CLAUDE.md, a managed CLAUDE.md and .claude/rules/ files don't count. CLAUDE.md files above the working directory are also loaded at launch, so an old parent-folder file feeds its own stale rules into every session. If AGENTS.md seems ignored, look up the tree first, then check /memory or /context.

The simple fix works in every case: keep the rules in AGENTS.md and make CLAUDE.md a thin file that starts with the import, with Claude-only notes after it:

@AGENTS.md

## Claude Code
- Use plan mode for changes under `src/billing/`.

The docs confirm the import is never read twice, whatever the Project instructions setting. The full pattern is in AGENTS.md vs CLAUDE.md: one source of truth, and the Codex side (discovery order, nested files, the 32 KiB cap) is in AGENTS.md for Codex: a practical template. The checker above also flags the import if someone renames AGENTS.md.

Fix 4: prune, don't just add

Instruction files only grow unless someone deletes lines. A short habit that keeps them honest:

Edit the file in the same commit as the change. Renamed a folder, dropped a script, swapped a library? Update or delete the line now. The CI check makes forgetting fail loudly.
Delete rules the agent already follows. Remove a line, run a typical task in a fresh session, and see if anything changes. If the agent does it anyway (it reads package.json, it follows the existing style), the line was only costing attention.
Don't describe what the code already says. Directory trees, dependency lists and architecture overviews go stale fastest. The Claude Code docs note that /doctor proposes cutting exactly that kind of content and keeping pitfalls, rationale and conventions that differ from tool defaults.
Keep history out. "We used toâ€¦" lines belong in a decisions log or the git history, not the always-loaded file.
Re-read it every few weeks, or run /doctor prompt-audit, and resolve contradictions between root, nested and rules files.

Shorter files also get followed better; the reasons, and how to see what's actually loaded, are in why a long CLAUDE.md gets ignored.

A ten-minute cleanup

Add the precedence sentence to ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md.
Look for stray CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md files above your repos.
Make AGENTS.md the single source and start CLAUDE.md with @AGENTS.md.
Add scripts/check_agent_docs.py, run it, and fix or delete every line it reports.
Wire it into pre-commit and CI.
Delete three lines the agent doesn't need.

Want a lean starting point? The free sampler (no email) ships one AGENTS.md as the single source of truth, a thin CLAUDE.md that imports it, and a /record-decisions skill that appends decisions to a log instead of growing the rules, in formats for Claude Code, Codex, Cursor, Windsurf and Copilot. The AI Coding Rules Pack adds a version-pinning rule (detect versions from package.json and lockfiles before writing code), an agent-safe definition of done and more skills.

FAQ

Why does my coding agent follow an outdated AGENTS.md instead of the code?

The instruction file reaches the model as an instruction, while the code only arrives as the output of a file-reading tool. A paper posted to arXiv in October 2026 argues that models are trained to rank instructions above tool output, so a stale line in the file can beat the code it used to describe, even when the agent notices the conflict.

What line should I add so the agent trusts the code over stale docs?

Something like: when a repository's documentation and its existing code disagree, follow the conventions used in the existing code, and point out each inconsistency in your final reply. Put it in your user-level file (~/.claude/CLAUDE.md for Claude Code, ~/.codex/AGENTS.md for Codex) so it applies to every repo.

How do I check that the paths and commands in AGENTS.md still exist?

Run a small script in CI or as a pre-commit hook. It scans AGENTS.md and CLAUDE.md for code-formatted paths, @imports, package.json scripts and make targets, and fails when one no longer exists. The article includes a tested Python version of about 40 lines.

Does Claude Code read AGENTS.md if I also have a CLAUDE.md?

Not by default. Claude Code reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any folder above it. Your ~/.claude/CLAUDE.md doesn't count. If you keep a CLAUDE.md, start it with @AGENTS.md so both tools read the same rules.

How often should I prune CLAUDE.md or AGENTS.md?

Whenever you change the thing a line describes, and in a quick review every few weeks. Delete rules the agent already follows without being told, rules about code that no longer exists, and anything the agent can read from package.json or the code itself.

Sources

Official docs, checked 2026-10-26.

Parallel agents with git worktrees in Claude Code, Codex and Cursor

Eliran Kotzero — Sun, 25 Oct 2026 07:04:31 +0000

Originally published on KitQuarry. Written by Eliran Kotzero for KitQuarry.

In short: two agents in one checkout overwrite each other's work. Give each agent its own git worktree: a separate folder on its own branch that shares one history. Claude Code, Codex and Cursor can all create worktrees for you. What they don't do is make a fresh checkout runnable or decide how the work fits back together, so set up .env and dependencies per worktree, split tasks so they touch different files, and run the full test suite on the merged result.

Why parallel agents in one folder go wrong

An agent that edits files, runs the build and reads the test output assumes nobody else is changing the folder. Run a second agent in the same checkout and each one sees the other's half-finished edits. Tests fail for reasons neither agent caused, and one agent "fixes" the other's work. Separate terminals or chat tabs don't help, because the files are still shared.

A git worktree fixes the file problem. In the Codex docs' words, each worktree "has its own copy of every file in your repo but they all share the same metadata (.git folder) about commits, branches, etc." Commits made in one worktree are visible from the others straight away, because they live in the same repository. The working files are not shared.

What a worktree does and doesn't isolate

Separate per worktree	Still shared
Tracked files and uncommitted edits	Commits, branches and remotes (one `.git`)
The checked-out branch: git allows a branch in only one worktree at a time	Anything outside the folder: ports, local databases, caches, services
Build output and installed dependencies, once you install them there	Nothing in the repo is copied that git ignores, so `.env` and `node_modules` start missing

Two things on the right trip people up in the first week:

Ignored files. A new worktree is a fresh checkout. The Claude Code docs say untracked files like .env "are not present", and the Codex troubleshooting page lists "code doesn't run on a worktree" with the same cause. Each tool has a fix, covered below.
Things outside the folder. Two dev servers still want the same port, and two agents running migrations still hit the same local database. The Codex docs suggest handing a chat back to your main checkout when you "can run only one instance of your app". Otherwise, give each worktree its own port or database in its environment file.

Claude Code: `claude --worktree`

From the worktrees guide: pass --worktree (or -w) with a name, and Claude Code creates the worktree under .claude/worktrees/<name>/ on a new branch called worktree-<name>. Run the same command with another name in a second terminal for a second isolated session. The repository needs at least one commit first (common workflows).

# terminal 1
claude --worktree feature-auth

# terminal 2
claude --worktree fix-billing-rounding

# start from a pull request instead (quote the #)
claude --worktree "#1234"

Set it up once per repo:

Ignore the folder. Add .claude/worktrees/ to .gitignore so the worktrees don't show up as untracked files in your main checkout.
Copy ignored files. Add a .worktreeinclude file at the repo root, in .gitignore syntax. Claude Code copies files that match a pattern and are gitignored into every worktree it creates, so tracked files are never duplicated.
Install dependencies. They aren't copied. Ask Claude to install them, or run your setup yourself in the worktree directory.
Pick the base. New worktrees branch from the remote's default branch, usually main. To branch from your current local HEAD (unpushed commits included), set "worktree": {"baseRef": "head"} in settings. It doesn't accept a branch name; for a specific existing branch, create the worktree with git.

# .worktreeinclude
.env
.env.local
config/secrets.json

When you exit, Claude checks the worktree. If it's clean, an unnamed session's worktree and branch are removed automatically, and a named session asks first. If it has changes or new commits, Claude asks whether to keep or remove it. Keep it and you can come back with the claude --worktree <name> --resume command Claude Code prints on exit. Non-interactive -p runs aren't cleaned up, so remove those with git worktree remove.

Inside one session you can also isolate subagents. Ask Claude to "use worktrees for your agents", or add isolation: worktree to a custom subagent's frontmatter in .claude/agents/. Each subagent gets a temporary worktree, removed automatically if it finishes without changes. One detail from the docs: such a subagent takes its instruction files from the main conversation, not from its worktree, so a CLAUDE.md that differs on the worktree's branch doesn't apply to it.

Some things carry across worktrees of the same repository: on most setups, "Yes, and don't ask again" Bash approvals are saved to the main checkout's .claude/settings.local.json, and project-scope plugins load in every worktree. While a session is isolated, Claude Code blocks file edits and git commands aimed at the main checkout.

Codex: Worktree mode in the ChatGPT desktop app

The Codex worktrees docs describe this for Codex in the ChatGPT desktop app (and the mobile app controlling a connected computer):

In a new chat, select Worktree under the composer, and optionally a local environment to run setup scripts.
Choose the starting branch: main, a feature branch, or your current branch with unstaged changes, which Codex applies to the worktree.
Submit the prompt. Codex creates the worktree in $CODEX_HOME/worktrees in a detached HEAD state, so several worktrees don't create a pile of branches.
When it's done, either click Create branch here to commit, push and open a pull request from the worktree, or Hand off the chat to Local to test it in your usual checkout.

Setup works in two parts. Local environments hold setup scripts (for example npm install and npm run build) that run automatically when Codex creates a worktree. The configuration lives in the .codex folder at the project root, so you can commit it for your team. Ignored files go in the same .worktreeinclude file as above, and Codex copies an ignored AGENTS.override.md into managed worktrees on its own. Both copy rules apply to worktrees the desktop app manages, not to ones you create yourself.

By default Codex keeps your 15 most recent managed worktrees. It doesn't delete one tied to a pinned chat, a chat still in progress, or a permanent worktree, and it saves a snapshot before deleting one so you can restore it from the chat.

Using the Codex CLI? The docs above cover the app. In the terminal, make the worktree with git (next section) and start Codex in it, for example codex --cd ../app-auth. Your committed AGENTS.md is part of every worktree, so Codex loads the same instructions there.

Cursor: `/worktree`, `/best-of-n` and the Agents Window

Per Cursor's worktrees docs, the UI for worktrees is in the Agents Window: start or move an agent into a worktree there, then review, commit or open a PR from that checkout, or bring the result back into your main workspace. In the IDE you use commands:

/worktree fix the failing auth tests runs the rest of that chat in a separate checkout.
/apply-worktree brings the changes into your main checkout, and /delete-worktree removes the isolated one.
/best-of-n sonnet,gpt,composer fix the flaky logout test runs the same task on several models, each in its own worktree. It doesn't merge anything; you pick the winner and apply it.

Setup goes in .cursor/worktrees.json, which Cursor checks when it creates a worktree from the Agents Window, the IDE or the Cursor CLI. setup-worktree takes an array of commands or a script path, with setup-worktree-unix and setup-worktree-windows as OS-specific overrides. $ROOT_WORKTREE_PATH points at your main checkout:

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

Cursor advises against symlinking dependencies into the worktree and suggests a fast package manager such as pnpm, bun or uv instead. If setup fails, open the Output panel and select Worktrees Setup.

Watch the cleanup. Cursor keeps 25 worktrees per machine by default (cursor.worktreeMaxCount, checked every cursor.worktreeCleanupIntervalHours), and the docs say worktrees created outside its manager, for example with git worktree add, "are eligible for deletion". Commit or push anything you want to keep.

Any agent: plain git

For Codex CLI, Copilot, Windsurf or a mix of tools, create the worktrees yourself. Keeping them next to the repo rather than inside it means there's nothing to add to .gitignore:

git worktree add ../app-auth -b agent/auth
git worktree add ../app-billing -b agent/billing
cp .env ../app-auth/ && cp .env ../app-billing/
git worktree list

cd ../app-auth && claude          # terminal 1
cd ../app-billing && codex        # terminal 2

Install dependencies in each folder before you trust any test result there. Two errors you'll meet, both from git itself:

fatal: 'agent/auth' is already used by worktree at 'â€¦/app-auth' when you try to check out a branch that another worktree has. Merge it from main instead (git merge agent/auth doesn't need it checked out), or switch that worktree to another branch first.
git worktree remove refuses a worktree with modified or untracked files. Commit what you need, then add --force. Removing the folder keeps its branch; delete that separately with git branch -d.

Split the work so it merges

Worktrees stop agents from overwriting each other's files. They don't stop two agents from making plans that can't both be true. Git merges text, so a rename on one branch and a new call to the old name on another can merge cleanly and then fail to build. A few habits help:

Give each agent a different area. "Auth middleware" and "billing rounding" merge well. "Refactor the API" and "add an endpoint" don't.
Settle shared contracts first. If two tasks depend on the same type, schema or route, land that change on main before starting them, and base both worktrees on it.
Avoid one shared file that everyone appends to. Translation catalogs, route tables and changelogs are where parallel runs lose entries. Have each agent write its own fragment, then merge them in one step that fails on duplicate or missing keys.
One integrator. You, or one designated session, merge the branches and resolve conflicts. Then run the full suite on the merged result, not just on each branch.
Same rules everywhere. Every worktree reads the committed instruction files, so put the commands and a "done means" section in AGENTS.md, and import it from CLAUDE.md as described in one source of truth. Then a Claude Code worktree and a Codex worktree check their work the same way.

Each parallel task is still a normal session. A short plan file per worktree keeps it on track; see the plan-first workflow.

Cleanup at a glance

Tool	Where worktrees go	Automatic cleanup
Claude Code	`.claude/worktrees/<name>/`	Clean unnamed sessions removed on exit; otherwise it asks. Subagent and background worktrees swept after `cleanupPeriodDays` unless they hold work
Codex (desktop app)	`$CODEX_HOME/worktrees` (change in Settings > Worktrees)	Keeps the 15 most recent managed worktrees by default; snapshot before deletion
Cursor	Cursor's worktree root	Keeps 25 per machine by default; the docs say worktrees made outside its manager can be deleted too
Plain git	Wherever you put them	None. `git worktree remove`, then `git worktree prune` for folders you deleted by hand

Checklist

Make sure the repo has at least one commit and your instruction files are committed.
One task, one worktree, one branch per agent.
List ignored files in .worktreeinclude (Claude Code, Codex app) or copy them in .cursor/worktrees.json (Cursor).
Install dependencies in each worktree; give each dev server its own port.
Split tasks by area, and land shared contracts on main first.
Merge through one integrator, then run the full test suite on the result.
Remove finished worktrees and branches; know your tool's automatic cleanup limit.

Want every worktree to start with the same rules? The free sampler (no email) ships a shared AGENTS.md with a thin CLAUDE.md that imports it, plus /plan-feature and /review-changes for Claude Code, Codex, Cursor, Windsurf and Copilot. The AI Coding Rules Pack adds an agent-safe definition of done and local AGENTS.md examples for risky folders.

FAQ

Can two AI agents work in the same folder at the same time?

They can, but they edit the same files, so one agent's half-finished change lands in the other's build and tests. Give each agent its own git worktree: a separate checkout on its own branch that shares the repository's history. Claude Code (claude --worktree), Codex in the ChatGPT desktop app (Worktree mode) and Cursor (/worktree or the Agents Window) can each create one for you.

Why is my .env missing in the worktree?

A worktree is a fresh checkout, so it only contains tracked files. Gitignored files such as .env or node_modules aren't there. Claude Code and the Codex app copy ignored files listed in a .worktreeinclude file at the repo root; Cursor runs the setup commands in .cursor/worktrees.json, for example cp $ROOT_WORKTREE_PATH/.env .env. Install dependencies in each worktree too.

Why does git say a branch is already used by another worktree?

Git lets a branch be checked out in only one worktree at a time. Check out a different branch in one of them, merge the branch from your main checkout without checking it out, or in Codex use Hand off to move the chat to Local instead.

Does each worktree load my CLAUDE.md or AGENTS.md?

Yes, if the file is committed, because every worktree has its own copy of the tracked files. Edits you make in one worktree don't reach the others until you commit and merge them. One exception: a Claude Code subagent running in its own worktree takes its instruction files from the main conversation. Codex copies an ignored AGENTS.override.md into the worktrees it manages.

How do I clean up old worktrees?

Claude Code offers to remove a worktree when you exit the session and removes clean unnamed ones automatically. The Codex app keeps your 15 most recent managed worktrees by default, and Cursor keeps 25 per machine by default. For worktrees you made yourself, run git worktree list and git worktree remove <path>.

Sources

Official docs, checked 2026-10-22.

Why your long CLAUDE.md gets ignored, and how to fix it

Eliran Kotzero — Wed, 21 Oct 2026 17:14:34 +0000

Originally published on KitQuarry. Written by Eliran Kotzero for KitQuarry.

In short: Claude Code treats CLAUDE.md as context, not enforced configuration. A long file costs context on every session, buries the rules that matter, and tends to hide contradictions. Keep only the facts every session needs (under 200 lines, per Anthropic's docs). Move procedures into skills and file-specific rules into .claude/rules/. Use @imports to organize, knowing they don't save tokens. Then turn "run the tests before you say you're done" into a check Claude can run, and enforce it with a Stop hook.

Why a long CLAUDE.md stops working

The Claude Code memory docs are explicit: CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, "but there's no guarantee of strict compliance, especially for vague or conflicting instructions." Four things make that worse as the file grows:

Length. The docs say to target under 200 lines per CLAUDE.md file: "Longer files consume more context and reduce adherence." Anthropic's best practices are blunter: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!"
Lost rules. Also from the best practices: if Claude keeps doing something you have a rule against, "the file is probably too long and the rule is getting lost."
Contradictions. Claude Code concatenates every CLAUDE.md it finds, plus your rules files, instead of letting one override another. If two instructions disagree, the docs say Claude "may pick one arbitrarily". Long files hide those conflicts.
Vague lines and emphasis inflation. "Test your changes" can't be checked. "Run npm test before committing" can. And if you mark many lines IMPORTANT, none of them stands out. The docs suggest emphasis on one line only.

First, check what actually loaded

/context lists the CLAUDE.md and rules files loaded at launch under Memory files. If a file isn't there, Claude can't see it. CLAUDE.md files in subdirectories don't show up there, because they load on demand when Claude reads or edits a file in that folder.
Length warnings. When a file is over the recommended length, Claude Code warns at startup and in /status. It also warns when several files that are each fine add up past a combined limit. Each CLAUDE.md, rules file and @path import counts as a separate file.
/doctor proposes trims for a checked-in CLAUDE.md. It cuts what Claude can derive from the codebase (directory layouts, dependency lists, architecture overviews) and keeps pitfalls, rationale and non-default conventions.
/doctor prompt-audit (Claude Code v2.1.283 or later) looks for outdated or conflicting instructions across your CLAUDE.md, AGENTS.md, rules and skills. It only reports; nothing changes until you ask Claude to apply the edits.

Fix 1: keep the always-on part short

The docs' rule for CLAUDE.md: "Keep it to facts Claude should hold in every session: build commands, conventions, project layout, 'always do X' rules." The test for every line is Anthropic's: "Would removing this cause Claude to make mistakes?" If not, cut it.

Keep in CLAUDE.md	Cut or move
Commands Claude can't guess (test one file, typecheck, lint)	Anything Claude can learn by reading the code
Conventions that differ from the defaults	Standard language conventions, "write clean code"
Testing instructions and the preferred test runner	Detailed API docs (link to them instead)
Environment quirks and gotchas	File-by-file descriptions, long tutorials, anything that changes often

Here is a complete project CLAUDE.md in that spirit, about 25 lines:

# acme-api: Node 22, Fastify, Postgres

## Commands
- Typecheck: `npm run typecheck`
- One test file: `npx vitest run path/to/file.test.ts`
- Full suite: `npm test` (needs `docker compose up -d db` first)
- Lint and fix: `npm run lint -- --fix`

## Conventions that differ from defaults
- Money is integer cents (`amountCents`), never floats
- Database access only through `src/db/repo/*`, no raw SQL in route handlers
- New env vars must be added to the schema in `src/env.ts`

## Definition of done
- Run `npm run typecheck` and the tests for every file you changed,
  then `npm test`, before you say a task is done
- Report the exact commands you ran and their results.
  If you didn't run something, say so
- Never delete, skip or loosen a test or assertion to get a pass

## Workflows (skills, loaded on demand)
- /release, /db-migration, /fix-issue

<!-- Maintainers: release steps live in .claude/skills/release/SKILL.md -->

That last line is free. Claude Code strips block-level HTML comments from CLAUDE.md before injecting it, so you can leave notes for humans without spending context on them.

Fix 2: move procedures into skills

The memory docs say it directly: "If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead." The skills docs explain why it pays off: "Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it."

A typical offender is a 20-line "How to release" section that every session pays for. As a skill it looks like this. Save it as .claude/skills/release/SKILL.md:

---
name: release
description: Cuts a new release. Bumps the version, updates CHANGELOG.md, tags and pushes. Use only when the user asks to release or publish a version.
disable-model-invocation: true
---
# Release

1. Check the working tree is clean: `git status --porcelain` must print nothing.
2. Run `npm run typecheck` and `npm test`. If anything fails, stop and report.
3. Ask which bump (patch, minor or major) if the user didn't say.
4. Move the "Unreleased" notes in CHANGELOG.md under the new version heading and commit.
5. Run `npm version <bump>`, then `git push --follow-tags`.
6. Report the new version and every command you ran.

Two details matter here. disable-model-invocation: true means only you can start it with /release, which is what you want for anything with side effects, and Claude Code then keeps even the description out of context until you call it. Without that field, the description sits in the skill listing every session and the body loads when the skill is used. Also keep skill bodies concise: once a skill loads, its content stays in the conversation across later turns. For writing descriptions that make a skill fire when it should, see how to write a SKILL.md that actually triggers.

Rules that only matter for some files belong in .claude/rules/ with paths frontmatter. They load when Claude reads or edits a matching file:

---
paths:
  - "src/api/**/*.ts"
---
# API handlers
- Validate every request body with the schema in `src/api/schemas/`
- Return errors with `sendError()` from `src/api/errors.ts`

A rules file without paths loads at launch like CLAUDE.md, so splitting into rules only saves context when you scope them.

If the line isâ€¦	Put it in
Needed in every session	`CLAUDE.md`
Only relevant to some files or folders	`.claude/rules/*.md` with `paths`, or a CLAUDE.md in that folder
A multi-step procedure or reference you need sometimes	A skill in `.claude/skills/<name>/SKILL.md`
Something that must happen every time, no exceptions	A hook
Your personal preference for this repo	`CLAUDE.local.md` (add it to `.gitignore`)

Fix 3: use @imports to organize, not to save tokens

CLAUDE.md can pull in other files with @path/to/file. What the docs say about it:

Relative paths resolve from the file that contains the import, not the working directory. Absolute paths and ~/ paths work too.
Imported files can import others, up to four hops deep.
Imports are expanded and loaded at launch, so they don't reduce context. In the docs' words, imports "help you organize a long file but don't reduce its context cost."
An @path inside backticks or a code block stays literal text, so you can mention a file without importing it.
The first time a project imports a file from outside your working directory, Claude Code asks you to approve it.

# CLAUDE.md
@AGENTS.md

## Claude Code only
- Workflows are skills in .claude/skills: /release, /db-migration
- My personal notes: @~/.claude/acme-api-notes.md

The @AGENTS.md line is the useful one. It keeps one rule file shared with Codex, Cursor and other tools, with Claude-only notes underneath. By default, Claude Code (v2.1.277 or later) reads AGENTS.md on its own only when there's no CLAUDE.md or CLAUDE.local.md in your working directory or above it. Once you have one, import AGENTS.md from it. Details in AGENTS.md vs CLAUDE.md: one source of truth. The imported file counts toward the same budget, so keep it lean too.

Fix 4: make "done" mean the tests passed

Anthropic's best practices put it plainly: "Claude stops when the work looks done. Without a check it can run, 'looks done' is the only signal available." The fix is a check that returns pass or fail (tests, a build, a linter) plus evidence instead of claims: the command Claude ran and what it returned. You can apply it at three levels.

In the prompt: "â€¦then run the tests and fix any failures."
In CLAUDE.md: a short, concrete "Definition of done" with exact commands, like the example above. This is still guidance, not enforcement.
As a deterministic gate: a Stop hook that runs your check and blocks the turn from ending until it passes. The docs also describe a /goal condition that a separate evaluator re-checks after every turn, and verification subagents that give a second opinion.

Here is a Stop hook. Register it in .claude/settings.json (Stop hooks take no matcher):

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/require-tests.sh",
            "timeout": 300
          }
        ]
      }
    ]
  }
}

And the script, .claude/hooks/require-tests.sh (run chmod +x on it; it uses jq):

#!/bin/bash
# Stop hook: don't let Claude finish while the test suite fails.
INPUT=$(cat)

# Already continuing because a Stop hook blocked? Let it stop instead of looping.
# Delete this check for a strict gate.
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi

cd "$CLAUDE_PROJECT_DIR" || exit 0

# No uncommitted changes means nothing to verify (e.g. Claude only answered a question).
if [ -z "$(git status --porcelain)" ]; then
  exit 0
fi

if ! OUTPUT=$(npm test 2>&1); then
  echo "Tests are failing. Fix the code, not the tests, before you finish:" >&2
  echo "$OUTPUT" | tail -n 40 >&2
  exit 2
fi
exit 0

How it behaves, per the hooks guide and reference:

Exit code 2 on a Stop hook prevents Claude from stopping, and Claude receives the stderr text as the reason to continue. Exit 0 lets it stop.
Stop hooks fire whenever Claude finishes responding, not only when a task is complete. That's why the script skips clean trees, and why the check should be fast. Use your quickest meaningful test command.
stop_hook_active is true when Claude is already continuing because of a Stop hook. With the check in place, Claude is pushed back to work once per stop. Without it, Claude Code still ends the turn after eight consecutive blocks; that count resets whenever Claude calls a tool, and CLAUDE_CODE_STOP_HOOK_BLOCK_CAP changes the cap.
Run /hooks to confirm the hook is registered. Test the script by hand first: echo '{"stop_hook_active":false}' | CLAUDE_PROJECT_DIR=$PWD .claude/hooks/require-tests.sh; echo $?.

The same idea covers other "always" rules. A PostToolUse hook on Edit|Write can run your formatter after every edit, and a PreToolUse hook that exits 2 can block edits to protected files. Then those lines can come out of CLAUDE.md entirely. The docs also offer prompt and agent hook types for judgment calls (the agent hook example runs the test suite before Claude stops), but agent hooks are marked experimental, and the docs recommend command hooks for production.

The same principle in Cursor and AGENTS.md

Cursor's rules docs give the same advice: keep rules under 500 lines, split large rules into composable ones, and reference files instead of copying their contents. A rule with alwaysApply: true is applied to every chat session; otherwise the agent gets it through matching globs or decides from its description. So keep always-apply rules for true essentials. Cursor also supports nested AGENTS.md files in subdirectories, which apply when the agent works with files there. For how the formats map onto each other, see Cursor rules vs CLAUDE.md vs AGENTS.md.

A 15-minute cleanup

Run /context and note every memory file that loads at launch.
Count lines: wc -l CLAUDE.md CLAUDE.local.md .claude/CLAUDE.md 2>/dev/null. Aim for under 200 per file.
Ask "would removing this cause a mistake?" for every line. Cut what fails.
Move procedures into skills, file-specific rules into .claude/rules/ with paths, and personal notes into CLAUDE.local.md.
Rewrite vague lines as checkable ones with exact commands and paths.
Run /doctor prompt-audit to find conflicts and stale instructions.
Add the definition of done and the Stop hook.
Start a fresh session and check that Claude's behavior actually changes. Treat CLAUDE.md like code and prune it when things go wrong.

Want this layout ready-made? The free sampler (no email) ships a thin CLAUDE.md that imports a shared AGENTS.md, plus /plan-feature and /review-changes as skills. The AI Coding Rules Pack adds an agent-safe definition-of-done rule, local rules next to risky code and more skills, for Claude Code, Cursor, Codex, Windsurf and Copilot. For the session habits that go with it, read the plan-first workflow.

FAQ

How long should CLAUDE.md be?

Anthropic's Claude Code docs say to target under 200 lines per CLAUDE.md file, because longer files consume more context and reduce adherence. For each line, ask whether removing it would cause Claude to make mistakes. If not, cut it, or move it into a skill or a path-scoped rule.

Do @imports in CLAUDE.md reduce context usage?

No. Imported files are expanded and loaded into context at launch, alongside the CLAUDE.md that imports them. Imports help you organize a long file, but they don't lower its context cost. To load instructions only when needed, use .claude/rules files with paths frontmatter, or skills.

What is the difference between CLAUDE.md, .claude/rules and skills?

CLAUDE.md and rules without paths load at the start of every session. Rules with paths frontmatter load when Claude works with matching files. A skill's description sits in the skill listing, and its full body loads only when you or Claude invoke it. With disable-model-invocation: true, even the description stays out of context until you call the skill.

How do I make Claude Code run tests before it says it's done?

Write a concrete definition of done in CLAUDE.md with the exact test command, and ask Claude to report the commands it ran and their results. For a deterministic gate, add a Stop hook that runs the tests and exits with code 2 when they fail. Claude Code then keeps the conversation going and gives Claude the hook's stderr as the reason to continue.

Why does Claude still ignore a rule after I shortened CLAUDE.md?

Run /context to confirm the file loaded, look for conflicting instructions in other CLAUDE.md files, .claude/rules or ~/.claude, and make the rule specific enough to check. CLAUDE.md is guidance, not enforcement. If something must happen at a fixed point every time, such as after each edit or before Claude finishes, write it as a hook.

Sources

Official docs, checked 2026-10-18.

How to write a Claude Code skill (SKILL.md) that actually triggers

Eliran Kotzero — Sun, 18 Oct 2026 06:07:44 +0000

Originally published on KitQuarry.

In short: a skill triggers on its description, not its body. Say what it does and when to use it, in the third person, using the words people actually type, and put the main use case first. Keep the frontmatter to name and description and the same SKILL.md works in Claude Code, Codex and Cursor. Then test it in a fresh session with prompts that should and shouldn't trigger it.

How an agent decides to use a skill

Skills use progressive disclosure. When a session starts, the agent sees only a listing: each skill's name and description. The body of SKILL.md loads when the skill is invoked, either because you typed its name or because the model decided it fits the task. So when a skill "doesn't work", the problem is usually that listing entry, not the instructions underneath it.

Claude Code cuts each entry's combined description and when_to_use text at 1,536 characters. The whole listing gets about 1% of the context window. When it overflows, Claude Code drops descriptions for the skills you use least, and only their names remain.
Codex gives the initial skills list at most 2% of the context window (8,000 characters if the window size is unknown) and shortens descriptions first when many skills are installed. skills.max_context_tokens changes that budget.
The Agent Skills spec, the open standard all three tools build on, caps description at 1,024 characters.

The practical rule: front-load the key use case and trigger words, and stay under 1,024 characters so the file is valid everywhere.

Where the file goes

Tool	Project skills	Personal skills	Run it yourself
Claude Code	`.claude/skills/<name>/SKILL.md`	`~/.claude/skills/`	`/name`
Codex	`.agents/skills/<name>/SKILL.md`, scanned from the launch directory up to the repo root	`~/.agents/skills/`	`$name`, or pick from `/skills`
Cursor	`.cursor/skills/` or `.agents/skills/` (also reads `.claude/skills/` and `.codex/skills/`)	`~/.cursor/skills/`, `~/.agents/skills/`	Type `/` and the skill name

Name the folder carefully. The spec says name must match the parent folder and use only lowercase letters, digits and single hyphens, up to 64 characters. In Claude Code the folder name (or name) becomes the slash command. Anthropic's authoring guide also reserves the words "anthropic" and "claude" in skill names, so avoid names like claude-helper if you might upload the skill to claude.ai or the API later.

Anatomy of a description that triggers

The model reads descriptions to choose a skill for the current request, sometimes out of dozens. Anthropic's authoring guide and OpenAI's Codex docs give the same advice:

What, then when. One clause on what the skill does, then "Use when..." with concrete situations.
Third person. "Writes tests for..." rather than "I can help you write tests". The description is injected into the system prompt, and Anthropic warns that an inconsistent point of view can cause discovery problems.
The user's words. Include phrasings people actually type ("add tests", "coverage", "this is untested") plus file types and tools (.tsx, pytest, Vitest).
Boundaries. Codex's docs say to explain when the skill should and should not trigger. A short "Not for..." clause stops near-misses.
Front-loaded. If descriptions get shortened, the first sentence is the part that survives.

description: Helps with tests.

description: Writes and runs unit and integration tests for changed code. Use when the user asks to add tests, improve coverage, reproduce a bug with a failing test, or says code is untested. Not for end-to-end browser tests.

A working template

Here is a complete skill. Save it as .claude/skills/write-tests/SKILL.md for Claude Code, or .agents/skills/write-tests/SKILL.md for Codex and Cursor. It uses only the two fields every tool understands.

---
name: write-tests
description: Writes and runs unit and integration tests for changed code. Use when the user asks to add tests, improve coverage, reproduce a bug with a failing test, or says code is untested. Not for end-to-end browser tests.
---
# Write tests

## Steps
1. List what changed: `git diff --name-only HEAD`. If nothing changed, ask which files to cover.
2. Find the test runner and conventions in package.json, pyproject.toml or the existing tests. Match their location, naming and style.
3. For each changed behaviour, write a happy-path test, one edge case and one failure case.
4. Run the new tests first, then the full suite.
5. If a test fails, fix the code or the test. Never delete or weaken an existing assertion to get a pass.

## Report
- Files added or changed
- Cases covered, one line each
- The exact test command you ran and its result

As it grows, keep SKILL.md as the overview and move detail into files it links to directly:

write-tests/
â”œâ”€â”€ SKILL.md          # required: frontmatter + steps
â”œâ”€â”€ references/
â”‚   â””â”€â”€ fixtures.md   # optional: read only when SKILL.md points to it
â””â”€â”€ scripts/
    â””â”€â”€ coverage.sh   # optional: executed, not loaded into context

Why it is shaped this way. The steps are imperative and end in an explicit output, which the Codex docs recommend. The "never weaken an assertion" line is concrete enough to check in review. Long reference material sits one level deep, so it costs no context until it is needed. Anthropic and the spec both recommend keeping SKILL.md under 500 lines.

Make side-effect skills manual-only

Some skills should never fire on their own: committing, deploying, sending messages. Each tool has a switch.

Tool	Only you can invoke it	Only the model can invoke it
Claude Code	`disable-model-invocation: true`	`user-invocable: false`
Cursor	`disable-model-invocation: true`	Not documented
Codex	`allow_implicit_invocation: false` in `agents/openai.yaml`	Not documented

# .claude/skills/commit-work/SKILL.md (Claude Code; Cursor reads the same field)
---
name: commit-work
description: Runs all checks, then stages and commits the current work with a Conventional Commits message. Only when the user explicitly asks to commit.
disable-model-invocation: true
---

# .agents/skills/commit-work/agents/openai.yaml (Codex)
policy:
  allow_implicit_invocation: false

In Claude Code, a skill with disable-model-invocation: true is left out of the model's listing completely, so it also costs no context until you call it.

Claude Code extras, and when to skip them

when_to_use: extra trigger phrases, appended to the description and counted toward the 1,536-character cap.
paths: globs that limit automatic loading to matching files. Cursor supports paths too.
argument-hint and $ARGUMENTS (or $0, $1): arguments, as in /fix-issue 123.
A line like !`git diff HEAD`: dynamic context. Claude Code runs the command and inlines its output before Claude reads the skill.
allowed-tools: pre-approves tools for the turn that invokes the skill. The grant clears when you send your next message, and it doesn't block other tools. Read it before running skills you didn't write.
context: fork: runs the skill in a subagent that can't see your conversation, so the skill must stand on its own.

These fields are Claude Code extensions, not part of the spec. Cursor documents its own small set (paths, disable-model-invocation, metadata and a few display fields), and the Codex docs list only name and description plus agents/openai.yaml. Uploading a skill to claude.ai or the Skills API fails with an "Unexpected key(s)" error if the frontmatter holds anything beyond name, description, license, compatibility, metadata and allowed-tools.

Why a skill doesn't trigger: a checklist

The frontmatter isn't on line 1. Claude Code reads frontmatter only when the opening --- is the file's first line. Otherwise the whole file, markers included, is treated as content.
The YAML doesn't parse. Claude Code still loads the skill, but with no fields set, so /name works while automatic matching has no description to use. An unquoted description containing ": " is a common cause. Wrap it in quotes.
Wrong folder for the tool. Claude Code's documented locations are under .claude/skills; Codex scans .agents/skills. A skill in only one of them is invisible to the other tool.
The description is vague, or it describes the implementation rather than the request.
Too many skills. When the listing overflows its budget, descriptions get dropped or shortened. In Claude Code, /doctor estimates the listing's cost and /skill-doctor flags skills you never use.
It's switched off: disable-model-invocation, a skillOverrides entry in Claude Code settings, or enabled = false under [[skills.config]] in ~/.codex/config.toml.
It's nested. In Claude Code, skills in a .claude/skills folder below where you started load only after Claude reads or edits a file in that subdirectory.

If a skill triggers but Claude stops following it later in the session: Claude Code doesn't re-read SKILL.md on later turns, and after auto-compaction it keeps only the first 5,000 tokens of each invoked skill. Put the most important rules at the top, word them as standing instructions ("run the tests after every edit"), and move anything that must hold every time into a hook.

Test it like code

Start a fresh session. Anthropic's docs point out that leftover context from writing the skill hides gaps in the instructions.
Confirm it is listed. In Claude Code, ask "What skills are available?" or run /skills. In Codex, run /skills. In Cursor, open Customize, then Skills.
Write 3â€“5 prompts that should trigger it and 2â€“3 near-misses that shouldn't. For the template above, "add a Playwright test for checkout" is a good near-miss.
Run each prompt with the skill on and off and compare the results. In Claude Code, set the skill to "off" in skillOverrides for the baseline run.
Validate the frontmatter with claude plugin validate .claude/skills (Claude Code v2.1.233 or later) or skills-ref validate ./write-tests from the spec's reference library.

Tune the description, not the body, until it triggers when it should. If it fires too often, narrow the description or make the skill manual-only.

One source, three tools

Because all three tools follow the same spec, a SKILL.md with just name and description runs everywhere. The catch is duplication. Cursor also reads .claude/skills and .agents/skills, so a repo that carries the same skill in several folders should keep the copies identical, ideally generated from one source. That is how our kits are built: one master source compiled into each tool's native folder and checked by a format validator. For how skills relate to rule files, see Cursor rules vs CLAUDE.md vs AGENTS.md, and for the workflow these skills support, the plan-first workflow.

Want working examples? The free sampler (no email) includes /plan-feature and /review-changes as SKILL.md files for Claude Code and Codex, plus the same workflows for Cursor, Windsurf and Copilot. The Rules Pack adds /fix-bug, /security-audit, /write-tests and a manual-only /commit-work.

FAQ

Do I need both name and description in SKILL.md?

For portability, yes. The Agent Skills spec, Codex and Cursor all require name and description. Claude Code treats every field as optional (it falls back to the folder name and the first non-empty line of the body), but the description is what Claude matches against, so always write one.

Why does my skill run with /name but never trigger on its own?

Usually the description is too vague or doesn't use the words people actually type. Other causes: disable-model-invocation is set, the YAML frontmatter fails to parse (Claude Code then loads the skill with no fields), or so many skills are installed that the listing dropped its description.

Where do Codex skills go, and how do I run one?

Put them in .agents/skills/<name>/SKILL.md. Codex scans .agents/skills in every directory from where you launch it up to the repository root, plus ~/.agents/skills for personal skills. Mention a skill with $name, or pick it from /skills.

Can one SKILL.md work in Claude Code, Codex and Cursor?

Yes, if you stick to the Agent Skills spec fields (name, description, and optionally license, compatibility, metadata, allowed-tools). Copy the same folder to .claude/skills for Claude Code and .agents/skills for Codex. Cursor reads .cursor/skills and .agents/skills, and also .claude/skills and .codex/skills.

How long can a skill description be?

The Agent Skills spec allows up to 1,024 characters. Claude Code cuts the combined description and when_to_use text at 1,536 characters in its listing, and Codex shortens descriptions when many skills are installed. Put the main use case and trigger words in the first sentence.

Sources

Official docs, checked 2026-10-16.

Want ready-made SKILL.md examples to copy? The free sampler is on GitHub: elirankotzero/ai-coding-rules-sampler.

DEV Community: Eliran Kotzero

Hooks in Claude Code, Cursor and Codex: enforce what rules can't

Why rules aren't enough

The same three hooks in each tool

Where hooks live and when they run

Setup: one folder of scripts, three small configs

Hook 1: block risky commands

Hook 2: format what the agent edits

Hook 3: don't let the agent stop while checks fail

Using your Claude Code hooks in Cursor

Why a hook silently does nothing

Hooks are guardrails, not a sandbox

Test a hook before you trust it

A ten-minute setup

FAQ

What's the difference between a rule and a hook?

Do Claude Code hooks work in Cursor?

Does Codex support hooks?

How do I block a command in a Claude Code hook?

Are hooks a security boundary?

Sources

Too many agent skills? What they cost in context and how to prune

How skills load

What actually costs context

How many skills is too many?

Step 1: audit what's installed

Step 2: turn off or remove what you don't use

Step 3: make side-effect skills manual-only

Step 4: consolidate and slim the rest

Step 5: short, trigger-first descriptions

Step 6: scope skills to where they're used

A ten-minute cleanup

FAQ

How many Claude Code skills is too many?

Do installed skills use context even if I never use them?

How do I turn off a skill without deleting it?

How much of the context window can Codex's skill list use?

Should skills be personal or per project?

Sources

One MCP server, three configs: Claude Code, Cursor and Codex

Where each tool looks

The same setup, written three ways

Claude Code: .mcp.json

Cursor: .cursor/mcp.json

Codex: .codex/config.toml

Adding servers from the command line

Which definition wins

Approvals and trust

Keeping three files in sync

Checklist

FAQ

Where does each tool keep project MCP servers?

Can I copy Cursor's mcp.json into Claude Code's .mcp.json?

Does Codex support project-level MCP servers?

How do I keep API keys out of a committed MCP config?

Why does my project MCP server not show up in Claude Code?

Sources

How to stop Claude Code, Cursor and Codex reading your .env file

Why "don't read .env" in your rules isn't enough

Claude Code: Read deny rules, then the sandbox

1. Deny the files

2. Know what deny rules don't cover

3. Turn on the sandbox for shell commands

Cursor: .cursorignore, plus a hook for the terminal

1. Ignore the files

2. Cover the terminal with a hook

Codex: a permission profile with deny globs

The fix that doesn't depend on any tool

Five-minute checklist

FAQ

How do I stop Claude Code from reading my .env file?

Does Cursor read .env files by default?

How do I block .env files in Codex?

Is .gitignore enough to keep secrets away from an AI coding agent?

What's the safest way to keep API keys away from coding agents?

Sources

Stale AGENTS.md and CLAUDE.md: why agents follow them, how to catch it

Why a stale instruction file is worse than none

What the new research says

Fix 1: add a precedence line

Claude Code: `.mcp.json`

Cursor: `.cursor/mcp.json`

Codex: `.codex/config.toml`

Claude Code: `claude --worktree`

Cursor: `/worktree`, `/best-of-n` and the Agents Window