Multi-Agent Context

A CLI that generates agent-specific context files from your Markdown docs, so developers can pick the AI coding agent they prefer—today—and switch as the ecosystem evolves—tomorrow.

Write docs once. Keep your options open across AI agents.

Why this exists

The AI tooling ecosystem moves fast, but project documentation moves (and should move) slower. Teams end up rewriting the same “rules” and onboarding docs to match whichever agent they’re using right now.

There’s a push for a common format (like AGENTS.md) to avoid lock-in, but a lowest-common-denominator standard must stay simple to encourage adoption—often leaving useful vendor-specific features behind (imports, rule metadata, globs, etc.).

Multi-Agent Context keeps your docs as the source of truth and generates the best format for each agent, so you get:

• Developer freedom: use the agent you prefer without rewriting docs
• Future-proofing: your documentation stays ready for new agents/targets
• Better ergonomics: take advantage of each agent’s strengths

Usage

# Generate context files for a target
npx multi-agent-context <target>

# Targets: claude, codex, agents-md, cursor, gemini
npx multi-agent-context claude
npx multi-agent-context codex
npx multi-agent-context cursor

# Use custom config file
npx multi-agent-context claude --config ./custom-config.yml

# Clean generated files
npx multi-agent-context clean           # All targets
npx multi-agent-context clean claude    # Specific target

Supported targets

claude, codex, agents-md, cursor, gemini

Note: codex is separate from agents-md because Codex supports both a root AGENTS.md and per-directory AGENTS.override.md (layered rules), while agents-md uses AGENTS.md in every directory.

How it works

1. Keep your “agent rules” as normal Markdown docs (for example in docs/).
2. Map those docs to rule metadata in .multi-agent-context.yml (descriptions, optional globs, optional output paths).
3. Generate the right files for your chosen agent target.
4. As agents change, your docs don't—just generate a different target.

Working with Multiple Agents

When switching agents or testing alternatives:

• Some targets can coexist when they write different files (e.g. claude + codex).
• Cursor reads both .cursor/rules/ and AGENTS.md if present—so don’t generate cursor and codex/agents-md at the same time.
• Safe option: run npx multi-agent-context clean (or npx multi-agent-context clean <target>) before generating a different target.

Configuration

Create a .multi-agent-context.yml file in your project root:

rules:
  docs/overview.md:
    description: "Project architecture overview"
    autoLoad: true

  docs/automation.md:
    description: "Automation patterns"
    globs:
      - "app/models/automation/**/*.rb"
      - "app/services/automation/**/*.rb"
    paths:
      - "app/models/automation"

  docs/testing.md:
    description: "Testing patterns"
    globs:
      - "spec/**/*"
      - "**/*.spec.ts"
    paths:
      - "spec"
      - "test"

Rule Options

| Option | Description | |--------|-------------| | description | Human-readable description of the rule | | autoLoad | If true, content is automatically loaded in every session. If false (default), content is loaded on-demand based on description | | globs | File patterns that trigger this rule (Cursor only) | | paths | Subdirectories where context files are created. For Cursor, if globs is empty, globs are auto-generated from paths (e.g., src/api becomes src/api/**/*) |

Output by Target

Claude (claude)

Creates CLAUDE.md files with @path references:

# AI Context

@docs/overview.md

## Context-Specific Rules

- Load `docs/automation.md` for **Automation patterns**

Subdirectory files contain just the reference:

@docs/automation.md

Codex (codex)

Creates AGENTS.md at root and AGENTS.override.md in subdirectories with inlined content (Codex doesn't support imports).

Standard AGENTS.md (agents-md)

Generates AGENTS.md in every directory (no AGENTS.override.md).

Cursor (cursor)

Creates .cursor/rules/<name>.mdc files with YAML frontmatter:

---
description: Automation patterns
globs: app/models/automation/**/*.rb,app/services/automation/**/*.rb
---

[Content of docs/automation.md]

Gemini (gemini)

Creates GEMINI.md files with @path references (same format as Claude).

Safe Clean

Generated files include a marker comment:

<!-- generated by multi-agent-context -->

The clean command only deletes files containing this marker, preserving any hand-written context files.

Error Handling

The tool continues on errors and shows a summary:

Multi-Agent Context - Generation Complete

Target: claude

Files created:
  ✓ CLAUDE.md
  ✓ app/models/automation/CLAUDE.md

Issues:
  ⚠ docs/deprecated.md - file not found (skipped)

Summary: 2 files created, 1 issue

License

MIT