agents-md

We need an elegant and scalable vibe coding solution.

The Problem

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

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

The Solution

Split context into organized fragments, then compose:

`bash
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:

`bash
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
- *//.md
- */.
- 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:

`bash
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:
`bash
npm install -g agents-md
`

This avoids npx downloading the package on every commit.

To regenerate the hook (after updating agents-md):
`bash
npx agents-md setup:compose-before-commit
`

To bypass temporarily (not recommended):
`bash
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 / comments |
| truncate | { atChars, strategy } | undefined | Trim oversized outputs |
| limits | { warn/max source/output } | undefined | Size limits and warnings |

$3

- Target routing
-
-
- (relative dir)
- Imports
-
-
- Ordering and metadata
- (higher numbers surface earlier)
- (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 and 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.