Skip to content

README.md

Latest commit

 

History

History
203 lines (158 loc) · 8.54 KB

README.md

File metadata and controls

203 lines (158 loc) · 8.54 KB
Raw

agentsmd

One source of truth for AI agent instructions — linted, wired, scored.

CI license

Status (2026-09-06): public pre-release. GitHub's latest release is v0.1.0-alpha.2; the published npm package is @daichunghy/agentsmd@0.1.0-alpha.4 — the alpha and latest dist-tags both resolve it, and the v0.1.0-alpha.4 tag matches the published tarball. The repository has 1 star and 1 fork; no external downstream usage is verified.

demo

Install the published alpha (Node.js 18+):

npm install --global @daichunghy/agentsmd@alpha
agentsmd doctor

To verify from source instead:

npm install --save-exact @daichunghy/agentsmd@alpha
npx @daichunghy/agentsmd@alpha doctor

To reproduce the latest GitHub release from source (needs a git repo):

git clone --branch v0.1.0-alpha.2 https://github.com/daichunghy/agentsmd.git
cd agentsmd
npm install
npm run verify
node dist/main.js doctor

Every AI coding agent reads a different instructions file: Codex, Cursor and the Copilot agent read AGENTS.md, Claude Code reads CLAUDE.md, Gemini CLI reads GEMINI.md, Copilot Chat reads .github/copilot-instructions.md. Use two tools and you get four near-identical files that rot in silence — you fix one, the others keep teaching your agents last year's rules.

agentsmd keeps AGENTS.md the single source, then:

  • verifies the wiring — does each tool actually load your source of truth?
  • detects rot — dead paths, removed scripts, sprawl copies, TODO crust
  • guards budgets — the Codex 32 KiB instruction cap, Claude's ~200-line guidance
  • scores instruction health 0–100, explainable, CI-ready

🌟 Features

  • agentsmd init — starter AGENTS.md (and optional config) in a git repo
  • agentsmd doctor — wiring report for Codex / Claude Code / Gemini CLI / Cursor / GitHub Copilot
  • agentsmd lint — 11 deterministic rules (dead paths, dead commands, sprawl duplicates, secrets, TODO rot, budget overflow, …), text or JSON
  • agentsmd sync — generates the minimal wiring: a one-line managed CLAUDE.md stub (@AGENTS.md import), Gemini context.fileName config; never duplicates content, always idempotent
  • agentsmd score — 0–100 with a versioned JSON schema, badge-ready
  • agentsmd mcp — Model Context Protocol (MCP) stdio server exposing doctor, lint, score, and instruction loader directly to Claude Desktop, Cursor, Antigravity, and OpenCode
  • Zero runtime dependencies · TypeScript strict · deterministic output (repeat runs are byte-identical)

🚀 Quick start

node dist/main.js init            # starter AGENTS.md (git repo required)
node dist/main.js doctor          # see what each agent tool reads today
node dist/main.js sync            # wire Claude Code + Gemini CLI to AGENTS.md
node dist/main.js lint            # find rot
node dist/main.js score           # 0–100 instruction health
node dist/main.js mcp             # start MCP stdio server

The published package also works with npx @daichunghy/agentsmd@alpha …. Commands other than --help/--version need a git repository.

init --config also writes agentsmd.config.json when missing. init --force overwrites those files with the starter. sync still never modifies AGENTS.md.

Inside a repo whose only instruction file is AGENTS.md, doctor reports:

codex: native AGENTS.md — chain 1 file(s), 214 byte(s)
cursor: native AGENTS.md — present
copilot: cloud agent reads AGENTS.md natively; chat instructions absent
claude-code: absent
gemini-cli: absent

🔌 Wiring per tool

Tool What agentsmd does
OpenAI Codex Nothing needed — reads AGENTS.md natively (chain + 32 KiB budget verified)
Cursor Nothing needed — native AGENTS.md, nested supported
Copilot agent / code review Nothing needed — reads AGENTS.md natively
Claude Code Generates a managed CLAUDE.md stub containing @AGENTS.md (docs-endorsed import; survives Windows where symlinks need admin)
Gemini CLI Adds "AGENTS.md" to .gemini/settings.json context.fileName
Copilot Chat Optional managed copy (sync --copilot-copy), hash-verified

sync --adopt wraps an existing CLAUDE.md without deleting a single line of your content. Run sync twice — the second run changes nothing.

🧩 Model Context Protocol (MCP)

agentsmd runs as an MCP stdio server to let agents verify and load instructions in real-time.

Add to your claude_desktop_config.json or Cursor / Antigravity MCP settings:

{
  "mcpServers": {
    "agentsmd": {
      "command": "npx",
      "args": ["@daichunghy/agentsmd", "mcp"]
    }
  }
}

Exposes tools:

  • agentsmd_doctor — verify tool instruction wiring
  • agentsmd_lint — check dead paths, dead commands, and instruction sprawl
  • agentsmd_score — instruction health score (0–100) and actionable deductions
  • agentsmd_get_instructions — reads clean repository instructions for the agent

📏 Rules

Rule Severity Catches
dead-path error backtick paths that no longer exist
dead-command error npm run x / make x that is not defined
codex-budget-overflow error instruction chain over 32 KiB (silently truncated by Codex)
stub-broken error edited/missing @AGENTS.md import or tampered managed copy
sprawl-duplicate error another instruction file ≥70% identical to AGENTS.md
secret-like error private keys / long API tokens committed into instructions
claude-unmanaged warning hand-written CLAUDE.md Claude reads instead of your source
gemini-unwired warning Gemini detected but not pointed at AGENTS.md
claude-length-warn warning CLAUDE.md beyond ~200 lines
todo-rot warning TODO/FIXME crust agents act on literally
absolute-path-portability warning /Users/… / C:\… paths that break elsewhere

Severities configurable in agentsmd.config.json; fail-on sets the CI gate.

🤖 GitHub Action

- uses: daichunghy/agentsmd@v0.1.0-alpha.3
  with:
    fail-on: error        # error | warning | never
    badge-write: false    # commit score.json to gh-pages for a badge

No GitHub Marketplace listing. Pin @v0.1.0-alpha.3 or a commit SHA. Annotations on the exact lines, score output, canonical score.json. Optional config input; default is repo-root agentsmd.config.json. when present. See GitHub Action usage for PR checks, a weekly cron example, and pinning notes.

🆚 Existing tools

Capability agents-lint agent-sync aicfg @reaatech kit agentsmd
Stale-path/command lint ✅ — partial partial ✅
Wiring verification (doctor) — — — — ✅
Sprawl (duplicate file) detection — — — — ✅
Content-hash managed copies — — — — ✅
Deterministic score + schema — — — — ✅
Zero-dependency CLI ✅ — — — ✅

🗺️ Roadmap

  • v0.1 — lint / doctor / sync / score / init / Action (this release)
  • v0.2 — registry + leaderboard of AGENTS.md health
  • later — Cursor rules migration, MCP mode

🤝 Contributing

npm run verify must pass (typecheck, build, action bundle, tests, golden fixtures, determinism, parity, process gates). MIT.

Windows notes (npm pack / bin)

On Windows, npm pack installs package bins via .cmd shims. A Unix shebang (#!/usr/bin/env node) in the bin entry is ignored by cmd.exe but honored under Git Bash, WSL, and when Node launches the file directly.

  • Supported: npx <bin>, npm exec -- <bin>, and the generated .cmd shim after npm install -g from the tarball.
  • Limitation: running the raw bin path as a shell script (./bin/foo) requires a Unix-like shell; use node path/to/bin or the npm shim instead.
  • Process test: lint/sync from the packed tarball should be invoked via npm exec / npx so path separators and shims match Windows.