xailon-review user guide

1. Install and first run

You need:

• macOS on Apple Silicon (XailonCode is Apple Silicon only for now)
• the xailon CLI on your PATH, signed in, with a working model
• git
• optional: gh (GitHub CLI, signed in) for PR facts and the PR bot
• optional: Google Chrome or Chromium for PDF output

Get the binary:

node scripts/build-binary.mjs        # builds dist/xailon-review (~100 MB, no Node needed to run it)
cp dist/xailon-review /usr/local/bin/

To run from source instead, use Node 22.13 or later and run npm link.

Check the engine:

xailon-review engine check                # JSON mode (default)
xailon-review engine check --engine acp   # ACP mode

If this fails, fix XailonCode first (see Troubleshooting). If xailon is not on your PATH, set XAILON_BIN=/path/to/xailon.

Where things are stored:

Add .xailon-review/*.db and .xailon-review/pr/ to .gitignore. Commit decisions/, and commit reviews/ too if you want report history in git.

2. Five-minute tour

cd ~/code/my-service
xailon-review scan                          # index and run the deterministic scanners (seconds, no model)
xailon-review review readiness --org "Platform team"   # full review (5–8 min)
xailon-review view                          # explore it in the browser and ask questions
xailon-review review whiteboard             # architecture tour with diagrams (3–4 min)
xailon-review pr 128                        # dry-run review of PR #128 (posts nothing)
xailon-review slop src/                     # AI-slop check

All commands work on the current directory. To target another repo, pass --root <dir>, or pass the path after the review type: review readiness ~/code/other.

3. Reading a report

Every report follows the same rules, so you can read one, then trust the format of the others.

Evidence tags

Every claim says how it is known:

Citation checking

Every path:line is checked against the repository at that commit after the model finishes. A citation that does not resolve is marked †. An [observed] claim whose citations all fail is downgraded to [inferred]. The "How to read this report" section shows the counts.

Categories and IDs (readiness and follow-up)

One rule: a failure with no recovery path never goes in SLA. An SLA can put a price on downtime or data loss. It cannot put one on "the system does not come back".

Severity

blocker (do not ship), high, medium, low. Within a category, items are ordered by severity.

⚠ marks

In whiteboard tours and the code map, ⚠ marks a structural weak spot, or a module with open high or blocker scanner findings.

The code map

The code map is drawn deterministically from build manifests, directory structure and resolved imports. No model is involved, so two runs at the same commit give the same map. A red dashed edge closes a dependency cycle.

4. Reports

Production readiness review

xailon-review review readiness [path] [--org NAME] [--areas 7] [--parallel 3]

How it works:

1. Facts (no model): index, module graph, scanners, git churn, deploy and CI files, listening ports. With gh, it also collects merged PRs that had no second reviewer, and open issues.
2. Area reviewers: XailonCode agents work in parallel, read-only. There is one per area: the largest modules, security and identity, durability and recovery, and deployment and operations.
3. Lead synthesis: deduplicates, sorts into A, C and S, names the architecture gaps, and writes the summary, recommendation, process notes and next steps.
4. Verification and render.

Sections:

• Summary and recommendation
• How to read
• Architecture gaps
• (a) Needs work, (b) Constraints, (c) SLA
• Process
• What is already good
• Code map
• Next steps

Tips:

• --areas controls breadth: more areas cost more tokens and give more findings.
• --parallel controls speed. Keep it at 3–4 unless your XailonCode plan allows more concurrency.
• Run scan first on large repos so the facts step is fast.

Follow-up review

xailon-review review followup --prior latest      # or --prior <review id>

Reloads the earlier readiness review and re-checks every item at the current commit. Each item is marked closed, mostly closed (with what is left) or open, and fixes are attributed to the merged PRs that made them. Only code that changed since the earlier review is reviewed again. Use it after a fix sprint.

Whiteboard tour

xailon-review review whiteboard [path]

Explains how the system is built, diagrams first:

• the system on one page and the code map
• one section per mechanism (state, request routing, writes, replication, recovery …), with ⚠ weak spots
• a "bets" table (each design choice, what it buys and what it costs)
• a comparison with similar systems

Mermaid diagrams are syntax-checked in a headless browser, and broken ones are sent back to the engine for repair, up to two passes.

Managing reports

xailon-review reports                 # list
xailon-review reports --open <id>     # open the PDF
xailon-review render <id>             # re-render HTML/PDF from the stored JSON (recomputes the code map, re-checks diagrams)

Report IDs look like readiness-2026-10-28-8b10e2d (type, date, commit). latest refers to the most recent readiness review.

5. The interactive viewer

xailon-review view                    # all reports, http://127.0.0.1:7421
xailon-review view <id>               # open a specific report
xailon-review view --port 8080 --no-open
xailon-review view <id> --static      # write <id>.interactive.html to share

Ask the report. Click Ask the report (top right) to open the chat.

• Ask anything about the report or the code. XailonCode reads the report, can open files in the repo (read-only), cites path:line, refers to items by ID, and says so when the report is wrong.
• Focus: "Ask about this" on an item, module or section adds it as context. Clear focus removes it.
• Suggested questions change with the report type and focus.
• A typical answer takes 30–90 seconds and 0.5–2M tokens. Progress steps stream while it works.

Safety: the server binds to 127.0.0.1 only. Code requests are confined to the repository root. Ask runs XailonCode read-only. If the port is busy, the viewer uses the next free one.

Static export: one HTML file with the report embedded. Charts, filters, the code map and diagrams all work offline (diagrams need internet to load Mermaid). Ask and code snippets need the live server, so they are hidden.

6. Pull-request review bot

xailon-review pr 2983                    # dry run: prints the review, posts nothing
xailon-review pr https://github.com/org/repo/pull/2983
xailon-review pr 2983 --post             # post ONE GitHub review (summary + inline comments)
xailon-review pr 2983 --post --block     # REQUEST_CHANGES and exit 1 on a blocker/high
xailon-review pr 2983 --max-comments 8

What it does:

1. Checks out the PR head in a throwaway worktree (.xailon-review/pr/<n>).
2. Runs the deterministic checks on added lines only: security rules, decision-ledger rules, slop detectors. It also computes the blast radius (who imports the changed files) and finds other open branches touching the same files.
3. Runs one focused engine pass over the diff and the surrounding code, using relevant patterns from the pattern index. It reports bugs, security problems, data loss, broken contracts and slop that matters. It never reports style.
4. Places comments only on lines that are in the diff. Anything else goes in the summary under "Outside the changed lines".

Re-runs: after a new push, run it again. It reads the hidden state marker in its earlier review and never repeats a comment.

Each comment shows:

• severity
• [observed] or [inferred]
• source: engine, static rule, slop or decision

Requirements: gh signed in, with write access to the repo for --post.

Dry run is the default on purpose. Run without --post first on any repository you don't own.

7. AI-slop validator

xailon-review slop                    # whole repo: findings + slop index (per 1,000 lines)
xailon-review slop src/ api/          # specific paths
xailon-review slop src/ --deep        # + engine pass judged against the pattern index
xailon-review slop --json

--deep sends the static hits plus a sample of the code to XailonCode, judged against the pattern index. It rejects false positives, adds problems the detectors cannot see (for example a rate limiter defeated by trustProxy: true), cites a pattern for each, and gives an overall verdict: clean, some slop, or sloppy.

Known limits:

• Phantom-import checks cover JS/TS and Go manifests. Python imports are not checked yet.
• Generated, migration, seed and data paths are excluded from copy-paste detection.

8. Pattern index

The index lists concrete engineering rules learned from well-regarded open-source repos. Slop --deep and PR reviews judge code against it.

xailon-review patterns repos                      # catalog (✓ = learned)
xailon-review patterns repos --lang go
xailon-review patterns learn fastify/fastify      # one repo (or any owner/repo, even outside the catalog)
xailon-review patterns learn --lang ts            # a language
xailon-review patterns learn --all                # everything not yet learned
xailon-review patterns learn --all --force        # re-learn everything
xailon-review patterns list --category error-handling
xailon-review patterns search timeout

Catalog: 24 repos across Go, TypeScript, Python, Rust and JVM, including healthcare/FHIR projects (medplum, HAPI FHIR).

Each pattern has:

• a rule you can check in a review
• the anti-pattern it avoids
• the failure it prevents
• a cited example (path:lines and a GitHub permalink)

Citations are checked against the clone, and patterns with bad citations are dropped.

Categories:

• error-handling
• input-validation
• resource-bounds
• concurrency
• persistence-transactions
• config-and-secrets
• security-authz
• shutdown-lifecycle
• observability
• testing
• api-design
• module-structure

Learning takes about 3–4 minutes and 1.5–2M tokens per repo, which is about 1.5 hours for the full catalog. The index is per user (~/.xailon-review), so you learn once and every repo benefits.

9. Competitive and architecture analysis

export PARALLEL_API_KEY=…     # Parallel Web Systems, or
export TINYFISH_API_KEY=…     # TinyFish
xailon-review compete                                     # discover competitors automatically
xailon-review compete --vs competitor-a.com,competitor-b.com   # name them
xailon-review compete --product "AI code review with cited reports" --max 4
xailon-review compete --web tinyfish --no-fetch

Pipeline:

1. Self profile: XailonCode reads your repo and lists its capabilities, each with maturity (solid, partial or stub) and code evidence. It also gives the market category and search queries.
2. Research:
   • Competitors are found by web search (or taken from --vs).
   • For each one it searches features and pricing, architecture and deployment, and independent user reviews (Reddit, HN, G2).
   • TinyFish also fetches full pages. With Parallel, pages are fetched directly unless you pass --no-fetch.
   • Every page becomes a numbered source W1…Wn.
3. Synthesis:
   • feature map: ● has it · ◐ partial · ○ does not · ? no source says. It never guesses "does not".
   • architecture compared, with ⚠ weaknesses
   • what users praise and complain about
   • ranked gaps: must, should, could or skip, with effort S/M/L/XL. "Skip" is an explicit "not worth chasing".
   • where you are ahead, and next moves
4. Verification: unknown W ids and missing files are marked †. An [observed] claim with no valid source is downgraded.

Vendor pages are treated as claims. User reviews and documentation count for more. Open the result with xailon-review view for the filterable matrix.

10. Scanning, branch checks and the decision ledger

These run without any model. They are fast and deterministic, so they suit pre-commit hooks and CI.

Scan

xailon-review scan                 # incremental: only changed files are re-indexed
xailon-review overview

Analyzers:

• secrets
• injection, TLS turned off, weak crypto
• import cycles (Tarjan), orphan files, god files
• churn × complexity hotspots
• decision violations

Findings are fingerprinted, so they keep their identity across scans and resolve automatically when the code is fixed.

Search and impact

xailon-review search "rate limit"          # BM25 over code chunks + symbol boost
xailon-review symbol handleConn
xailon-review impact src/http/service.go   # who depends on this file (default depth 3, --depth N)
xailon-review context src/a.ts src/b.ts    # context pack: the files, their neighbours, decisions in scope

Branch check

xailon-review check                        # vs origin/main
xailon-review check --base origin/develop

Reports issues on added lines only, decisions in scope, blast radius, and other branches editing the same files. Exits with code 1 on blocking issues, so it works as a pre-push hook or CI gate.

Decision ledger

Architecture decisions are Markdown files in .xailon-review/decisions/ that contain machine-checkable rules.

xailon-review decision new --title "HTTP goes through lib/http" \
  --decision "Services must not import axios directly" --rationale "Retries, timeouts and tracing live in lib/http" \
  --scope "src/**" --owner platform --status active \
  --rules '[{"type":"forbid_import","pattern":"axios","message":"Use lib/http"}]'
xailon-review decision list
xailon-review decision accept <slug>       # proposed → active
xailon-review decision retire <slug>
xailon-review decision supersede <slug>

Rule types:

Every rule also accepts these optional fields: in, except (globs), severity (default high) and message.

You can also edit the Markdown directly. The rules go in an `atlas-rules JSON block. Only active decisions are enforced.

11. Integrations

GitHub Action setup:

• Runner: macos-14 (Apple Silicon).
• Secrets: XAILON_CONFIG_YAML and XAILON_SECRETS_YAML, which hold your XailonCode config and secrets.
• Repository variable: XAILON_REVIEW_BINARY_URL, where the workflow downloads the binary from.

The Action posts with --post. Add --block if you want it to fail the check on blockers.

12. Configuration reference

Global flags

Engine flags (any AI command)

Environment variables

Your XailonCode models, privacy routing and spending limits apply to every AI command.

13. Cost and time

Rough figures from real runs (rqlite, about 100k lines of Go; a TypeScript monorepo):

To spend less:

• lower --areas
• review a sub-path
• use a cheaper --model for pr and slop --deep

14. Troubleshooting

15. FAQ

Does my code leave my machine? Only through XailonCode, under your XailonCode privacy routing. compete sends search queries (product category and competitor names) to the web provider you choose. It never sends code.

Does it run my code? No. Every review reads code. Claims about runtime behaviour are tagged [inferred].

Can the engine change my files? No. Reviews, PR reviews and Ask run read-only. Permission requests other than reads are rejected.

How do I know a finding is real? Click the citation. The viewer shows the exact lines. [observed] with a resolved citation is the strongest grade. Ask the viewer "Is A3 right? check the code" for a second look.

Can I use it in CI? Yes. Use check (no model, exit code) as a gate, and pr --post for review comments. See Integrations.

How is this different from XailonCode itself? XailonCode is a general coding agent. xailon-review is a reviewer product built on it: deterministic facts, a fixed report format, mechanical citation checks, a decision ledger and a PR bot.