Harness

CI CodeQL OpenSSF Scorecard codecov License: Apache-2.0 Node ≥20

A cross-platform CLI that helps prepare developer workstations and repositories for reviewable, governed AI-assisted coding in enterprise environments — from locked-down, TLS-intercepted networks to open ones. It extracts corporate trust, tunes local inference, adds repo guardrails, wires up MCP / observability / sandboxing, and lays down a tool-agnostic context architecture — all from one command surface. On top of that setup it runs a governance loop for external agent skills — vet → approve → pack → marketplace → evidence — anchored in a committed approval lock (aih-skills.lock.json).

See docs/ARCHITECTURE.md for the shipped architecture and current trust boundaries, and docs/CONTROL_MATRIX.md for the claim -> implementation -> test proof map.

Provided as open-source software under Apache-2.0 on an "AS IS" basis. No warranty, support obligation, SLA, indemnity, consulting, or professional advice is provided. aih is dry-run by default — review the plan before running --apply. See DISCLAIMER.md.

The stable command contract

For the current v2 line, pin @aihq/harness@^2 unless your organization pins an exact release for reproducible rollout. Every command, flag, and deprecated alias is snapshot-tested in CI against a committed fixture, the --json envelope is schema-pinned, and exit-code semantics are pinned — a surface change fails the build until it ships as a reviewed contract decision. Renames ship as deprecated aliases (the old name keeps working, with a one-line warning) before a major removes them, and security fixes land on the latest minor — upgrading is the fix path. The full policy: STABILITY.md.

Design posture

Install

Install and verify a published release. Current releases publish npm provenance plus GitHub release checksums and a keyless cosign bundle:

npm install -g @aihq/[email protected]      # then run: aih --help
aih verify-release 2.11.0   # checks npm signatures, GitHub release sums, and cosign evidence for 2.11.0

Full release verification requires local npm, gh, and cosign; proceed only when all three legs pass. A skipped leg is incomplete evidence, not a successful rollout gate.

npm install        # deps
npm run build      # → dist/cli.js  (bin: aih)
node dist/cli.js --help

Quickstart

aih doctor              # read-only: is the workstation ready for AI coding?
aih init .              # preview the full repo bootstrap (dry-run — nothing is written)
aih init . --apply      # apply it

Guides by workflow

Use the command reference for exact CLI behavior; use the guides when you need the right workflow for a reader or rollout stage.

Command surface

One honest line per command — the long-form behavior detail for every command lives in docs/commands.md, and aih <command> --help is authoritative for flags. Keep this table as a navigation index: do not add flag-level behavior or workflow recipes here.

Workstation & runtime

Repo canon & bootstrap

Skill governance & supply chain

Enterprise packs, skill governance, and safety

Trust configuration notes

trust.internalScopes is intentionally inert until an org configures internal package scopes in policy. Without that scope list, dependency-confusion checks still report general package risk but do not guess which names are private to your organization.

Baseline component evidence

aih ecc and aih superpowers acquire only exact Git commits into quarantine. Selected component paths must match the vendor lock shipped in the npm release or an attributable GitHub-attested org bundle. Covered user seats verify hashes and signatures; they do not rerun the release analyzers. Missing/mismatched coverage warns without an authorization receipt at vibe and denies at team/enterprise. A signed blocked verdict denies at every posture and cannot be waived by org evidence for the same bytes. See Baseline Component Evidence for the vet/sign/policy flow.

Analytics & operations

Verification

Shared flags: --apply, --force, --verify, --json, --posture <vibe|team|enterprise>, --support-out <dir>, --no-log, --context-dir <dir>, --root <dir>, --cli <list>, --all-tools, --detect, --yes (read-only commands take the relevant subset). Settings also read from AIH_* env vars (AIH_APPLY, AIH_CONTEXT_DIR, AIH_LOG, …).

Plugins

At startup aih probes for exactly one optional peer package: @aihq/enterprise — the literal name, never env- or config-selectable, so nothing can point the probe at other code. The package name is a reserved extension point; the open-source harness does not require it to be published. When installed, it contributes additive enterprise command capabilities through its aihCommands export (CommandSpec[]) as defined in the enterprise extension point spec. Those commands register as native subcommands through the identical path as the built-ins: shared flags, posture resolution, the dirty-worktree gate, and the run ledger all apply unchanged. Not installed → zero output, fully local. AIH_NO_PLUGINS=1 disables the probe. A plugin that fails to load, exports the wrong shape, or ships an invalid spec degrades to local-only with a one-line aih: plugin: warning on stderr — and a plugin command can never shadow a built-in (built-ins always win). Installing the plugin package is the trust decision: importing it runs its code, exactly like any other dependency you install.

The probe is hardened at its seams. The package must resolve from the install tree aih itself runs from (the node_modules chain above the aih binary), so a global or npx-run aih pointed at an untrusted repo never imports a node_modules/@aihq/enterprise planted inside that repo. Honesty note: when aih is installed inside the target repo, the repo already controls the binary itself — the boundary is exactly "the tree aih runs from", nothing stronger. The import also races a 2-second startup budget (timeout → local-only with a warning), and aih --version skips the probe entirely. Plugin specs cannot claim shared or reserved flags (--apply, --json, --help, …), cannot take the names help/version, and alias fields plus any skipWorktreeGate field are stripped — aliases are core-owned and the dirty-worktree preflight always applies to plugin commands.

Dashboard

aih report --open builds a self-contained, offline HTML dashboard (dark by default with a light toggle; fonts embedded) — context footprint + a KPI strip, an adoption ring, output-velocity and code-quality panels, and trend sparklines from recorded history (aih track). Add --v9 for the newer developer-console dashboard: every panel is explicitly LIVE, PREVIEW, or EMPTY, so demo data never reads as real. When the report derives findings (see Support tickets), a Suggested actions section leads with copy-to-clipboard tickets. Add --demo for showcase data, or --refresh <sec> to keep it live.

The --v9 developer console with --demo showcase data: harness-wiring score, ranked fix actions, and the remediation ledger. This image uses demo/local data, not customer telemetry. aih report --demo --v9 opens the same dashboard locally.

Targeting CLIs

aih ecc, aih superpowers, and aih bootstrap-ai only touch the agent CLIs you actually use. Pass --cli with a comma-separated list, --all-tools for every supported CLI, or --detect to auto-target the CLIs found on this machine; the default is claude. Supported: claude, codex, cursor, antigravity, gemini, copilot, windsurf, opencode, zed, kimi, kiro.

aih bootstrap-ai --cli claude       # writes CLAUDE.md (the default target, auto-loaded)
# repeatable declarations add to detection and the prior machine union
aih ecc --cli claude,codex --with framework:react --with lang:typescript
aih superpowers --cli antigravity   # verify exact pin; guidance only (no mutable plugin exec)
aih bootstrap-ai --cli kiro         # Kiro: .kiro/steering/00-canon.md (inclusion: always)
aih bootstrap-ai --detect           # target only the CLIs installed here
aih init . --all-tools              # bootstrap a repo for every CLI at once

Each CLI gets its native entry: Claude → CLAUDE.md (the default target, auto-loaded), Codex/OpenCode/Zed/Kimi/Antigravity → AGENTS.md, Gemini → GEMINI.md, Cursor → .cursor/rules/*.mdc, Windsurf → .windsurfrules, Copilot → .github/copilot-instructions.md, Kiro → .kiro/steering/00-canon.md (inclusion: always, with a #[[file:…/RULE_ROUTER.md]] live-reference). For a tool aih doesn't target yet, <context-dir>/adapters/other-tools.md documents how to point it at RULE_ROUTER.md.

Per-tool depth (Kiro example). Claude reuses your ~/.claude baseline, so its entry is just CLAUDE.md. Tools that can't read ~/.claude get fuller native content instead — Kiro is the deepest case (schemas verified against Kiro's docs and ECC's real .kiro/ tree):

• aih bootstrap-ai --cli kiro → .kiro/steering/agent-tools.md (stack-aware CLI usage) + stack-aware .kiro/hooks/*.kiro.hook files (aih-secret-scan-on-create, aih-tests-on-edit, aih-quality-gate running the repo's real lint/test) in Kiro's real hook schema.
• aih ecc --cli kiro → emits scoped consult guidance; Kiro's native installer cannot yet materialize the component union safely, so aih does not run it.
• aih superpowers --cli kiro → .kiro/steering/superpowers-methodology.md (the brainstorm → plan → TDD → review routing, since Kiro can't load ~/.claude/superpowers).

Detection (--detect) targets runnable CLI binaries on PATH. Config dirs (~/.claude, ~/.codex, ~/.gemini, ~/.cursor, ~/.kiro, …) are still reported as config-only traces, but they are advisory and may be stale; they do not drive setup unless you explicitly type the CLI with --cli or --all-tools. Precedence: --all-tools > --cli > --detect > committed marker > runnable CLIs > default claude. When --detect finds no runnable CLI it defaults to claude and says so. In an interactive terminal, --detect shows the runnable list and any config-only traces before asking you to confirm or edit it (press Enter to accept, or type a comma-separated list to add/remove tools) before anything installs — pass --yes (or run non-interactively / piped / --json) to skip the prompt and use the runnable list as-is. aih doctor reports runnable vs config-only CLIs, and aih bootstrap-ai --verify adds a per-CLI "installed" confirm step (pass = runnable binary on PATH, skip = config-only/not here yet, bootloader still written) alongside the drift gate.

Canon directory name. Every generated file and reference adopts --context-dir <name> — use any name you like; the default is the visible ai-coding/:

aih init                          # → ai-coding/   (default, visible)
aih init --context-dir my-canon   # → my-canon/    (any name; everything adapts)
aih init --context-dir .ai-context  # → hidden, the old default

ECC install actions execute under --apply only after exact component evidence clears and the same quarantined tree re-hashes. By default, aih ecc materializes the additive union of its common baseline, detected or repeatably declared project riders, posture-selected security, and validated MCPs; --profile full is the explicit full-surface opt-in. Evidence verdicts apply per component: authorized components install, while held components are quarantined and reported with their exact codes and reasons. No install process starts unless ECC's installer runtime is also authorized. The project contribution keeps the requested intent, while each target record contains only the surface actually installed. The primary project/target contribution ledger lives at ~/.aih/ecc/registration-ledger.json and commits only after every install step succeeds. A bare aih prune also checks that ledger: missing project roots are retired, the live component/MCP union is recomputed, and only state-recorded aih-managed operations no longer shared by a live project are removed. Dry-run reports the diff without mutation; --apply hash-binds all inputs, rolls back partial failure, and replaces target state before committing the ledger last. Superpowers marketplace/TUI paths cannot bind installed bytes to that tree, so aih executes none of them; it emits pin-aware guidance and says those marketplace selections are not evidence-covered. ECC and Superpowers are complementary — ECC supplies stack-aware rules, agents, and memory; Superpowers supplies the disciplined agent loop that uses them. For Codex, installed ECC skills are consumed on demand by name, such as $configure-ecc, from the literal Codex skills path (~/.codex/skills/<name>/SKILL.md); they are not an ambient auto-loaded .agents/skills/ surface. aih ecc --cli codex still installs the selected ECC Codex skills/agents from ECC's manifest, but uses add-only Codex TOML merge helpers and a fenced AGENTS merge rather than the upstream ecc-install --target codex copy mode for shared ~/.codex files. Its scoped MCP block contains pinned sequential-thinking plus GitHub at team/enterprise (and repo-declared local graph/memory servers); Context7 and Exa are never defaults.

Layered AI canon (bootstrap-ai)

The harness models the same two-layer setup used in the reference repos (eicp / ai-os / syntegris):

• Layer 1 — user baseline: selectable with --baseline ecc|gstack|gsd (default ecc, ECC + Superpowers installed per CLI by aih ecc / aih superpowers).
• Layer 2 — repo canon: the committed ai-coding/ (or --context-dir) tree — RULE_ROUTER.md (stack-aware routing entry point), the contract files project.json, project.md, and setup.md, adapters/<cli>.md (per-tool wiring notes), and the root bootloaders (CLAUDE.md, AGENTS.md, GEMINI.md, Cursor/Windsurf/Copilot). REGENERATION.md is emitted only for --canon legacy.

aih bootstrap-ai generates and verifies Layer 2. Each bootloader is hand-editable tool-specific content plus one marker-delimited shared block that bootstrap-ai regenerates idempotently — your edits outside the markers survive (merged in, with an .aih.bak backup). aih bootstrap-ai --verify is the drift gate: it fails if the router is missing or a bootloader's block has been hand-edited away from the canonical source — wire it into CI to keep every tool's entry point in sync.

aih bootstrap-ai --all-tools --apply   # lay down RULE_ROUTER + adapters + bootloaders for every CLI
aih bootstrap-ai --baseline gstack     # use garrytan/gstack as the Layer-1 baseline
aih bootstrap-ai --verify              # CI drift gate (no writes; exit 1 on drift)

Precedence: Layer 2 wins on conflict — repo canon overrides the generic baseline. Run aih contract to refresh the contract files the compact router points at.

Multi-repo workspaces

Most orgs split a product across separate repos (a UI repo and a backend repo in one git org). An agent editing the UI then has no view into the backend — no cross-repo blast radius. aih workspace is a federated bridge, not a monorepo replacement: the child repo owns truth, and the parent workspace owns routing, contract edges, snapshots, MCP wiring, and report rollups. It bridges that gap from the parent folder that holds the repos:

aih workspace ./my-org --repos ui,backend --apply

It writes, at the parent (it does not touch the child repos — run aih init in each):

• <context-dir>/cross-repo-architecture.md — per-repo responsibilities + a cross-repo feature map (UI column · backend column · the contract). Write-once — aih seeds it from your repo list, then you own it; re-running never overwrites it.
• <context-dir>/repo-discipline.md — load a repo's own canon before editing it.
• Targeted CLI bootloaders — CLAUDE.md by default; --cli/--all-tools can add AGENTS.md, GEMINI.md, .kiro/steering/00-canon.md, and other tool-native entries.
• <name>.code-workspace — opens every repo in one VS Code window.
• .mcp.json — one code-review graph MCP per present declared child repo, using absolute root-anchored child paths so MCP clients work from any launch directory.
• .aih-workspace.json — marker that puts aih doctor into workspace mode (validates each child repo is scaffolded); object-form repos can retain optional remote/ref source metadata.
• Child repos are an explicit allowlist: use --repos or an existing .aih-workspace.json. If child Git repos are present without an allowlist, aih workspace reports candidates but does not add them to .aih-workspace.json or workspace MCP scope.
• aih workspace snapshot --lock --apply writes the recorded child remote into <context-dir>/workspace-lock.json when present, so a lock captures both the commit and fetch location. A manifest-declared remote takes precedence; otherwise snapshot collection reads only child-local origin config and never fetches.
• aih workspace hydrate --apply restores a declared workspace from .aih-workspace.json plus the committed workspace lock: missing children are cloned from recorded remotes, present clean children are checked out to the recorded ref, and children with no recorded remote are skipped with a note. Until a declared child exists, aih workspace --apply skips that child's graph MCP scope and emits a hydrate note instead of wiring an empty path.

Support tickets

Any verifying command (aih doctor, aih heal, aih secrets --verify, …) turns a failed or skipped check that carries a Check.code into a ticket-ready support template — three registers keyed off who fixes the issue, and external tickets are tool-neutral by contract (they never name aih). Labels print by default; --support-out <dir> writes full tickets, --json carries them. Registers, redaction, and the SETUP.md context markers: docs/commands.md.

Run ledger

Every aih invocation appends one structured row to .aih/runs/YYYY-MM.jsonl (UTC, month-sharded, append-only) — a "what happened" diagnostics trail: schema version, run id, capability, redacted argv, status (success / failed / partial / error), exit code, mode (apply/verify/json/sarif), platform, host hash, repo remote hash, write tally, and verification + support counts. It's distinct from .aih/history.jsonl (the per-commit metrics behind aih report trends). Logging is on only after the repo is initialised (a committed .aih-config.json marker exists) and never fails a command; opt out with --no-log or AIH_LOG=0. Like all of .aih/, the ledger is gitignored local diagnostics — never committed. aih evidence build packages it into a checksummed bundle; use aih evidence build --sign <signer> --require-signature when the bundle crosses a sharing boundary that requires tamper evidence.

Examples

aih doctor --json                 # what's configured? (read-only)
aih init . --apply                # bootstrap the current repo
aih certs --ca-pattern Zscaler --apply --verify
aih hardware                      # preview the tuned inference env block
AIH_CONTEXT_DIR=ai-coding aih scaffold --apply
aih doctor --support-out .aih/tickets   # write IT/support tickets for failing checks (kept local)
aih report --v9 --apply --out .aih/reports/local-v9.html
aih usage --apply --cli claude,codex,gemini
aih usage --rollup ../repo-a,../repo-b

Releases & roadmap

• Roadmap — ROADMAP.md, tracked as GitHub Milestones.
• Changelog — CHANGELOG.md; tagged builds on Releases.
• Versioning & support — VERSIONING.md. SemVer; security fixes land on the latest minor — upgrade to the latest release line to stay fixed.
• Supply chain — the current release workflow publishes via npm Trusted Publishing with build provenance and ships an SPDX SBOM, a SHA256 checksum, its keyless cosign signature bundle (SHA256SUMS.txt.sigstore.json), and the Sigstore build-provenance bundle on the GitHub Release. Releases from v0.6.0 onward include the sigstore/provenance assets; earlier historical tags have a narrower asset set. Tagged release artifacts claim SLSA Build L2 under SLSA v1.2; no Build L3 claim is made. Verify a published release with aih verify-release [version]; a skipped verification leg is incomplete evidence. Consumers with provenance-aware policy can also use gh attestation verify.
• Support — SUPPORT.md · Security — SECURITY.md (private reporting) · Contributing — CONTRIBUTING.md.

Development

npm test          # vitest
npm run typecheck # tsc --noEmit
npm run lint      # biome
npm run build     # tsup → dist/

Stack: TypeScript (ESM) · commander · zod · vitest · biome · tsup. Coverage floors are enforced in vitest.config.ts — set just below the achieved levels so coverage only ratchets up; CI and releases fail on regression. See CONTRIBUTING.md for the contributor workflow.

Stability

The tests behind the stable command contract live in tests/contract/: every command and option is snapshotted against a committed fixture (command-surface.json), the --json envelope is schema-pinned, and exit-code semantics are pinned. Additive changes regenerate the fixture in the same PR (label it contract:additive); removals or renames of anything pinned are breaking and ship in majors only, per STABILITY.md.

License

Apache-2.0.