AIIR for VS Code

AIIR for VS Code gives teams a local-first way to produce AI integrity receipts for git commits. Record the current commit, inspect what was captured, and share a proof summary without leaving the editor.

The default workflow is intentionally narrow: open a repository, run AIIR: Record Commit Activity, and let AIIR handle missing CLI or local .aiir/ setup from the same flow when the repository is not ready yet.

Invariant Systems makes AIIR. This extension works with the public aiir CLI and keeps the default workflow local. Optional networked or admin features stay out of the way unless you explicitly turn them on.

Why teams adopt it

• Produce verifiable proof for the current commit without leaving the editor.
• Review the receipt and copy a PR-ready summary from the same workflow.
• Verify existing AIIR receipts where code review already happens.
• Keep the default posture local instead of starting with a cloud dependency.
• Expose rollout, policy, and network-backed controls only when a team intentionally needs them.

What teams get on day one

• One core loop: record, inspect, and share proof for the current commit.
• One fallback surface: AIIR: Commit Status when setup or repository state needs attention.
• One default trust posture: local-first, with advanced and network-backed surfaces gated behind explicit opt-in.

This is the public single-repository operator experience for AIIR. The extension is designed to look calm in front of developers and credible in front of security, audit, and compliance reviewers.

Privacy and local data

• By default, AIIR keeps the extension in a local-only posture and leaves passive AI edit tracking off.
• If you enable aiir.listener.enabled, AIIR writes file-level provenance records to .aiir/editor_provenance.jsonl only while an AI coding tool is actively editing files in the current workspace.
• Receipt generation records active AI tools only. Installed-but-inactive extensions are not written into local receipts.
• If you enable aiir.provenanceRetainPrompts, AIIR may store raw prompt text on disk. Treat that setting as sensitive because prompts can contain credentials, proprietary code, or personal data.

Primary workflow

For most repositories, the product loop is only three steps:

1. Open a git repository in VS Code.
2. Use AIIR: Record Commit Activity to cover the current commit.
3. Copy the receipt summary or verify the result.

If the public aiir CLI or local .aiir/ scaffolding is missing, AIIR routes you through that setup from the same flow instead of forcing you to learn separate commands first.

AIIR: Commit Status is the fallback surface when one of those steps is missing or a repository needs repair.

Everything else in the extension exists to support that loop, verify its output, or help a repository recover cleanly when it is not ready yet.

By default, advanced/operator commands are intentionally buried behind in-product surfaces instead of filling the command palette. If you want direct command-palette access to those pages, enable aiir.showAdvancedCommands.

Sigstore is not the default local generation path. In the public codebase it still depends on the optional sigstore package plus ambient OIDC credentials, so the extension keeps local generation reliable by default and treats signing as a CI/release or explicitly configured workflow.

Advanced surfaces

These pages are useful once the core product loop is already working:

• AIIR: Control Panel
• AIIR: Health Check
• AIIR: Security Posture
• AIIR: Deployment Presets
• AIIR: Advanced Settings
• AIIR: Open Policy File
• AIIR: Edit Policy Targets
• optional Hub commands when local-only mode is intentionally disabled

These surfaces remain in the repo, but the extension keeps them behind advanced/admin mode or deeper in-product links so the default UX stays focused on the core local workflow first.

What it does

• Discovers AIIR receipt files in the current workspace.
• Verifies receipt integrity and shows diagnostics inline.
• Adds CodeLens and the Receipts view for quick inspection.
• Adds a Getting Started walkthrough and a setup/readiness panel for first-run onboarding.
• Records proof for the latest local commit through the AIIR CLI.
• Generates deterministic editor provenance through AIIR: Generate With Provenance, then attaches it to the next local commit receipt.
• Automatically detects active AI coding tools (Copilot, Cline, Codeium, Cursor, Continue, Tabnine, and others) and passes only active tools to the CLI so receipts include accurate agent attestation without manual flags.
• Adds AIIR actions directly to the SCM title bar so receipt generation and setup are reachable from the native git workflow.
• Initializes .aiir repository scaffolding from VS Code.
• Installs a managed post-commit hook for automatic recording.
• Can copy the exact CLI install command or open a terminal with the install command ready when setup is still missing.
• Copies a shareable Markdown receipt summary for PRs, chat, or audit notes directly from the tree or command palette.
• Lets you preview that Markdown summary from the receipt viewer before you copy or share it.
• Remembers CLI-dependent actions you started too early and lets you continue them from setup once the workspace is ready.
• Automatically refreshes when local git state changes so the status bar and AIIR views keep up with HEAD, branch, and hook changes.
• Nudges you when a new HEAD commit is still uncovered while an active AI coding tool such as Copilot is detected and managed auto-receipting is not enabled.
• Shows a repository health check for CLI, git, receipts, sidecars, and hook state.
• Prompts for a target repository when repo-scoped commands run from a multi-root workspace without a file context.
• Enforces folder allowlists in multi-root workspaces when isolation is enabled.
• Defaults to strict local-only mode so Hub and other network-backed commands stay disabled until explicitly allowed.
• Surfaces security posture and deployment presets only when you intentionally opt into advanced/admin workflows.
• Supports optional AIIR Hub actions only after you intentionally disable the default local-only posture.

Requirements

• VS Code 1.85 or newer.
• The public aiir CLI installed locally for proof generation, initialization, and managed auto-receipting.
• A git repository if you want to initialize AIIR, generate receipts, or manage the post-commit hook.

Install the CLI with:

pip install aiir

Getting started

1. Open a git repository in VS Code.
2. Run AIIR: Getting Started or AIIR: Commit Status.
3. Start with AIIR: Record Commit Activity to record proof for the current workflow. If an active file supports deterministic provenance, AIIR will use it automatically.
4. Let AIIR route you through CLI install or repository setup only if the repository is not ready yet.
5. Copy the latest receipt summary or verify the result.

If you start a CLI-dependent action before the AIIR CLI is installed, the extension now routes you into setup, remembers what you were trying to do, and can offer to continue once the workspace is ready.

If your repository already contains AIIR receipts, the extension will detect them automatically and populate the Receipts view.

In multi-root workspaces, repo-scoped commands such as generate, initialize, health check, control panel, and auto-receipting will target the active editor's repository when possible, or prompt you to choose one.

Sidebar layout

The AIIR activity bar container uses three focused views:

• Status for a state-driven landing surface that answers two questions: "is AI use being recorded and verified here?" and "what do I do next?"
• Coverage for repository-scoped coverage, current trust cues, and the most relevant next action
• Receipts for grouped commit-centric receipt browsing by repository, including accessible git repositories that do not have receipts yet

The Status view is intentionally compact. Early states show one main message and one primary action. Steady-state repositories show a compact status line plus the latest receipt, while setup internals and advanced tools stay behind deeper surfaces.

The status bar now reflects current-repository coverage as well as workspace totals, including when HEAD is missing proof, so AIIR can nudge the next step without requiring a manual refresh.

When AIIR sees a new uncovered HEAD commit and an active AI tool in the editor, it can prompt the next step directly: record proof now or enable managed auto-receipting for future commits.

The SCM title bar is also contextual now. When HEAD is missing proof, AIIR surfaces Record Commit Activity directly in the native git view, and when an active AI tool is detected without managed automation, it can surface Enable Auto-Receipting there as well.

Receipts View

The Receipts view shows one row per discovered receipt and includes:

• commit subject as the primary label
• short commit identity plus inline badge-style status markers for failed, AI-authored, signed, or CBOR-backed receipts
• grouped sections such as Current HEAD, Needs Attention, Signed Commits, AI Commits, recent commits, and author buckets for older history
• nested subsections for overview, signals, files, artifacts, and provenance

In multi-root workspaces, accessible repositories now appear even when they have no receipts yet, with direct setup, initialize, generate, and health actions in the tree. Selecting a receipt expands a structured index instead of a flat metadata list, so commit details, changed files, artifacts, provenance, branch context, and HEAD alignment are easier to scan. Changed files in the Files subsection are directly openable from the tree, and the full receipt page is now an explicit action rather than the default tree-row click behavior. When the receipt does not include a file list, the explorer can enrich that view from local git history.

The receipt UI distinguishes between AI Involvement and AI Signals Detected. AI Involvement can come from agent attestation, such as the VS Code extension passing --agent-tool copilot, while AI Signals Detected reflects commit-level heuristic evidence stored in ai_attestation.is_ai_authored and signals_detected.

Receipts with deterministic editor-side provenance are also surfaced separately from heuristic-only receipts. In the explorer they appear under Provable Edits, and in the receipt viewer they show an explicit deterministic provenance summary instead of requiring users to inspect raw JSON.

Commands

Core commands

• AIIR: Verify All Receipts refreshes and verifies all discovered receipts.
• AIIR: Show Receipt Summary opens a summary panel with receipt and coverage counts.
• AIIR: Copy Receipt Summary copies a PR-ready Markdown summary for the selected or latest receipt.
• AIIR: Commit Status opens the first-run readiness and setup page with next actions.
• AIIR: Report a Bug opens the public GitHub issue flow with VS Code and extension version details prefilled.

Optional advanced commands

• AIIR: Generate With Provenance
• AIIR: Health Check

These remain available, but they are intentionally de-emphasized so the default story stays centered on setup, record, review, and local trust signals.

Admin and rollout commands

• AIIR: Control Panel
• AIIR: Security Posture
• AIIR: Deployment Presets
• AIIR: Advanced Settings
• AIIR: Manage Repositories
• AIIR: Open Policy File
• AIIR: Edit Policy Targets
• AIIR: Toggle Current Policy Target
• AIIR: Sigstore Signing Guide
• AIIR: View Review History
• AIIR: Record Compliance Exception
• AIIR: Export Evidence Pack

These are for rollout, policy, or stricter evidence workflows. Most individual developers should not need them on day one.

Automation commands

• AIIR: Enable Auto-Receipting installs or updates a managed post-commit hook.
• AIIR: Disable Auto-Receipting removes the managed AIIR hook block.

After AIIR: Record Commit Activity, the extension now offers immediate next steps: open the proof, copy a PR-ready Markdown summary, or enable managed auto-receipting when the repository is still manual-only.

AIIR: Generate With Provenance is the lowest-friction way to get deterministic editor-side provenance into receipts without asking users to manually assemble CLI flags or queue files.

The receipt viewer now includes Copy Receipt Summary and Preview Receipt Summary actions, so the share-ready output is visible from the place where you inspect the receipt.

CLI-dependent flows such as Record Commit Activity, Initialize Repository, and Enable Auto-Receipting now hand off to setup instead of failing immediately when the CLI is missing, and AIIR can offer to resume the original action once setup is complete.

Optional Hub commands

Hub integration is optional. The extension starts in local-only mode, so these commands stay disabled until you intentionally allow network-backed features.

• AIIR: Hub Plans and Access
• AIIR: Connect to Hub
• AIIR: Disconnect from Hub
• AIIR: Hub Status
• AIIR: Verify Receipt in Hub
• AIIR: Hub Latest Report
• AIIR: Hub Evidence Pack
• AIIR: Run Hub Attestation
• AIIR: Open Hub Dashboard
• AIIR: Sign Up for Hub

Settings

The extension contributes the following settings:

• aiir.cliPath: path to the aiir executable. Default: aiir.
• aiir.agentModelHint: optional declared model class written into local receipt agent attestation when generating receipts from VS Code.
• aiir.autoReceiptArgs: arguments passed to the managed post-commit hook. Default: ['--pretty'].
• aiir.commitExplorerLimit: number of recent commits to show in Coverage.
• aiir.listener.enabled: off by default. If enabled, AIIR records passive file-level provenance in .aiir/editor_provenance.jsonl while active AI tools edit files in this workspace.
• aiir.showAdvancedCommands: show advanced operator commands directly in the command palette. Default: false.
• aiir.provenanceRetainPrompts: off by default. If enabled, raw prompt text may be written to disk and can contain secrets, proprietary code, or personal data.

Advanced rollout and local-only settings:

• aiir.enforceWorkspaceIsolation: when true, multi-root auto-discovery is limited to aiir.allowedWorkspaceFolders. Default: false.
• aiir.allowedWorkspaceFolders: folder names or absolute paths that AIIR may inspect in the current workspace.
• aiir.strictLocalOnly: when true (default), Hub and other network-backed commands are disabled.
• aiir.hubBaseUrl: base URL for optional AIIR Hub API calls. Ignored while aiir.strictLocalOnly remains enabled.
• aiir.hubTenantId: tenant identifier used for Hub requests. Ignored while aiir.strictLocalOnly remains enabled.
• aiir.hubSignupEndpoint: endpoint used by the built-in Hub signup flow. Ignored while aiir.strictLocalOnly remains enabled.
• aiir.lockPreset: optional preset lock. When set, covered settings stay read-only until aiir.lockPreset is cleared.

Hardening

Recommended posture for mixed-sensitivity environments:

• Keep aiir.strictLocalOnly enabled unless you explicitly need Hub features.
• In multi-root workspaces, set aiir.allowedWorkspaceFolders to the exact repositories AIIR may inspect.
• The recommended multi-root baseline is to initialize all accessible repositories with the Baseline workspace policy, which creates blank ledgers for each repository and records every open workspace target in .aiir/policy.json so advanced users can disable individual repositories later.
• Prefer opening public and sensitive repositories in separate VS Code windows even with isolation enabled.

The Status view shows the selected repository's current policy-target state and includes a one-click action to enable or disable the current repository. Advanced Settings lists the enabled and disabled workspace targets currently recorded in .aiir/policy.json, and you can change those targets directly from the extension with AIIR: Edit Policy Targets.

Operational docs now live under extensions/vscode/docs/.

• Threat model: extensions/vscode/docs/operations/THREAT_MODEL.md
• Smoke test checklist: extensions/vscode/docs/operations/SMOKE_TEST.md
• Admin rollout guide: extensions/vscode/docs/operations/ADMIN_DEPLOYMENT.md

If you are onboarding, testing a package, or preparing a rollout, start with the three operational docs above.

Optional rollout controls

Recommended order for a staged rollout:

1. Install the VSIX and open AIIR: Commit Status.
2. Apply a preset from AIIR: Deployment Presets.
3. Confirm local-only mode and allowlists in AIIR: Security Posture.
4. Use the walkthrough for repository initialization and first receipt generation.

Support

• Use AIIR: Report a Bug from the command palette or the AIIR surfaces to open the public GitHub issue flow with extension environment details prefilled.
• You can also report issues directly at https://github.com/invariant-systems-ai/aiir/issues.

AI tool detection

The extension scans for active AI coding extensions on every receipt generation and auto-receipting hook invocation. Detected tools are passed as --agent-tool and --agent-context flags so each receipt records which AI assistants were present at commit time.

If you want local receipts to declare a specific model class as well, set aiir.agentModelHint.

Currently detected extensions include GitHub Copilot, Cline, Codeium, Cursor, Continue, Tabnine, Amazon Q, Sourcegraph Cody, Supermaven, Blackbox AI, AskCodi, Bito, and Pieces. The commit status and health check views also show which AI tools are currently active.

Health check

The health check view reports whether the workspace has:

• an available AIIR CLI
• a git repository
• .aiir scaffolding
• receipt ledger and index files
• policy file presence
• managed or custom post-commit hook state
• receipt coverage for HEAD
• CBOR and Sigstore sidecar coverage
• detected AI coding tools
• optional Hub connectivity state

Development

From extensions/vscode:

npm install
npm test
npm run test:extension-host
npm run package

The package build emits a .vsix artifact in this directory. Contributor-facing release and operations notes live under extensions/vscode/docs/.

Notes

• Receipt generation and initialization depend on the external AIIR CLI. Verification of existing receipt JSON files works inside the extension.
• Hub functionality is optional and remains inactive unless you disable strict local-only mode and configure Hub settings.
• The extension shares the same public brand mark as invariantsystems.io: the packaged Marketplace icon is sourced from the website shield badge, and the activity bar uses a monochrome variant of that same infinity-eyes and checkmark-mouth mark for small-size legibility.
• The packaged extension excludes development-only files through .vscodeignore so release artifacts stay small.