agentrel

Drift-detecting compiler and agent-readiness diagnostic for AI tooling configuration files (AGENTS.md, CLAUDE.md, llms.txt).

Status: v0.1 — works end-to-end for the scan / init / install loop. The numeric Drift Score, GitHub Action, landing page, and Cursor / Windsurf / Antigravity skill adapters are on the v0.2+ roadmap.

Why this exists

You're using more than one AI coding agent — Claude Code plus Cursor, or Copilot plus Codex. Each reads instructions from a different markdown file. Over time those files drift apart: AGENTS.md says pnpm test, CLAUDE.md says npm test. A junior dev's AI assistant ends up running the wrong command, or — worse, for a payment app — logging a PAN because one file's "never log card data" rule got dropped.

agentrel keeps the files honest with each other.

Install

npm install -g agentrel
# or use it ad-hoc
npx agentrel scan

Commands

agentrel scan [path]

Scan a repo for drift between AGENTS.md and CLAUDE.md. Default output is plain English with file:line citations; --json emits a stable machine-readable shape for CI / skill use.

$ agentrel scan .
Drift

◆ medium  AGENTS.md says `pnpm test`; CLAUDE.md says `npm test`
  AGENTS.md:3
  CLAUDE.md:3

1 conflict found.

Exit codes: 0 clean, 1 drift detected, 2 config error, 3 unexpected. Stderr always carries a what / why / next-step block when things go wrong — never a raw stack trace.

agentrel init [path] [--force]

Synthesize starter AGENTS.md, CLAUDE.md, and llms.txt from your repo's README.md, package.json (Build / Test / Dev scripts), and openapi.yaml if present. The generated AGENTS.md and CLAUDE.md emit byte-identical intent fences so a rescan immediately reports zero drift.

$ agentrel init .
wrote: AGENTS.md, CLAUDE.md, llms.txt

Without --force, init refuses to overwrite any existing target file and exits 1 — protects manually-tuned files from accidental loss.

agentrel install [path]

Auto-detect IDE config directories (.claude/, .cursor/, .windsurf/, .antigravity/) and copy the AgentRel skill payload. v0.1 ships Claude only; the other three are detected and reported as "coming Week 4+".

$ agentrel install .
detected: Claude Code
installed: .claude/skills/agentrel/SKILL.md, .claude/skills/agentrel/README.md,
           .claude/skills/agentrel/steps/scan.md, .claude/skills/agentrel/steps/init.md

In a TTY environment with no IDE folders, install prompts [c]laude / [s]kip. In CI / non-TTY, the same condition exits 1 with a NoIdeDetectedError.

The Claude Skill

After agentrel install, type /agentrel inside Claude Code. The skill dispatches by intent:

• "scan for drift" / "are my agent files in sync?" → runs agentrel scan --json, summarizes the JSON in plain English with file:line citations and suggested fixes
• "bootstrap agents.md" / "set up agent files" → reads your README + package.json + OpenAPI spec, asks the host LLM to author higher-quality starter files than the deterministic synthesizer, then verifies zero drift via a rescan

Data policy: the L1 CLI has zero network calls and zero telemetry. The L2 Skill uses your host IDE's LLM under Anthropic's data policy. If your repo holds sensitive code, use the CLI directly and skip the Skill.

Exit codes

| Code | Meaning | |---|---| | 0 | Clean — no drift, or operation succeeded | | 1 | Drift detected (scan) · target files already exist (init) · no IDE detected in non-TTY (install) | | 2 | Config error — bad path, malformed input, IO error. Stderr has a what / why / next block | | 3 | Unexpected — please file an issue with the command you ran |

Output contracts

Default — ANSI-colored human output. Honors NO_COLOR and --no-color.

--json — machine-readable, schema-stable:

{
  "schema": "v0",
  "filesScanned": ["AGENTS.md", "CLAUDE.md"],
  "conflicts": [
    {
      "kind": "command",
      "severity": "medium",
      "fileA": { "path": "AGENTS.md", "line": 3 },
      "fileB": { "path": "CLAUDE.md", "line": 3 },
      "description": "AGENTS.md says `pnpm test`; CLAUDE.md says `npm test`",
      "excerpt": { "a": "pnpm test", "b": "npm test" }
    }
  ]
}

The schema field is a stable version identifier — future v1+ schemas add fields, never rename existing ones.

Trust posture

• No network calls in the CLI. The binary imports nothing from node:http, node:https, or fetch.
• No analytics SDKs. No telemetry, no usage pings, no error reporting.
• No postinstall scripts. npm install agentrel runs no code.
• The published tarball ships dist/ + skills/ + LICENSE + NOTICE + this README. Nothing else.

Trust-posture-as-code lint rules (NFR7), Sigstore signing (FR37), and SBOM publication (FR38) target v0.2.

License

Apache-2.0