gem-hunter

AI Instruction Diagnostics for coding agents. Validates the entire agentic instruction system against 120+ rules across six rule packs (core + per-agent). Supports Antigravity, Claude, Codex, Copilot, and Cursor.

Beta phase - moving fast, feedback welcome.

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

No install, no account. The headline is a single Quality score (the analysis service's verdict on how well-formed your instructions are); fix the findings that move it, run again, watch it climb:

Reporails — Diagnostics

  ┌─ Main (1)  6 directive / 1 constraint · 30% prose
  │ CLAUDE.md  6 dir / 1 con · 30% prose
  │   ✗       Unresolved imports: docs/setup.md  CORE:S:0024
  │   ⚠       Missing directory layout — show the project structure with a tre…  CORE:C:0035
  │     ... and 19 more
  │     6 vague · 7 brief · 1 weak
  │     ⊕ 2 Pro diagnostics — topic overlap, unbalanced topics
  │
  └─ 35 findings

  ┌─ Rules (1)  4 directive · 20% prose
  │ testing  4 dir · 20% prose
  │   ⚠       No frontmatter block found  CLAUDE:S:0012
  │   ⚠       Missing frontmatter block — start with --- delimited YAML frontm…  CORE:S:0006
  │     ... and 1 more
  │     4 vague · 4 brief
  │     ⊕ 1 Pro diagnostics — topic overlap
  │
  └─ 11 findings

  ── Cross-file ────────────────────────────────────────

  ⚠  .claude/rules/testing.md ↔ CLAUDE.md — 3 overlaps
  ⚠  .claude/rules/testing.md ↔ CLAUDE.md — 1 repetition

  Line-level detail → sign in with ails login, then upgrade to Pro

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

  Quality   1.0 / 10  ▓▓░░░░░░░░░░░░░░░░░░  (1.0s)
  Fix now   1 error. Start with CORE:S:0024.
  Findings  46 total · -v to list every one
  Agent: Claude
  Level: L3 Scoped

  Scope:
    instructions: 10 directive / 4 prose (27%)
                  1 constraint

  Main (1):  ▓▓░░░░░░░░░░░░░   1.0  35 findings · 1 error
  Rules (1): ▓▓░░░░░░░░░░░░░   1.0  11 findings

  Top rules (by finding count):
    CORE:E:0004   x11  warn  Instruction Elaboration
    CORE:C:0042   x10  warn  Specificity Gap
    CLAUDE:S:0012 x2   warn  Path Scope Declared
    CORE:C:0005   x1   warn  Testing Framework Documented

  + 3 Pro diagnostics (3 warnings)
  1 cross-file repetition
  1 element pair overlaps in topic — keep each topic in one file

  Pro adds the remedies and the order to apply them.
  → sign in with ails login, then upgrade to Pro

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

Puts ails on your PATH, installs the reporails plugin into Claude Code and Codex when they are on your machine, and prints the install steps for the other supported agents (also listed in Agent Support). ails install --project installs the plugin for the current repository only, shared with collaborators through its Claude Code settings; Codex installs for your user. ails update upgrades ails and refreshes the plugin in each agent that has it. With Pro, the step after install is /reporails:ails heal in Claude Code, which rewrites your instruction files.

Anonymous mode needs no account, and signing in is free. Anonymous and signed-in free accounts share the same rate and payload caps and the same full diagnosis — every finding, the score, and the fix text of the local checks in -f json and MCP — and ails check --heal writes fixes on a Pro account only (an anonymous or free run gets the diagnosis and no changes). ails check also shows messages about your account (a failed payment, Pro ending) when there are any. Pro is the paid subscription: it raises the rate and payload caps and unlocks the remedies for the findings worth fixing, the exact line of each cross-file repetition and topic overlap, and the ordered remediation workflow your coding agent runs end to end.

# Sign in through your browser; one sign-in per machine
ails login

Full breakdown: Tiers and Limits.

Run on every PR so instruction-quality regressions (vague or buried instructions, oversized files, weak reinforcement, instructions repeated across files) get caught the same way test or lint regressions do — before merge, not after a teammate's agent has been silently misbehaving for a week.

- uses: reporails/cli/action@0.6.5
  with:
    api-key: ${{ secrets.REPORAILS_API_KEY }}   # optional - a Pro key unlocks the full diagnostic detail
    strict: "true"                              # exit 1 if any rule fires
    min-score: "7.0"                            # exit 1 if Quality < 7.0

Create an API key on reporails.com/account and store it as REPORAILS_API_KEY in your CI secret store. See Configuration → Authentication.

The action keeps the analysis model (~275 MB) in the repository's Actions cache: the first run downloads it, and later runs restore it instead of downloading it again, even when the check fails. Running ails directly in a workflow? See Configuration → Caching the model in CI.

• Getting Started - install, first run, what the output means
• Agent Support - which agents are recognized and what's covered
• Tiers and Limits - Free vs Pro, what each tier includes
• Configuration - disabling rules, project / global config, exclude paths
• Score Guide - how the score is built and what it tells you
• Capability Levels - the L0-L7 ladder and what each level requires
• Rules CLI - ails rules list --capability=skill and friends — preflight rules before authoring
• FAQ - common questions

• Antigravity — Google
• Claude — Anthropic
• Codex — OpenAI
• Copilot — GitHub
• Cursor — Anysphere

BUSL 1.1 - converts to Apache 2.0 three years after each release.

The analysis model files are licensed separately under the Reporails Model Licence.