Getting Started

Quick start

From a folder that has at least one instruction file (CLAUDE.md, AGENTS.md, .cursorrules, .github/copilot-instructions.md, or GEMINI.md) — no install, no account:

npx @reporails/cli check
# or
uvx --from reporails-cli ails check

First run downloads the model once (~275 MB). The package itself is small; on the first check that needs it, Reporails downloads its analysis model into ~/.reporails/cache/ and prints a Downloading reporails model… banner followed by one line per file fetched. The download lives in your home cache, not the package cache, so it happens once per machine and every later run — including a fresh npx — is silent and offline. A first run needs network access; see Configuration to point the download at a mirror. A CI job starts on a fresh machine every time; see Caching the model in CI so that only the first run downloads it.

You'll see something like this:

Reporails — Diagnostics

  ┌─ Main (1)  4 directive / 3 constraint · 50% prose
  │ CLAUDE.md  4 dir / 3 con · 50% prose
  │   ⚠ L9    Missing directory layout — show the project structure  CORE:C:0035
  │   ⚠ L23   7 of 7 instruction(s) lack effective reinforcement  CORE:C:0053
  │     ... and 19 more
  │     1 misordered · 1 orphan · 1 ambiguous
  │
  └─ 21 findings

  ── Summary ────────────────────────────────────────────────────────

  Quality   7.9 / 10  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░  (1.3s)
  Fix now   16 errors. Start with CORE:C:0053.
  Findings  21 total · -v to list every one
  Agent: Claude
  Level: L4 Delegated

  Scope:
    instructions: 4 directive / 7 prose (50%)
                  3 constraint

Three things to read first:

• Quality — closer to 10 is better. See the Score Guide for what each band means.
• Fix now — the error count and the rule to start with. The Findings total beneath it is the size of the rest.
• Findings list — each row is a rule that fired. Run ails explain CORE:C:0035 (or whichever rule ID) to see what the rule checks for and how to fix it. In supporting terminals the rule IDs in the output are clickable links to their docs page.
• Scope summary — counts of directives, constraints, and prose detected. If a number looks wrong (e.g., zero directives), your instructions are probably written as prose rather than as commands the agent can act on.

Reporails ships in two pieces: the engine (the CLI + MCP server) and the plugin (the ails skill + MCP registration your agent installs natively).

1. Install the engine on your PATH:

uv tool install reporails-cli
# or
npm install -g @reporails/cli

A global npm install stays on the version it installed; ails update prints the npm command that moves it to the latest release. A bare npx @reporails/cli runs the latest release unless a copy is installed globally or in the project, where npx runs that copy.

ails install then ensures the binary is on PATH. After it runs, ails check works from anywhere without the npx / uvx prefix.

2. Add the reporails plugin to your agent. The plugin carries the ails skill and the MCP server; installing it registers both in one step — no per-agent config editing. The per-agent install commands are listed in Agent Support; ails install runs them for Claude Code and Codex and prints the rest. Add --project to install the plugin for the current repository only, shared with collaborators (Codex installs for your user); ails update refreshes the plugin in each agent that has it. What the plugin needs to start is stated there. Without the plugin, ails check in your terminal scores your instruction files, and --heal applies fixes on a Pro account; rewriting them needs the plugin and Pro (/reporails:ails heal in Claude Code).

Configure (optional)

Reporails auto-detects which agent rules to run based on the base config files present in your repo, so most projects need no setup. You may want to pin a default if your repo has multiple agents (CLAUDE.md + .cursorrules + AGENTS.md) and you want to bias toward one of them:

ails config set --global default_agent claude

Per-repo settings, rule thresholds, and rule disables live in .ails/config.yml — see Configuration for the full surface.

Authenticate (optional, free)

The anonymous tier works without an account and is enough to see whether your instructions are working — the full diagnosis, every finding, and the score. Signing in is free and does not change your rate or payload caps — anonymous and signed-in free accounts share the same limits. What an account gives you is an identity (so you can subscribe and manage the subscription); ails check --heal writes fixes on a Pro account only, and an anonymous or free run gets the full diagnosis and no changes. Raising the caps and unlocking the full diagnostic detail (the remedies, and the exact line of each cross-file repetition and topic overlap) is what Pro adds:

ails login    # sign this machine in through your browser
ails logout   # sign this machine out

ails login prints a link and a short code, opens your browser when it can, and finishes when you approve. The link is valid for 30 seconds; when it runs out, run ails login again. One sign-in per machine, good for a year; your plan (Free or Pro) comes from your account, so any machine you sign in on gets it.

See Tiers and Limits for the side-by-side breakdown, and Configuration → Authentication for the credential-storage and CI specifics.

Common follow-ups

• The score is lower than you expected. Run ails check -v to see all findings (the default output may leave some out). Then ails explain CORE:S:0002 (or whichever rule ID) to see the rule body and pass / fail examples. The Score Guide explains what each band means, how per-surface scores roll up, and which rules to start with.
• You disagree with a rule. Browse reporails.com/rules for the rule's intent before deciding, then disable it in .ails/config.yml — see Configuration → Disabling rules.
• You want this in CI. See the GitHub Actions section in the README and Configuration → Authentication for creating an API key on reporails.com/account and wiring it as secrets.REPORAILS_API_KEY.

Useful flags

ails check -v               # verbose — show all findings, not just top per file
ails check -f json          # machine-readable JSON
ails check -f github        # GitHub Actions inline annotations
                            # (text, json and github are the only formats; any
                            #  other value is a usage error)
ails check --strict              # exit code 1 if any finding fires
ails check --agent claude        # only run rules scoped to one agent
ails check CLAUDE.md --heal      # apply the listed fixes to one target (Pro)
ails check CLAUDE.md --fix       # alias for --heal (eslint / ruff convention)
ails check CLAUDE.md --heal --dry-run  # preview fixes without writing (Pro)
ails check --heal --cwd          # with --heal: opt into rewriting the whole project instead of naming a target

--heal needs an explicit target — a path or a capability like skills — or --cwd to opt into rewriting the whole project; a bare ails check --heal exits with an error naming both options. It also needs a Pro account: run ails login with one. Without one (anonymous, or signed in on a free account) the run still prints the full diagnosis, then declines the fix pass with Applying fixes needs a Pro account. and applies nothing. See Tiers and Limits.

The JSON output groups findings under files{path: {findings: [...], count: N}} plus aggregate stats, a notices list of messages about your account and announcements from reporails, and (when present) cross_file blocks — see Configuration → Output format for the full shape, including which fields are tier-conditional.

Focus on one file or capability

The folder you run ails check in is the project. A file or folder inside it is checked as part of that project; a folder outside it is checked as its own project, and a file outside it at its own folder (a file under ~/.claude at ~/.claude). Nothing looks in the folders above for .git, .ails/backbone.yml or an editor or agent folder. When you name a file that is not an instruction file of that project, the check says so and points you to run ails check in the project's folder.

When the whole-repo view is too noisy, name the target. Each positional is capability:name, @capability (all of capability), or a path:

ails check skills:backlog    # focus on .claude/skills/backlog/SKILL.md
ails check rules:git         # focus on .claude/rules/git.md
ails check agents:rule-writer
                             # subagent + any skills its frontmatter preloads
ails check @skills           # listing mode — every skill, one card each
ails check ./CLAUDE.md       # focus on a path
ails check .claude/skills    # focus on a directory — every instruction file under it
ails check skills:backlog @agents  # mix: one skill + all agents

Only the named files are read and checked, so cross-file rules compare them with each other, not with the rest of the project, and checks about the project as a whole (such as whether a main instruction file exists) are skipped. The output uses the same per-file card layout as a whole-project run, narrowed to the named target. Listing mode (ails check <capability> with no name) narrows the same card layout to every file under that capability instead of a single one. Capability names come from the agent's declared file_types: — both singular and plural are accepted.

The whole-repo summary also shows a Top rules (by finding count) block — a fast triage view of which rule classes contribute the most findings across your project.

See a Claude Code session's context

ails xray                      # the newest Claude Code session started in this folder
ails xray --session <id>       # one session by its id
ails xray --no-open            # print the address instead of opening the browser
ails xray --current            # the session of the agent running this command
ails xray --background         # start the page detached, print its address and return

ails xray opens a page on 127.0.0.1 that shows one session as who handed what to whom, in three tabs: Graph, Tool calls and Sources. It opens on the Graph. On the Graph, the agent sits on a timeline that runs top to bottom: what entered its context is on the left (one node per instruction file, rule, skill, memory file or MCP server, at the moment it first loaded), its subagents are cards on the right, joined by an arch that leaves the timeline when the agent launched and returns when it handed its result back, and only hooks stay on the timeline itself. The line's thickness follows the context size, and a compaction narrows it with a marker showing the sizes before and after. A jump rail beside the graph shows where the calls were and scrolls to repeated failures, fan-outs, the selection and the end.

• Hover or focus anything to highlight what it relates to; nothing moves. Click a card to see that agent in the right column: its peak context and estimated cost (each opens a breakdown), everything that was in its context at its peak, adding up to the exact total, its tool calls per tool, the subagents it launched and, for a subagent, what it returned. Press Open to go into that agent in the same layout; the path shows in the address bar and the breadcrumb, so a level can be linked. Esc closes the details, then clears the selection.
• Click a source anywhere to open its details over the graph: its findings, configuration, path patterns or MCP tools, its full text, which agents loaded it and how its cost is estimated. Repeated calls to one MCP server collapse into one round trip per burst.
• The Sources list on the left is the inventory of everything the session could load, the coding agent's own context first, and says what did not happen: listed but never loaded, on disk but never loaded, not recorded in this session, or none configured. Each group shows how many of its items were used and its findings; each item its size, estimated cost and findings. The eye button on a group shows or hides that kind on the graph only. A source's findings page opens with the command that fixes it.
• The Tool calls tab opens full width: the call count and the agent, tool and failed filters on one line (the most-called tools show as buttons and a +N button opens a menu with the rest), a strip with one full-height mark per call in its tool's colour (failed calls in the failure colour), and the table of every call with its time, agent, tool, result size, duration and status. Hovering a mark shows that call's time, tool and label, and a click on a mark opens that call (a click on a gap opens nothing). Clicking a row (or a mark) narrows the table to its time, tool and call (its filters collapse into one button naming the active ones), opens the call's input, result, context at that turn and the instruction files in context beside it, and marks the open call on the strip; the × or Esc closes the details and the table has its full width again. The Sources tab works the same way: it lists every source with the agents that had it, its size and findings at full width, and a click narrows it to the name and kind and opens the source's details beside it.

Open any session

• From a terminal, ails xray opens the newest session of the folder and keeps serving until Ctrl-C, or until it has had no request for 30 minutes; an open page keeps it running (set AILS_XRAY_IDLE_S to another number of seconds, 0 to never stop). It reads the sessions of the folder it runs in, so run it in the folder Claude Code was started in; with none there it exits with code 2 and names the folder. --session <id> opens one by its id. To choose without an id, open the session button in the page header: it lists the folder's recent sessions with their start time, length and subagent count, a "first prompt" toggle shows a session's first prompt only when clicked, and picking a session opens it on the same page. --session and --current cannot be combined, and an id that is not a session of the folder is refused.
• From inside an agent, ask for the x-ray and the page opens in the background, so the agent's call returns at once with the address to show you. In the reporails plugin that is /reporails:ails xray; any agent connected to the reporails MCP server can call its xray tool, optionally with a session. Without a terminal tool, ails xray --current --background prints the same address. A page already running for the project is reused, and a page started with ails xray in a terminal is reused too. A page stops by itself after 30 minutes with no request, so an agent's calls leave no servers running.
• Which session opens. From inside Claude Code, --current and the xray tool find the session you are running in by its id, whichever project it ran in, and open it even when a newer session of that folder exists. When the agent does not tell the command which session it is, the newest session opens and the page says that it is only the newest.

The page uses the names your coding agent gives its agents, tools and files, so only what that agent has appears. It updates while the session runs, checks the project's files once when it opens, and reads the session transcript Claude Code keeps under ~/.claude/projects/ and, with the reporails plugin installed, the session's recorded events. Nothing is sent off the machine except the check and fix calls ails check makes; a part of the page with no source shows "not known here".

Next steps

• Score Guide — what the number means in practice
• Tiers and Limits — Free vs Pro, what each tier includes
• Configuration — tuning rules, agents, exclusions
• FAQ — common questions

← Reporails CLI Documentation · Getting Started · Agent Support →