Air CLI

Air is a team business-fact trust layer for the AI-coding era, built around Claude Code (cc). It turns the increasingly expensive question — "what business does this code actually implement, and can I trust that answer?" — into evidence-bound, human-signed, self-freshening facts a team can share: understand → curate → validate → reconcile → human-freeze → keep-fresh. Underneath sits a deterministic local code explorer (five phases: index, coverage, graph, provenance wiki, intent alignment) that the trust layer and air q reuse.

The package is published as @fe178/air. It exposes the air, ai-ready, and air-explorer binaries.

Air has two layers you can use:

• Trust layer (the product) — the business-fact loop above, delivered as Claude Code skills. You drive it by talking to cc in natural language; air supplies the engine, cc supplies the interaction.
• Deterministic CLI (the engine) — air q, air fact …, air panorama, air web, and the air explorer family. No LLM, CI-friendly, usable standalone.

Quick Start

npm install -g @fe178/air   # install the CLI
air on                      # install the skills into Claude Code, then restart cc

Then cd into any project and tell Claude Code 「理解这个项目」 / "understand this project" to start building facts. Use these CLI commands anytime (no Claude Code needed):

air panorama --open   # offline business-fact panorama page for this project
air web               # serve the panorama locally with live-reload
air q schema          # pre-computed business map · concept→file lookup (no LLM)
air fact status       # trust status gate, CI-friendly (exit 0/1)

Everything below is the detailed version of the above.

Install & Use

Requires Node.js 20+, and — for the trust-layer skills — Claude Code installed.

npm install -g @fe178/air   # 1. install the air CLI
air on                      # 2. install the skills + wire the global rule into Claude Code
                            # 3. restart Claude Code so it picks up the new skills

air on is the one-command front door. It:

• copies the 11 bundled skills into ~/.claude/skills (global — one machine, every project);
• idempotently @imports air's global behavior rule into ~/.claude/CLAUDE.md (inside a managed marker block);
• records the on/off switch state.

Companion switches:

• air off — comment out the @import and remove the skills (byte-exact, reversible) — gives you an "air disabled" A/B baseline.
• air status — show 🟢 on / ⚪ off, how many skills are installed, and whether the rule is wired.

(air skill install --all does the same skill + rule wiring if you prefer the explicit form.)

In a project

cd into any project, open Claude Code, and just say what you want — the matching skill fires and persists facts under that project's .ai-ready/facts/:

| Say it (any natural phrasing, zh/en) | Skill | Persists | | --- | --- | --- | | "理解这个项目" / "understand this project" | air-understand-project | code-capabilities-v0.json | | "整理 PRD" / "which specs are current" | air-curate-intent | intent-sources-v0.json | | "验证下需求" / "validate the intent" | air-validate-intent | intent-capabilities-v0.json | | "代码和 PRD 对得上吗 / 对账" / "reconcile code vs spec" | air-reconcile-intent | code-intent-reconcile-v0.json | | "审一下、冻结" / "review and freeze" | air-review-freeze | frozen-facts-v0.json (sha256-bound) | | "刷新 / 保鲜" / "refresh stale facts" | air-fact-refresh | updates frozen-facts-v0.json |

The fact repository is per project (each project's own .ai-ready/facts/); the skills and the global rule are shared, so new projects need no reinstall.

Deterministic CLI (no Claude Code needed)

air q schema                 # pre-computed business map + concept→file lookup (no LLM)
air fact status|verify|coverage|impact|freshness   # trust gates, CI-friendly (exit 0/1)
air panorama --open          # generate this project's offline business-fact panorama page
air web                      # serve the panorama locally with live-reload

Explorer engine (low-level CLI)

The explorer is the deterministic index the layers above build on. Run it directly inside any project:

air explorer index .

Zero-build cross-platform (0.4.0+): tree-sitter parsers ship as WASM (no native parser build), and SQLite uses an auto-selecting adapter:

• node:sqlite (Node 22+ built-in · zero dependency · fastest)
• better-sqlite3 (native · macOS/Linux prebuilt · optionalDependencies · fastest pre-Node-22)
• sql.js (pure WASM · always available · works on Windows without VS Build Tools)

Force a specific backend with AIR_DB_BACKEND=node|better|sqljs. Node.js 20+ is required.

Explorer quick demo

mkdir -p /tmp/air-hello/src && printf 'export function hello(name) { return `hi ${name}`; }\n' > /tmp/air-hello/src/hello.js
air explorer index /tmp/air-hello
air explorer ask /tmp/air-hello "What does hello do?"

If no ANTHROPIC_API_KEY is available, the LLM commands can fall back to an installed local CLI such as claude or codex when logged in.

Explorer Commands

| Command | Purpose | | --- | --- | | air explorer index <repo> | Build or refresh the local SQLite explorer index. | | air explorer ask <repo> "<question>" | Ask a grounded code-understanding question with explorer tools. | | air explorer coverage <repo> --symbol NAME / --gaps | Inspect test links and untested symbols. | | air explorer graph <repo> --callers NAME / --callees NAME / --module-deps | Inspect call edges and module dependencies. | | air explorer wiki gen <repo> <symbol> [--strict] | Generate provenance-backed wiki facts and artifacts. | | air explorer wiki list <repo> [--stale] | List generated wiki entries and stale status. | | air explorer wiki overview <repo> [--class CLASS_ID] [--out FILE] | Generate a bundle overview from wiki entries. | | air explorer intent <repo> --docs "**/*.md" [--mine-git] | Ingest docs and git tickets into feature and requirement nodes. | | air explorer feature <repo> --map "Feature" / --impact SYMBOL | Map feature evidence or inspect symbol impact. | | air explorer diff <repo> [--base REF] | Explain changed files, changed symbols, callers, and affected features. | | air explorer tour <repo> | Produce a dependency-ordered project tour. | | air explorer lint <repo> [--feature NAME \| --all] | Reconcile feature intent against code evidence through the LLM gateway. | | air explorer dashboard <repo> [--out FILE] | Write an offline HTML dashboard of graph and wiki evidence. | | air explorer pr-risk <repo> [--base REF] [--out FILE] | Produce evidence-gated PR risk reviewer notes. | | air explorer eval <repo> [--class CLASS_ID] | Run the per-project-class explorer eval set and append history. |

Additional maintenance commands include docs, context, facts, and hook. See src/air/explorer/README.md for API and lower-level examples.

Architecture

• Phase 1 - index: parse source files into symbols, hashes, FTS search, and .explorer.db.
• Phase 2 - coverage: detect tests and deterministic tests edges.
• Phase 3 - graph: extract imports, calls, callers, callees, and module dependency rollups.
• Phase 4 - provenance wiki: store derived facts, source hashes, staleness, markdown artifacts, strict JSON pages, and wiki overview.
• Phase 5 - intent alignment: ingest docs and git history, create feature and requirement nodes, map features to code, inspect impact, diff changes, lint divergence, and evaluate PR risk.

Layer 1 project class detection routes prompts and evals for frontend classes such as React Vite SPA, Next App Router, Vue Vite SPA, Nuxt fullstack, TypeScript CLI monorepo, and NestJS/Vue/Electron monorepo. Class detection is a routing hint, not a confirmed fact; reports still require file:line evidence.

The agent path is hardened around a single LLM gateway, strict JSON parsing where required, hallucinated-evidence dropping, bounded feature-map output, throttling/cache controls, and loud fallback messages when API, Claude CLI, or Codex CLI calls fail.

Examples And Dogfood

• R107 eval dogfood: guada, v3-admin-vite, and Next blog-starter all produced PASS eval artifacts. See PRD/PM-Discussion/ROUND-107-eval-set/01-IMPLEMENTATION_REPORT.md.
• R112/R116 guada dogfood covered diff, tour, lint, and pr-risk. See PRD/PM-Discussion/ROUND-112-diff-tour-lint/01-IMPLEMENTATION_REPORT.md and PRD/PM-Discussion/ROUND-116-pr-risk/01-IMPLEMENTATION_REPORT.md.
• R114 WASM dogfood covered guada, typehero, v3-admin-vite, and Next blog-starter. See PRD/PM-Discussion/ROUND-114-wasm-treesitter/01-IMPLEMENTATION_REPORT.md.
• R117 wiki overview generated a real guada wiki bundle overview from R104 wiki entries. See PRD/PM-Discussion/ROUND-117-wiki-overview/01-IMPLEMENTATION_REPORT.md.

Local Artifacts — commit the facts, ignore the regenerables

Air writes two kinds of files into the target project. They are NOT the same and should be treated differently in git:

✅ Commit (the trusted fact layer — your team's shared asset):

.ai-ready/facts/*.json
  code-capabilities-v0.json     # code-side capability map
  intent-capabilities-v0.json   # intent-side (PRD) capability map
  intent-sources-v0.json        # which docs are the current intent
  code-intent-reconcile-v0.json # code ⟷ intent reconcile
  frozen-facts-v0.json          # human-reviewed, sha256-bound trusted facts

These are human-reviewed business facts that travel with the repo so the whole team (and the next AI coding session) inherits them. Commit them: git add .ai-ready/facts && git commit.

🚫 Ignore (regenerable products — rebuild anytime, do not commit):

.explorer.db                     # binary symbol index (rebuild: air explorer index .)
.ai-ready/*.html                 # panorama.html and other emitted pages
.ai-ready/panorama.html
.ai-ready/explorer/              # dashboard.html / wiki / eval / runs
.ai-ready/bizai/

Recommended setup (in the user project, not this repo): add a .ai-ready/.gitignore so products are ignored but facts stay tracked, and ignore the binary index at the repo root:

# .ai-ready/.gitignore  (facts/ stays tracked; products are regenerable)
*.html
explorer/
bizai/

# repo-root .gitignore
.explorer.db

These regenerable artifacts can contain source-derived project information. Review them before committing or publishing.

Note: this repository's own root .gitignore ignores the whole .ai-ready/ — that is air's dogfood private setting (air's self-produced facts should not pollute the air repo). Do not copy it into your project. In a real user project you commit .ai-ready/facts/ as above.

Publishing Status

The package is structurally prepared for npm packing, but real publish remains an owner decision. Public release should confirm package scope, repository/homepage/bugs metadata, version bump policy, and whether the package should go public or stay in an internal registry.

Useful checks:

node scripts/validate-air-explorer-npm-pack.mjs
npm pack --dry-run --json

Security

Do not index or publish secrets, tokens, private logs, raw snapshots, or unreviewed .ai-ready artifacts. Model output is candidate knowledge until grounded by evidence or human review. See SECURITY_NOTES.md.

Contribute

• Keep source files under src/air/explorer/*.ts and generated dist files under src/air/dist/explorer/** in sync with npm run build:air.
• Add focused validators for behavior changes under scripts/validate-air-explorer-*.mjs or focused tests under tests/air/3-noun/.
• Preserve evidence gates: scan_signal and LLM prose are not confirmed product truth without source evidence.

License

MIT. See LICENSE.