Claude Code Preflight Gate: auto-inject ~/AI/AGENTS.md into every session via SessionStart hook

agents-gate.sh

#!/bin/bash
# Preflight gate: injects ~/AI/AGENTS.md content into every session.
# The agent cannot miss it — the file content is in its context
# before it sees the user's first message.
set -euo pipefail

AGENTS_FILE="$HOME/AI/AGENTS.md"

if [[ ! -f "$AGENTS_FILE" ]]; then
	echo "WARNING: ~/AI/AGENTS.md not found. Global instruction set is missing."
	exit 0
fi

echo "=== PREFLIGHT GATE: ~/AI/AGENTS.md (injected by SessionStart hook) ==="
cat "$AGENTS_FILE"
echo "=== END PREFLIGHT GATE ==="
exit 0

preflight-gate-setup.md

Claude Code Preflight Gate: Auto-inject Global Instructions

Problem

Claude Code's auto-memory (MEMORY.md) is loaded into every session, but it's just text — the agent can read it and still skip the actual instruction files it points to. Instructions without enforcement are suggestions.

Solution

A SessionStart hook that reads your master instruction file and injects its full content into the agent's context before it sees the user's first message. The agent cannot miss it because the text is physically present in its context window.

How It Works

Session starts
    |
    v
Hook fires (SessionStart)
    |
    v
agents-gate.sh reads ~/AI/AGENTS.md
    |
    v
Content injected into agent context
    |
    v
Agent sees all instructions BEFORE user's first message

Setup (2 minutes)

1. Create the hook script

mkdir -p ~/.claude/hooks

Create ~/.claude/hooks/agents-gate.sh:

#!/bin/bash
# Preflight gate: injects ~/AI/AGENTS.md content into every session.
# The agent cannot miss it — the file content is in its context
# before it sees the user's first message.
set -euo pipefail

AGENTS_FILE="$HOME/AI/AGENTS.md"

if [[ ! -f "$AGENTS_FILE" ]]; then
	echo "WARNING: ~/AI/AGENTS.md not found. Global instruction set is missing."
	exit 0
fi

echo "=== PREFLIGHT GATE: ~/AI/AGENTS.md (injected by SessionStart hook) ==="
cat "$AGENTS_FILE"
echo "=== END PREFLIGHT GATE ==="
exit 0

Make it executable:

chmod +x ~/.claude/hooks/agents-gate.sh

2. Register the hook in settings.json

Add the hooks key to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|compact",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/agents-gate.sh",
            "async": false
          }
        ]
      }
    ]
  }
}

If you already have content in settings.json, merge the hooks key alongside your existing keys (permissions, enabledPlugins, etc.).

3. Verify

~/.claude/hooks/agents-gate.sh

Should print the full content of ~/AI/AGENTS.md wrapped in === PREFLIGHT GATE === markers.

Per-machine

This setup is per-machine. Both files live under ~/.claude/ which is local:

File	Purpose
~/.claude/hooks/agents-gate.sh	The script that reads and outputs your instructions
~/.claude/settings.json	Registers the hook with Claude Code
~/AI/AGENTS.md	Your master instruction file (the content being injected)

Repeat the setup on each computer where you run Claude Code. The ~/AI/ repository itself can be synced via git across machines — only the hook wiring in ~/.claude/ needs local setup.

Customisation

• Change AGENTS_FILE path if your instructions live elsewhere.
• The matcher value "startup|resume|compact" means the hook fires on new sessions, resumed sessions, and after context compaction. Remove compact if you don't want re-injection after compaction.
• Add more files to the script if you want multiple files injected (though AGENTS.md should be the single entry point that references everything else).