AsItIs agent tools

Lint CLAUDE.md, AGENTS.md and SKILL.md before your agent reads them. A free Claude Code plugin and MCP server that checks steering files against the vendors' published rules, estimates the tokens they load every session, and flags hidden instructions: comments addressed to the AI, zero-width and bidirectional characters, styled-away text. Also a CLI, a GitHub Action and a pre-commit hook for CI. Read-only, no network, MIT.

Try it in 30 seconds

No install: paste a file into the browser checker. Same linter, runs in your browser tab, nothing is uploaded.

Claude Code: add the marketplace and install the plugin, then run /asitis:md-lint or /asitis:md-budget in a new session.

claude plugin marketplace add Katta041/asitis-agent-tools
claude plugin install asitis@asitis

Other MCP clients: the server is on npm. This is the command your client's MCP config runs (always pin the version). Ready-made configs are under Install.

npx -y @asitis/mcp@0.3.0 --root /absolute/path/to/project

• Lint: frontmatter on line 1 and valid YAML, SKILL.md name and description rules, CLAUDE.md 200 lines, SKILL.md 500 lines, Codex's 32 KiB budget, broken links and @imports, duplicate and contradictory rules.
• Budget: approximate tokens per file and per tool for what loads every session (Claude Code, Codex, Gemini CLI, Cursor, Copilot, Windsurf, Cline).
• Hidden content: HTML and [//]: # comments that read like instructions, invisible Unicode, bidi controls, display:none text.
• Drift: an AGENTS.md that Claude Code skips because a CLAUDE.md shadows it, mirrored files that disagree, Codex's shared 32 KiB budget.
• Skills and agent config (opt-in): skill scripts that download and run code, decode payloads or read credentials; hooks, permissions and MCP servers in .claude/settings.json and .mcp.json. Off unless you pass include.
• Fixes: /asitis:md-fix (or asitis lint --fix-preview) shows mechanical fixes as a diff and applies only what you accept.
• CI: npx -y -p @asitis/mcp@0.3.0 asitis lint, a GitHub Action and a pre-commit hook. See CLI and CI.
• Guard (optional): warns before Claude rewrites a whole markdown file or strips its line endings, trailing spaces or BOM. An accident guard, not a security boundary.
• Read-only: no write tool, no network code, runs under Node's permission model in the plugin.

Words used below: a steering file is any file an AI coding agent reads as instructions (CLAUDE.md, AGENTS.md, SKILL.md, Cursor rules, Copilot instructions, GEMINI.md). An @import is a line such as @docs/style.md that makes Claude Code or Gemini CLI load another file. A baseline is a list of the findings you already have, so CI reports only new ones; each finding is matched by its fingerprint, a hash of the rule, the file and the line's text.

Install

Requires Node 22.13 or later on your PATH.

Claude Code (plugin)

Run the two commands from Try it in 30 seconds. Inside a session, /plugin marketplace add Katta041/asitis-agent-tools and /plugin install asitis@asitis do the same. Start a new session, then run /asitis:md-lint, /asitis:md-budget or /asitis:md-fix.

To update, run claude plugin marketplace update asitis, then claude plugin update asitis@asitis, and restart Claude Code. To remove it, run claude plugin uninstall asitis@asitis.

From a local clone instead:

git clone https://github.com/Katta041/asitis-agent-tools.git
claude plugin marketplace add ./asitis-agent-tools
claude plugin install asitis@asitis

Or try it for one session without installing: claude --plugin-dir ./asitis-agent-tools/plugins/asitis.

The plugin never downloads the server at runtime. See plugins/asitis/README.md for the skill, commands, guard hook and options.

To add only the MCP server to Claude Code, without the skill, commands or hook:

claude mcp add asitis -- npx -y @asitis/mcp@0.3.0 --root "$PWD"

Other MCP clients (Claude Desktop, Cursor, Codex, Gemini CLI)

The server is published on npm as @asitis/mcp. Always pin the version; never use @latest in an agent config. Clients start servers outside your project, so give --root as an absolute path.

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows.

{
  "mcpServers": {
    "asitis": {
      "command": "npx",
      "args": ["-y", "@asitis/mcp@0.3.0", "--root", "/absolute/path/to/project"]
    }
  }
}

Cursor: .cursor/mcp.json in the project (or ~/.cursor/mcp.json).

{
  "mcpServers": {
    "asitis": {
      "command": "npx",
      "args": ["-y", "@asitis/mcp@0.3.0", "--root", "${workspaceFolder}"]
    }
  }
}

If your Cursor version does not expand ${workspaceFolder}, use an absolute path. The server refuses a root that still contains ${...} rather than guessing.

VS Code (Copilot agent mode): .vscode/mcp.json in the project. VS Code uses the servers key.

{
  "servers": {
    "asitis": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@asitis/mcp@0.3.0", "--root", "${workspaceFolder}"]
    }
  }
}

Codex (CLI, IDE and desktop): ~/.codex/config.toml.

[mcp_servers.asitis]
command = "npx"
args = ["-y", "@asitis/mcp@0.3.0", "--root", "/absolute/path/to/project"]

Gemini CLI: .gemini/settings.json in the project (or ~/.gemini/settings.json).

{
  "mcpServers": {
    "asitis": {
      "command": "npx",
      "args": ["-y", "@asitis/mcp@0.3.0", "--root", "/absolute/path/to/project"]
    }
  }
}

If a desktop app cannot find npx, use its full path (run which npx, or where npx on Windows) as the command.

Without npm: the plugin folder in this repository already contains the built, pinned server, so no install or build step is needed.

git clone https://github.com/Katta041/asitis-agent-tools.git
node asitis-agent-tools/plugins/asitis/server/asitis-mcp.mjs --version

In any config above, set command to node and make the absolute path to plugins/asitis/server/asitis-mcp.mjs the first entry in args, followed by --root and your project folder.

Hardened: add Node's permission model so the runtime itself denies writes and child processes (and network access on Node 25 and later). This is what the Claude Code plugin does:

node --permission \
  --allow-fs-read=/absolute/path/to/asitis-agent-tools/plugins/asitis \
  --allow-fs-read=/absolute/path/to/project \
  /absolute/path/to/asitis-agent-tools/plugins/asitis/server/asitis-mcp.mjs --root /absolute/path/to/project

In a client config, command is node and every other word goes in args, in the same order. The @asitis/mcp README shows the same setup for an npm install.

CLI and CI

The package also has an asitis command for scripts, CI and pre-commit. It lints the same way as lint_steering and exits 0 (clean), 1 (findings at or above --fail-on, default error), 2 (something you can fix, one line on stderr) or 3 (a bug in asitis).

npx -y -p @asitis/mcp@0.3.0 asitis lint                      # every steering file under the current folder
npx -y -p @asitis/mcp@0.3.0 asitis lint CLAUDE.md AGENTS.md  # only these files
npx -y -p @asitis/mcp@0.3.0 asitis lint --format sarif > asitis.sarif
npx -y -p @asitis/mcp@0.3.0 asitis lint --fix-preview=safe | git apply   # apply the safe fixes yourself
npx -y -p @asitis/mcp@0.3.0 asitis budget                    # tokens each agent loads every session

Formats: text, json, sarif (the standard report format GitHub code scanning reads) and github (pull request annotations). With github, only errors and warnings become annotations; add --annotate-notes to annotate notes as well. It never writes a file; --fix-preview prints a diff and you decide whether to apply it. asitis lint --help and asitis budget --help list each command's options.

$ npx -y -p @asitis/mcp@0.3.0 asitis lint --include skills
.claude/skills/release/SKILL.md:4:1 warning sec-skill-allowed-tools allowed-tools pre-approves "Bash" (any shell command), so during the turn that invokes this skill those calls go ahead without asking you; scope each entry to the commands it needs, for example Bash(git status *) or WebFetch(domain:docs.example.com)

CLAUDE.md:7:1 warning duplicate-rule Same rule as line 5: "Run `pnpm test` before every commit". Duplicates cost context and drift apart when one is edited; keep one
CLAUDE.md:9:1 warning broken-link Relative link target not found: "docs/api.md". Fix the path or remove the link
CLAUDE.md:11:1 note hidden-comment 1 comment (HTML or [//]: # style) is hidden in rendered views on line 11: "maintainer note: keep this short". It does not read like an instruction to an agent; Claude Code strips it from CLAUDE.md at session start, though its Read tool and other agents still see it, so check that it says what you expect

Linted 2 files: 0 errors, 3 warnings, 1 note.
Skill scan: 1 skill folder, 0 scripts and 0 markdown files read, 0 other files checked for executable headers (0 files in all).

That run exits 0: with the default --fail-on error only errors fail the build. Planted invisible or bidirectional characters, and hidden comments that tell the agent to ignore instructions, hide something, run a command or reach for secrets, are errors, so they fail the build by default. Pass --fail-on warning to fail on warnings too.

GitHub Action. Runs the bundled CLI with no npm install and puts findings on the pull request:

permissions:
  contents: read
jobs:
  asitis:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: 22
      - uses: Katta041/asitis-agent-tools@v0.3.0

pre-commit. Lints only the staged steering files:

repos:
  - repo: https://github.com/Katta041/asitis-agent-tools
    rev: v0.3.0
    hooks:
      - id: asitis-lint

docs/ci.md covers the Action's inputs and SARIF upload, lefthook, husky and GitLab CI. Every flag and exit code is in docs/cli-contract.md.

Config

Put an .asitisrc.json at the project root. Everything is optional:

{
  "$schema": "https://raw.githubusercontent.com/Katta041/asitis-agent-tools/main/packages/mcp/schema/asitisrc-1.json",
  "extends": "recommended",
  "rules": {
    "duplicate-rule": "off",
    "length": ["warning", { "claudeMdLines": 300 }]
  },
  "ignore": ["vendor/**", "examples/**"],
  "overrides": [{ "files": ["docs/**"], "rules": { "contradiction": "off" } }],
  "include": ["skills", "config"]
}

A typo stops the run with the file, line and a suggestion (.asitisrc.json line 2: unknown key "rulez" (did you mean "rules"?)).

To silence one finding, put a comment above it with the rule id: <!-- asitis-disable-next-line duplicate-rule -- the two sections are alternatives -->, or asitis-disable-file for the whole file. The reason after -- is optional; when you give one it is carried into the JSON and SARIF output. The rule id is the word after the severity in each finding, and docs/rules/ lists them all. Security rules (hidden instructions, invisible characters, the sec-* rules) cannot be silenced by a comment, since a comment is exactly what an attacker would add; turn them off in .asitisrc.json or a baseline, where it shows in review. For an existing repo, asitis lint --format json --write-baseline > .asitis-baseline.json and then --baseline .asitis-baseline.json reports only new findings.

Every rule has a page with examples: docs/rules/.

What it checks

Six read-only MCP tools:

Vendor limits, with sources cited in packages/mcp/src/limits.ts:

Every tool is annotated readOnlyHint: true, destructiveHint: false, openWorldHint: false. Tool results carry no link to asitis.app unless you ask for one: with --footer (or ASITIS_MCP_FOOTER=1) the first result of each session ends with one line, Edit these files without rewriting them: https://asitis.app/?ref=mcp, and later results and errors do not repeat it. --no-footer is still accepted and changes nothing. Results are text only. Pass --structured (or set ASITIS_MCP_STRUCTURED=1) to also get each result as JSON in structuredContent, for scripts. It is off by default because Claude Code 2.1 gives the model the JSON instead of the text when both are present, which drops the untrusted-content notice and, for read_markdown, the file text.

Privacy

• The server, the CLI and the guard hook make no network connections and contain no network code. They collect nothing and send nothing.
• They never write, rename or delete a file, and create no temp files. Fixes come back as a diff; applying one is up to you or your assistant.
• By default only markdown steering files, .asitisrc.json and, when a relative link is missing, the root .gitmodules (to tell a submodule that is not checked out from a broken link) are read. Skill scripts are read only when you pass include: ["skills"] (or --include skills), and .claude/settings.json, .mcp.json, .cursor/mcp.json, .vscode/mcp.json and .gemini/settings.json only with include: ["config"], which also reads the name, homepage and repository of the root package.json and pyproject.toml so the project's own MCP server and install script are recognised. .claude/settings.local.json needs config-local. ~/.claude.json is never read. Values from settings files are never echoed: findings name the key, and anything shaped like a secret is redacted.
• The server logs one start-up line to stderr (version and root folder), never file content.
• What your assistant does with results is up to your assistant. Tool results go into the model's context, so they reach whichever AI provider your assistant uses. That is your assistant's network traffic, not ours.

Security model

• Root confinement. Every path is resolved with realpath and must stay inside a root given at start-up. ../ traversal, absolute paths outside the root and symlinks that resolve outside are refused. Symlinks that resolve inside a root are followed, so a CLAUDE.md that links to AGENTS.md or a linked .claude/skills folder is checked where the agent sees it. The filesystem root and your home folder are refused as roots unless you pass --allow-broad-root.
• Markdown only, unless you opt in. By default only .md, .mdc, .markdown, .mdx, .cursorrules, .windsurfrules and .clinerules are read, plus .asitisrc.json (at most 64 KB). include: ["skills"] adds the scripts inside skill folders (up to 1 MB each; other files there are read for their first 4 bytes only, to spot binaries), and include: ["config"] adds the agent settings and MCP config files listed under Privacy. .env*, anything in .git/ or node_modules/, ~/.claude.json and every other file are always refused, including through a symlink that points at them. A repo's .asitisrc.json cannot turn these scans on in the MCP server; only the call (or the CLI flag) can. @imports of other files are counted from their size, never read. Nothing that is read is ever run.
• Bounded work. Files over 16 MB are refused (--max-file-mb), results are capped, every tool call has a 20 s budget, and every scanner is linear time. The tests run 10 MB adversarial inputs (unclosed comments, bracket and backtick storms, long import tokens, invalid UTF-8 and more) through every tool under a 3 s per-call budget.
• Untrusted content. read_markdown labels file content as data, not instructions, and reports hidden instructions and invisible characters up front. This does not stop a model from obeying text it reads; it makes the text visible.
• Pinned server in the plugin. plugins/asitis/server/asitis-mcp.mjs and the CLI next to it are the exact builds of packages/mcp for this version, and server/VERSION records their SHA-256. The Action's copy in action/ is pinned the same way. A test fails if any of them differs from a fresh build.

Report vulnerabilities privately: see SECURITY.md.

Known limits

• Token counts are local approximations (about 4 characters per token for English), not any vendor's tokenizer.
• A hardlink inside the root to a file elsewhere is read like any other file (reads only).
• A symlink swapped into a parent folder between the check and the open is a narrow race; the final path component is opened with O_NOFOLLOW and checked by inode.
• Windows junctions and case-insensitive volumes have had less testing than macOS and Linux.
• The guard hook is an accident guard, not a security boundary: it does not see Bash (sed -i, redirects) or other programs.
• Lint rules follow the vendors' public docs at the time of release. When a vendor changes a limit, the number in limits.ts needs updating.

Options

asitis-mcp --root <folder> [--root <folder>...] [options]

  --root <folder>      Folder the server may read (repeatable). Default: the current folder.
  --footer             Add one line linking to asitis.app to the first result of the session. Off by default.
  --structured         Also return each result as JSON (structuredContent), for scripts. Off by default.
  --max-file-mb <n>    Largest file to analyse, in MB (default 16, max 64).
  --allow-broad-root   Allow your home folder or the filesystem root as the root.
  --version            Print the version.
  --help               Print this help.

ASITIS_MCP_ROOT (folders separated by :, or ; on Windows) ASITIS_MCP_FOOTER=1 and ASITIS_MCP_STRUCTURED=1 work as environment variables. Add a second --root for a memory folder that lives outside the project, for example ~/.claude/projects/<project>/memory.

Mistakes print one line and exit with code 2, for example:

asitis-mcp: Root folder not found: /x. Pass an existing folder with --root.

Develop

npm ci                # install the pinned dev dependencies (there are no install scripts)
npm test              # typecheck, bundle, then the full Vitest suite
npm run sync-plugin   # rebuild the server and CLI and copy them, with their SHA-256, into plugins/asitis/server and action/

See CONTRIBUTING.md. Changes are listed in CHANGELOG.md.

License

MIT. The bundled server includes open-source dependencies under their own licences, listed in plugins/asitis/server/THIRD_PARTY_NOTICES.md.