Documentation

Quick Start

Receipt your last commit in 10 seconds:

pip install aiir
cd your-repo
aiir --pretty

That's it. Zero dependencies. Python 3.9+. Apache 2.0.

Three Interfaces

One tool, three ways to use it. Same cryptographic core underneath.

💻 CLI

Receipt commits from your terminal:

# Receipt the last commit
aiir --pretty

# Receipt a whole PR branch
aiir --range origin/main..HEAD --pretty

# Only AI-authored commits
aiir --ai-only --output .receipts/

# Pipe to jq
aiir --range HEAD~5..HEAD --jsonl | jq .receipt_id

# Verify a receipt
aiir --verify receipt.json

⚙️ GitHub Action

One YAML file. Every push and PR gets a receipt, uploaded as a build artifact:

# .github/workflows/aiir.yml
name: AIIR
on: [push, pull_request]

jobs:
  receipt:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: invariant-systems-ai/aiir@v1

🤖 MCP Tool

Any MCP-aware AI assistant — Claude, Copilot, Cursor — discovers and uses AIIR automatically. Add to your MCP config:

{
  "mcpServers": {
    "aiir": {
      "command": "aiir-mcp-server",
      "args": ["--stdio"]
    }
  }
}

Now your AI generates receipts after writing code. Zero friction.

What It Detects

AIIR scans commit metadata for AI-involvement signals using heuristic_v1:

Receipt Format

Each receipt is a content-addressed JSON document. The receipt_id is derived from SHA-256 of the canonical JSON — change any field and the hash breaks:

{
  "type": "aiir.commit_receipt",
  "schema": "aiir/commit_receipt.v1",
  "version": "1.0.0",
  "commit": {
    "sha": "c4dec85630232666aba81...",
    "author": { "name": "Jane Dev", "email": "jane@example.com", "date": "2026-03-07T09:45:00-05:00" },
    "committer": { "name": "Jane Dev", "email": "jane@example.com", "date": "2026-03-07T09:48:00-05:00" },
    "subject": "feat: add receipt generation to CI",
    "message_hash": "sha256:e3b0c44298...",
    "diff_hash": "sha256:b2c1d4e5f6...",
    "files_changed": 4,
    "files": ["src/ci.py", "tests/test_ci.py", ".github/workflows/aiir.yml", "README.md"]
  },
  "ai_attestation": {
    "is_ai_authored": true,
    "signals_detected": ["message_match:co-authored-by: copilot"],
    "signal_count": 1,
    "detection_method": "heuristic_v1"
  },
  "provenance": {
    "repository": "https://github.com/example/repo",
    "tool": "https://github.com/invariant-systems-ai/aiir@1.0.0",
    "generator": "aiir.cli"
  },
  "receipt_id": "g1-a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4",
  "content_hash": "sha256:7f3a8b2c1d...",
  "timestamp": "2026-03-07T14:48:59Z"
}

Sigstore Signing

Unsigned receipts are tamper-evident — anyone can detect changes, but anyone who re-runs aiir can recreate a matching receipt. For cryptographic non-repudiation, enable Sigstore keyless signing:

# Install signing support
pip install aiir[sign]

# Sign in CI
- uses: invariant-systems-ai/aiir@v1
  with:
    output-dir: .receipts/
    sign: true

Each signed receipt gets an accompanying .sigstore bundle:

• Fulcio certificate — short-lived cert proving the signer's OIDC identity
• Rekor transparency log — tamper-evident public record
• Signature — cryptographic binding to the receipt content

Verify locally:

aiir --verify receipt.json --verify-signature

GitHub Action Reference

Inputs

Outputs

Example: PR Comment

- uses: invariant-systems-ai/aiir@v1
  id: receipt
  with:
    output-dir: .receipts/

- name: Comment on PR
  if: steps.receipt.outputs.ai_commit_count > 0
  uses: actions/github-script@v7
  with:
    script: |
      const count = '${{ steps.receipt.outputs.ai_commit_count }}';
      const total = '${{ steps.receipt.outputs.receipt_count }}';
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: `🔐 **AIIR**: ${total} commits receipted, ${count} AI-authored.`
      });

Example: Enforce Receipt Policy

- uses: invariant-systems-ai/aiir@v1
  id: receipt

- name: Enforce receipt policy
  if: steps.receipt.outputs.ai_commit_count > 0
  run: |
    echo "✅ ${{ steps.receipt.outputs.ai_commit_count }} AI commits receipted"

Ready to start?

One command. Zero dependencies. Apache 2.0.