# Agentfile > Find what is wrong with the AI agent configuration your repository already has. - **Type:** MCP server - **Install:** `agentstack add mcp-dennishavermans-agentfile` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [dennishavermans](https://agentstack.voostack.com/s/dennishavermans) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [dennishavermans](https://github.com/dennishavermans) - **Source:** https://github.com/dennishavermans/agentfile - **Website:** https://www.npmjs.com/package/@agentfile/cli ## Install ```sh agentstack add mcp-dennishavermans-agentfile ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # agentfile > Find what is wrong with the AI agent configuration your repository already has. Your team uses Claude Code, Copilot, Cursor, Codex — each with its own instruction file, in its own format, in its own place. Nobody reads all of them at once, so they drift, contradict each other, and quietly cost context in every session. `agentfile` reads them as they are and tells you what is wrong. ```bash npx @agentfile/cli doctor ``` No setup. No file to adopt first. Nothing written to disk. **Nothing it finds is ever executed** — hooks, skills, commands and MCP configuration are read as text, and a clean result says "no pattern matched", never "this is safe". --- ## The problem The same rule, maintained in four places, drifting apart: ``` AGENTS.md ← the one that is current CLAUDE.md ← a copy, edited last month .github/copilot-instructions.md ← a copy, probably out of date .cursor/rules/main.mdc ← different format, different rules ``` Symlinks solve the copying. They do not tell you that two of these disagree about the package manager, that a hook points at a script nobody committed, that a `.mcp.json` server will silently fail to load, or that 10,000 tokens load into every session before anyone types a word. --- ## What it does Nine questions, one command each. Run them in this order the first time: ```bash npx @agentfile/cli doctor # what is here, and what is wrong with it npx @agentfile/cli context src/api.ts # which configuration applies here, and why npx @agentfile/cli audit # what a hook, skill or MCP server could do npx @agentfile/cli adopt # plan a single source of truth ``` Then, once it is part of the build: ```bash npx @agentfile/cli check # fast enough for a pre-commit hook npx @agentfile/cli validate --strict # every layer, in CI npx @agentfile/cli lint # drifted copies, duplication, context cost npx @agentfile/cli compile --check # generated files still match their source npx @agentfile/cli eval # did the agent actually comply ``` Everything is deterministic: no model, no network, same tree in, same findings out. Every finding carries a stable code, a location, why it matters, and what to do about it. --- ## How it works agentfile reads whatever is there, normalises it into one representation with full provenance, and answers every question from that: ``` AGENTS.md, CLAUDE.md, .cursorrules ┐ .claude/{rules,skills,agents,commands}/ │ .cursor/{rules,commands}/ ├─→ one normalized model ─→ doctor .github/copilot-instructions.md │ every node knows check .github/instructions/, .agents/skills/ │ its file, line, lint .claude/settings.json, .mcp.json ┘ platform and scope audit context compile ``` Because there is one resolver, `context` and `compile` cannot disagree about what applies where. If you would rather keep one source and generate the rest, `adopt` plans that and `compile` maintains it. That is a choice, not a prerequisite. --- ## Getting started Point it at any repository: ```bash npx @agentfile/cli doctor ``` It needs nothing from you. If it finds nothing, it says what it looked for. --- ## Installation ```bash npm install --save-dev @agentfile/cli ``` Add to `package.json`: ```json { "scripts": { "ai:check": "agentfile check", "ai:validate": "agentfile validate --strict" } } ``` > **Requires Node.js >=22.0.0.** The local dashboard is a separate install, because it ships an HTTP server most projects never want: `npm install --save-dev @agentfile/ui`. --- ## Documentation - [Diagnostic codes](docs/diagnostics.md) — every `AGFxxx`, what it means, and how to configure it - [What is stable](docs/stability.md) — what CI and editors may depend on - [Moving to v2](docs/migration-v2.md) — nothing you have breaks; here is what is new - [Security](SECURITY.md) — what agentfile promises about execution, and what it does not promise about safety - [Contributing](CONTRIBUTING.md) — the rules the code follows, and why --- ## Commands ### `npx @agentfile/cli doctor` Analyses the AI agent configuration your repository already has — no setup required, nothing written to disk. ```bash npx @agentfile/cli doctor npx @agentfile/cli doctor --verbose # list every file found npx @agentfile/cli doctor --format json # machine-readable, for CI ``` It reads `AGENTS.md`, `CLAUDE.md`, `.claude/rules/`, `.claude/skills/`, `.claude/agents/`, `.claude/commands/`, `.cursor/rules/`, `.cursor/commands/`, `.github/copilot-instructions.md`, `.github/instructions/`, and `.mcp.json`, then reports: - what configuration exists, per platform, and where it lives - how much context loads into **every** session (an estimate, clearly labelled) - rules duplicated across platforms — the drift the rest of agentfile prevents - skills whose description is too thin for an agent to route on - misconfigurations such as an MCP server that will silently fail to load, or an instruction file importing a path that does not exist `doctor` runs no model, makes no network calls, and never executes a hook, script, or MCP command it finds. It exits non-zero on errors, so it can gate CI. ### `npx @agentfile/cli adopt` Proposes a single source of truth for the configuration you already have, and shows the plan before touching anything. ```bash npx @agentfile/cli adopt # plan only — writes nothing npx @agentfile/cli adopt --apply # carry it out, after confirming npx @agentfile/cli adopt --source claude # consolidate into CLAUDE.md instead ``` Adoption happens in two phases, and the order is not cosmetic. A compiler never carries a target's own file into that target, so generating `CLAUDE.md` while `CLAUDE.md` still holds text nothing else has would lose that text. So: 1. **Consolidate.** Everything every platform says is gathered into one file — `AGENTS.md` by default, because it is the cross-tool standard — which stays hand-written. Bodies are appended whole under a heading naming where they came from: nothing is rewritten, reordered, or summarised, and a file the source already says everything from is skipped rather than copied again. 2. **Generate.** The other platforms' files become compiler output of that source. Nothing is written without `--apply`, and `--apply` confirms first. A hand-written file is overwritten only once its own text is already in the source — anything else is still refused, exactly as `compile` refuses it. Skills, subagents, commands, hooks, MCP servers and permission rules are left alone, and the plan says so rather than leaving you to notice. Asking `compile` to do both phases at once is reported as `AGF205`: with two hand-written targets each becomes the other's source, and under `--force` their contents swap. ### `npx @agentfile/cli rule [code]` What a diagnostic code means, from the same registry that produces it. ```bash npx @agentfile/cli rule # every code, grouped by band npx @agentfile/cli rule AGF302 # one code in full ``` ### `npx @agentfile/cli context ` What configuration actually applies to a file — in load order, with the reason for each. ```bash npx @agentfile/cli context src/api/handler.ts npx @agentfile/cli context src/api/handler.ts --excluded # and why the rest did not ``` When an agent behaves unexpectedly, the question is never "what does the configuration say" — it is *which of these nine files reached this request, and which one won*. This answers that: every instruction in load order with its platform and the reason it matched, the rules and skills available there, and the context cost at that path, separating what loads in every session from what is specific to the path. ### `npx @agentfile/cli explain ` The inverse question: where does this piece of configuration come from, and when does it apply? ```bash npx @agentfile/cli explain .cursor/rules/api.mdc npx @agentfile/cli explain deploy # a skill by name npx @agentfile/cli explain "use pnpm" --at src/api/handler.ts ``` A target can be a file path, a skill or subagent name, or part of a rule's text. With `--at`, it answers whether the rule applies to that file, **why or why not**, and what outranks it there. It also names the other files declaring the same thing. ### `npx @agentfile/cli check` Fast deterministic validation, built for pre-commit hooks and editors. A full run takes around 140 ms including Node startup. ```bash npx @agentfile/cli check npx @agentfile/cli check --strict # warnings fail the run npx @agentfile/cli check --format json ``` Runs the structural and resolution checks: files that will not parse, references that point at nothing, the same rule maintained in several places, glob-scoped rules that match no file, and rules whose scope differs between platforms. No network, no model, nothing executed. #### Silencing a finding you have already decided about A finding you have reviewed and accepted is silenced with a comment in the file itself, in whatever comment syntax that file already uses: ```markdown ``` `agentfile-disable-next-line` covers the following line, `agentfile-disable-line` its own line, and `agentfile-disable` the whole file. Name no codes and it silences everything on that line. Two things keep this from becoming a way to hide problems. Suppressed findings are **counted, not discarded** — every command says how many it silenced, and `--format json` carries each one with the directive responsible, so `--no-suppressions` is never needed to find out what a repository has chosen not to see. And a directive that silences nothing is reported as `AGF005`, so a suppression cannot quietly outlive the problem it was written for. ### `npx @agentfile/cli lint` Quality analysis — the things that are not wrong but are costing you. ```bash npx @agentfile/cli lint npx @agentfile/cli lint --budget 2000 # tighten the context budget npx @agentfile/cli lint --similarity 0.75 # loosen near-duplicate detection ``` Finds copies of a rule that have **drifted apart** — exact comparison goes quiet at exactly the moment someone edits one copy and not the others — and measures always-loaded context against a budget, naming the largest contributors. Similarity is measured on words, not meaning, and the output says so. For skills, it reports descriptions too thin for an agent to route on, two skills an agent has no basis to choose between, bodies past the size the specification recommends, and frontmatter that will not survive being shared through claude.ai or the Skills API. ### `npx @agentfile/cli validate` Strict validation across every layer. Designed for CI. ```bash npx @agentfile/cli validate npx @agentfile/cli validate --target claude # what would compiling to Claude Code lose? npx @agentfile/cli validate --target all npx @agentfile/cli validate --strict npx @agentfile/cli validate --list-rules # print the rule set ``` With `--target`, it checks the features your configuration uses against what that platform actually supports, and every finding cites the platform's own documentation. Without `--target` it says compatibility was not checked, rather than assuming a target and failing your build over it. It also validates every `SKILL.md` against the [Agent Skills specification](https://agentskills.io/specification) — agentfile validates against that standard rather than inventing a replacement — and statically inspects the scripts a skill bundles against a documented set of risk patterns. **Nothing found in the repository is ever executed**, and a clean result says "no pattern matched", never "this is safe". `ai/contract.yaml` is still validated first and reported exactly as before, and a schema failure is still an immediate exit 1. ### `npx @agentfile/cli audit` Security and trust analysis of hooks, skills, MCP servers, and permission rules. ```bash npx @agentfile/cli audit npx @agentfile/cli audit --all # include informational findings npx @agentfile/cli audit --strict # treat warnings as errors ``` Reads everything as text and executes nothing. Reports risky hook commands, unpinned MCP packages, committed credentials, permission rules that do not grant what they appear to, and prompt-injection indicators — each finding with the reason and, where it applies, the platform documentation that backs it. The output names every surface analysed and every file it could not read, and a clean result says what it means: no pattern matched, **not** "this is safe". ### `npx @agentfile/cli compile` Compiles the normalized configuration into native target files. ```bash npx @agentfile/cli compile --target claude cursor # from whatever your source of truth is npx @agentfile/cli compile --target agents-md --check # CI: exit 1 on drift, writes nothing ``` Whatever the repository maintains — AGENTS.md, CLAUDE.md, an agentfile contract — becomes the input; the requested targets get their documented file shapes (AGENTS.md files, CLAUDE.md plus `.claude/rules`, Copilot instruction files, Cursor `.mdc` rules). What a target cannot express is reported (`AGF201`–`AGF203`) instead of silently dropped, output is deterministic and marker-stamped, and a file agentfile does not own is never overwritten without `--force`. ### `npx @agentfile/cli eval` Behavioral evaluation: run an agent task in an isolated workspace, judge the result with deterministic assertions. See [docs/evals.md](docs/evals.md). ```bash npx @agentfile/cli eval --agent "claude -p {prompt}" npx @agentfile/cli eval evals/button.eval.yaml --keep-workspace ``` Nothing executes in your working tree, no agent runs unless you name one, and results are cached against the repository state so unchanged evals are not re-run. Exit codes: 0 passed, 1 assertions failed, 2 harness error. ## Generated-file utilities These work with the manifest that both `compile` and the legacy `sync` write, so they apply to either workflow. ### `npx @agentfile/cli diff` Checks generated files against `.agentfile-manifest.json` and exits non-zero when drift is detected. ```bash npx @agentfile/cli diff npx @agentfile/cli diff --files CLAUDE.md,.github/copilot-instructions.md ``` ### `npx @agentfile/cli clean` Removes generated files that can be regenerated and updates manifest ownership records. ```bash npx @agentfile/cli clean --dry-run npx @agentfile/cli clean ``` ### `npx @agentfile/cli rollback` Restores files from `.agentfile-backup/`. ```bash npx @agentfile/cli rollback --list npx @agentfile/cli rollback --tag migrate-1700000000000 ``` ## Configuring agentfile Everything below is also a flag, and a repository that never writes this file loses nothing. What the file buys is agreement: a pre-commit hook, a CI job and an editor cannot each spell out the same `--budget 2000 --similarity 0.75`, and a tool arguing for one source of truth should not need its own settings in three places. `agentfile.yaml`, at the repository root, every key optional: ```yaml # Directory names to skip, added to the built-in list ignore: - fixtures # Per-code severity. `off` silences a code repository-wide severity: AGF302: info AGF501: error AGF203: off budget: 2000 # always-loaded context budget, in estimated tokens similarity: 0.75 # near-duplicate threshold targets: [claude, copilot] maxWarnings: 0 # fail when warnings exceed this suppressions: true # honour agentfile-disable directives ``` A key nobody recognises is an error, not a shrug — a silently ignored `sevrity:` block is a setting the team believes is applied and is not, which is the failure agentfile exists to report. And a file that do … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [dennishavermans](https://github.com/dennishavermans) - **Source:** [dennishavermans/agentfile](https://github.com/dennishavermans/agentfile) - **License:** MIT - **Homepage:** https://www.npmjs.com/package/@agentfile/cli Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-dennishavermans-agentfile - Seller: https://agentstack.voostack.com/s/dennishavermans - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.