Maintain AGENTS.md once. Sync CLAUDE.md, GEMINI.md, .cursor/rules/*.mdc, .windsurf/rules/*.md, .clinerules/*.md, CONVENTIONS.md automatically.

Why

Every AI coding tool invented its own rules-file format. Eleven of them, last we counted. Maintaining CLAUDE.md + AGENTS.md + .cursorrules + .cursor/rules/*.mdc + .clinerules/*.md + .windsurfrules + .windsurf/rules/*.md + CONVENTIONS.md by hand drifts within weeks. This tool keeps them in sync.

Quickstart

# See what's in this repo
npx @mbeato/agentcontext inspect

# Detect everything, normalize to AGENTS.md, write per-tool shims
npx @mbeato/agentcontext sync --write --shims claude,cursor,cline,windsurf,gemini,aider

# Or convert one direction explicitly
npx @mbeato/agentcontext convert --from cursor-mdc --to agents-md --in .cursor/rules/style.mdc

What gets read and written

Format	Read	Write	Notes
`AGENTS.md`	✓	✓	Canonical hub
`CLAUDE.md`	✓	✓	@-imports resolved (5 hops)
`GEMINI.md`	✓	✓	Code-block-aware @-imports; preserves `## Gemini Added Memories`
`.cursor/rules/*.mdc`	✓	✓	All 4 activation modes (alwaysApply / globs / description / manual)
`.cursorrules`	✓	✗	Read-only — deprecated by Cursor in Agent mode
`.windsurf/rules/*.md`	✓	✓	All 4 triggers; warns on 12K char limit
`.windsurfrules`	✓	✗	Read-only — pre-Wave-8 legacy
`.clinerules` (file)	✓	✗	Read-only — pre-v3.7.0 legacy
`.clinerules/*.md`	✓	✓	Skips reserved subdirs (workflows/, hooks/, skills/)
`CONVENTIONS.md`	✓	✓	Aider community pattern; emits matching `.aider.conf.yml` snippet
`.aider.conf.yml`	partial	✗	Reads `read:` list only — never round-tripped (it's CLI config, not rules)

Library

import { ingest, render, renderMany } from "@mbeato/agentcontext";

const bundle = await ingest("/path/to/repo");
console.log(bundle.detected_formats); // ["agents-md", "claude-md", "cursor-mdc"]
console.log(bundle.rules.length);

const out = renderMany(bundle, ["agents-md", "claude-md", "cursor-mdc"]);
for (const [path, content] of Object.entries(out.files)) {
  console.log(path, content.length);
}
for (const w of out.warnings) console.log(w); // W003, W042, etc.

MCP server

There's a separate package @mbeato/agentcontext-mcp that exposes two MCP tools (read_agent_context, convert_agent_context) for any MCP-aware agent.

// MCP client config
{
  "mcpServers": {
    "agentcontext": {
      "command": "npx",
      "args": ["-y", "@mbeato/agentcontext-mcp"]
    }
  }
}

Hosted endpoint

https://agentsmd.apimesh.xyz — landing + POST /normalize (deploying this week — until then, use the CLI or MCP).

POST /normalize will accept { source_format, content, targets } and return { files, warnings, detected_formats }. Free, rate-limited.

Round-trip guarantee

Lossless pairs (e.g., agents-md ↔ agents-md, cursor-mdc ↔ cursor-mdc, conventions-md ↔ conventions-md) round-trip byte-identical after canonicalization. Lossy directions (e.g., cursor-mdc → agents-md collapses activation modes into prose) emit numbered warnings (W001–W099) so you can grep CI logs.

Status

v0.1.2 — early. Working CLI + MCP + library. Hosted endpoint deploying this week. Not yet: walked-up nested AGENTS.md / CLAUDE.md, .claude/rules/*.md path-scoped rules, GitHub App for auto-PR sync.