Agents MD Watcher

Automatically loads and monitors AGENTS.md configuration at session start to enforce project-specific agent behavior rules.

When to Use This Hook

Attach this hook when you need to:

• Ensure Claude Code follows project-specific behavioral guidelines defined in AGENTS.md on every session start
• Maintain cross-platform AI assistant compatibility using the universal AGENTS.md standard
• Automatically inject contextual project rules without requiring manual configuration each session

Consider alternatives when:

• Your project does not use an AGENTS.md file and relies on inline instructions or CLAUDE.md exclusively
• You prefer to load agent behavior configurations through a custom MCP server or startup script with more granular control

Quick Start

Configuration

Copy
name: agents-md-watcher
type: hook
trigger: SessionStart
category: automation

Example Trigger

Copy
claude
# Session starts and hook fires automatically:
# Hook output: Loading AGENTS.md configuration...

Example Output

AGENTS.md Watcher: Configuration loaded successfully
Context injected: 47 lines of agent behavior rules
Project: my-web-app
Rules found: code-style, testing-requirements, commit-conventions
Status: Active for this session

Core Concepts

AGENTS.md Standard Overview

Aspect	Details
File Location	Project root directory as AGENTS.md
Format	Standard Markdown with structured sections for behavior rules
Fallback Behavior	Returns empty context gracefully if AGENTS.md does not exist
Cross-Platform	Compatible with Claude Code, Cursor, Copilot, and other AI assistants
Load Timing	Executed once at session startup before any user interaction
Content Scope	Project-wide rules including code style, testing, and commit conventions

Configuration Loading Workflow

Session Start
    |
    v
[Hook Triggered] --> [Check AGENTS.md exists?]
    |                        |
    |                   No --+--> Return empty context
    |                        |
    |                  Yes --+--> Read file contents
    |                              |
    v                              v
[Parse content] --> [Inject into session context]
    |
    v
[Claude Code operates with rules active]

Configuration

Parameter	Type	Default	Description
file_path	string	AGENTS.md	Path to the agents configuration file relative to project root
timeout	integer	30	Maximum seconds to wait for file read operation to complete
matcher	string	startup|resume	Session events that trigger the configuration load
fallback_context	string	""	Context string to inject when AGENTS.md is not found
verbose	boolean	false	Whether to output detailed logging about loaded configuration sections

Best Practices

1. Keep AGENTS.md focused and concise - Write clear, actionable rules rather than lengthy prose. Each section should address a specific behavioral concern such as code style, testing requirements, or commit message format so the AI can parse and apply rules efficiently.

2. Use structured headings for discoverability - Organize your AGENTS.md with consistent Markdown headings like ## Code Style, ## Testing, and ## Commit Conventions. This structure helps both human developers and AI assistants quickly locate relevant guidelines.

3. Version control your AGENTS.md alongside code - Treat the agents configuration as a first-class project artifact. Review changes to AGENTS.md in pull requests just as you would review code changes to ensure team alignment on behavioral expectations.

4. Test with fresh sessions after updates - After modifying AGENTS.md, start a new Claude Code session to verify the watcher loads the updated rules correctly. Stale session contexts can mask configuration errors until the next restart.

5. Coordinate with CLAUDE.md for layered instructions - Use AGENTS.md for cross-platform, tool-agnostic rules and CLAUDE.md for Claude-specific instructions. The watcher loads AGENTS.md as supplemental context that complements rather than conflicts with existing Claude configuration.

Common Issues

1. AGENTS.md not loading on session start - Verify the file is named exactly AGENTS.md (case-sensitive) and is located in the project root directory. The hook checks os.path.exists('AGENTS.md') from the current working directory, so launching Claude Code from a subdirectory will cause the file to be missed.

2. Hook timeout on large configuration files - If your AGENTS.md exceeds several hundred lines, the default 30-second timeout may not be sufficient on slower systems. Reduce the file size by extracting verbose documentation into separate files and keeping only actionable rules in AGENTS.md.

3. Empty context injected despite file existing - This typically occurs when the file has encoding issues or contains only whitespace. Ensure the file uses UTF-8 encoding and contains at least one non-whitespace line of content. Check file permissions to confirm the hook process can read it.