agents-md

We need an elegant and scalable vibe coding solution.

The Problem

Your project grows, but your AGENTS.md doesn't scale:

project/
├── AGENTS.md     ← single file, static name, impossible to sustain
├── docs/
├── api/

The Solution

Split context into organized fragments, then compose:

project/
├── AGENTS.md                ← auto-generated
├── docs/
│   └── overview.agents.md   ← parsed
├── api/
│   ├── AGENTS.md            ← auto-generated
│   └── endpoints.agents.md  ← parsed
├── agents-md/
│   └── epics/
│       └── epic-one.md      ← parsed
│       └── epic-two.md      ← parsed

One command builds them all:

npx agents-md compose

Compose canonical AGENTS.md from sustainable and elegant file structures. Keep agent context current, composable, and shareable with your human docs. Abstract-context-as-code is what we aim to achieve.

Quick Start

• Initialize: npx agents-md init (creates root AGENTS.md if missing)
• Update fragment files in any of these path formats:
  • **/agents-md/**/*.md
  • **/*.agents.md
  • **/<customised-directories>/*.md
  • **/*.<customised-file-formats>
• Compose: npx agents-md compose

Generated files are owned by agents-md. Don't hand‑edit AGENTS.md — edit source fragments instead.

To have multiple AGENTS.md files for dynamic location-based context, simply add an empty AGENTS.md file in any target directory and rerun bun agents-md compose.

Git Integration

Keep your AGENTS.md files automatically up-to-date with a pre-commit hook:

npx agents-md setup:compose-before-commit

The setup command works with any git repository, regardless of language (JavaScript, Python, Go, Rust, etc.):

What it does:

1. Creates a git hook in .git/hooks/pre-commit
2. Makes it executable automatically
3. Runs npx agents-md compose and stages AGENTS.md files before each commit

Performance tip: For faster commits, install agents-md globally:

npm install -g agents-md

This avoids npx downloading the package on every commit.

To regenerate the hook (after updating agents-md):

npx agents-md setup:compose-before-commit

To bypass temporarily (not recommended):

git commit --no-verify

Why agents-md?

Common pain points today:

• Single, static AGENTS.md per directory; no native "imports" or multi‑file composition.
• No glob‑based includes in AGENTS.md itself; no spec for dynamic content (e.g., JSDoc or config extraction).
• Some tools don't read AGENTS.md;
• Existing options like Ruler assume .ruler/ and don't curate dynamic content outside of those directories.

agents-md fixes them all

• Inputs (fragment files): Accept all Markdown files in **/agents-md/**/*.md and **/*.agents.md. Meanwhile, all file paths are configurable.
• Outputs (AGENTS.md target files): One AGENTS.md per target directory (nearest‑wins by default) with deterministic ordering and source annotations.
• Routing: Markdown directives map fragments to targets.
• Interop: Optional CLAUDE.md can import @AGENTS.md for tools that don't read AGENTS.md.

CLI

• agents-md init
  • Initialize agents-md in this project; creates root AGENTS.md if missing (use compose if already initialized).
• agents-md compose
  • Build outputs from fragments.
• agents-md report [--json]
  • Show outputs, sizes (k chars), token estimates, and warnings (use --json for CI).
• agents-md watch [--verbose]
  • Rebuild on changes silently; use --verbose to log rebuilds.
• agents-md setup:compose-before-commit
  • Setup pre-commit hook to auto-compose AGENTS.md files before each commit (works with any codebase: Node.js, Python, Go, etc.).
• agents-md help|version

Exit codes: 0 success, 1 generic error, 2 invalid config, 4 limit violation.

Configuration

Use agents-md.config.ts (or .js/.mjs) at repo root. Defaults are zero‑config; customize only as needed. See full schema in docs/design.md.

Key options

| Option | Type | Default | Purpose | | --- | --- | --- | --- | | include | string[] | ['**/agents-md/**/*.md','**/*.agents.md'] | Fragment discovery globs | | exclude | string[] | ['**/node_modules/**','**/.git/**'] | Ignore patterns | | includeFiles | (ctx) => boolean | undefined | Advanced per‑file filter | | defaultTarget | 'nearest'|'root' | 'nearest' | Fallback routing behavior | | annotateSources | boolean | true | Wrap fragments with <!-- source: ... priority=n --> / <!-- /source: ... --> comments | | truncate | { atChars, strategy } | undefined | Trim oversized outputs | | limits | { warn/max source/output } | undefined | Size limits and warnings |

Markdown Directives

• Target routing
  • <!-- agents-md: target=nearest -->
  • <!-- agents-md: target=root -->
  • <!-- agents-md: target=../docs --> (relative dir)
• Imports
  • <!-- agents-md: import=@./shared/common.md -->
  • <!-- agents-md: import=@../standards/api.md -->
• Ordering and metadata
  • <!-- agents-md: priority=10 --> (higher numbers surface earlier)
  • <!-- agents-md: title="My Section" --> (optional heading hint)

Rules: keys are comma/space separated (key=value); paths start with @ for Claude Code compatibility; resolution is relative to the fragment file.

Composition Model

• Discovery: collect fragments from include globs.
• Targeting: directive > defaultTarget (nearest).
• Ordering: by priority (descending), then by path (stable and deterministic).
• Annotation: optionally wrap fragments with <!-- source: path --> and <!-- /source: path --> comments.
• Output: write one AGENTS.md per selected target with a generated‑file banner.

Reporting

• Shows: target tree, output sizes, token estimates, source counts, limit status.
• JSON mode: agents-md report --json for CI and tooling.

Interop & Migration

• init moves content from AGENTS.md/CLAUDE.md into fragments, scaffolds config, and creates a root AGENTS.md when absent.
• For Claude Code, create CLAUDE.md with: @AGENTS.md (imports generated content).
• Can be combined with distribution tools (e.g., Ruler) if needed.

FAQ

• Why not hand‑write AGENTS.md? Fragments scale better and enable reuse.
• Do I need more than one AGENTS.md files? No — start with zero‑config and a single root 'AGENTS.md' generated by init or compose.
• Are directives required? No — they only override defaults when needed.

Roadmap

• Official plugin kit (extract JSDoc, TypeScript types, DB schemas).
• Better hot reload support for ecosystem tools (Vite, Bun, etc.).
• MCP for cross-directory reference support.

Credits

• Thanks to OpenAI's AGENTS.md standardization efforts.
• Inspired by Ruler for distribution ideas.