AGENTS.md context loader
Auto-loads your AGENTS.md so every session starts with full agent context
Reads AGENTS.md from the project root at session start and injects it as additional context. Works seamlessly alongside CLAUDE.md — useful for projects that use the OpenAI Codex / multi-agent AGENTS.md convention to document agent roles, capabilities and coordination rules.
What does the AGENTS.md context loader hook do?
AGENTS.md context loader is a Claude Code SessionStart hook. It fires automatically at that lifecycle event — outside the model, so it can't be skipped or forgotten. Auto-loads your AGENTS.md so every session starts with full agent context.
As a SessionStart hook it runs after the action, reacting to what just happened rather than blocking it. Because it is a deterministic Node.js script, it executes on every matching event without relying on the model to remember — the guarantee that makes agentic workflows safe to automate.
Use cases
- Multi-agent projects using AGENTS.md for role definitions
- Teams migrating from Codex/OpenAI Codex to Claude Code
- Projects with explicit agent coordination rules
Tags
settings.json fragment
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/agents-md-loader.mjs",
"type": "command"
}
]
}
]
}
}Script · .claude/hooks/agents-md-loader.mjs
#!/usr/bin/env node
// @hookstack session-start-agents-md
// Charge AGENTS.md comme contexte supplémentaire au démarrage de session (SessionStart)
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
export function run(
_input,
{
projectDir = process.env.CLAUDE_PROJECT_DIR,
readFile = readFileSync,
fileExists = existsSync,
} = {},
) {
if (!projectDir) return null;
const agentsPath = join(projectDir, "AGENTS.md");
if (!fileExists(agentsPath)) return null;
const content = readFile(agentsPath, "utf8");
if (!content.trim()) return null;
return {
hookSpecificOutput: {
hookEventName: "SessionStart",
additionalContext: content,
},
};
}
/* v8 ignore next 5 */
if (process.argv[1] === fileURLToPath(import.meta.url)) {
const input = JSON.parse(readFileSync(0, "utf8"));
const result = run(input);
if (result) process.stdout.write(JSON.stringify(result));
}