aioengine

AI change control for developers using AI coding tools.

aioengine helps you review AI-generated code before you trust it. It scans your repo for missing guardrails, saves repo snapshots, checks changed files for risky edits, flags when AI may have wandered outside the requested task, and can comment directly on GitHub pull requests with a change-control report.

Quick start

Run a local setup check:

npx aioengine@latest check

Set up local guardrails and GitHub pull request comments:

npx aioengine@latest init --github

Save a repo snapshot before AI changes code:

npx aioengine@latest snapshot

After your AI coding tool makes changes, check whether the changes stayed in scope:

npx aioengine@latest scope "example: update landing page headline" --profile <profile>

Profiles: ui, docs, cli, ci, backend, marketing

Then review risky files before committing:

npx aioengine@latest review

Save a local Markdown report for review:

npx aioengine@latest ci --report aioengine-report.md

Open a pull request. aioengine will run in GitHub Actions and comment directly on the PR with a change-control report.

Commands

npx aioengine@latest check
npx aioengine@latest init
npx aioengine@latest init --github
npx aioengine@latest snapshot
npx aioengine@latest snapshot --name checkpoint
npx aioengine@latest scope "example: update landing page headline"
npx aioengine@latest scope "example: update landing page headline" --profile <profile>
npx aioengine@latest review
npx aioengine@latest ci
npx aioengine@latest ci --profile ci
npx aioengine@latest ci --report aioengine-report.md
npx aioengine@latest rules

Why aioengine exists

AI coding tools can move fast, but review becomes the bottleneck.

A simple prompt can lead to unexpected changes in sensitive files like auth, billing, database migrations, environment config, deployment settings, dependency files, or CI workflows.

aioengine helps answer:

• Did AI touch sensitive files?
• Did AI change files outside the task?
• Did AI add or modify dependencies?
• Does this repo have AI coding rules?
• What changed since the last repo snapshot?
• What should I review before committing or merging?

aioengine check

Scans your repo for AI coding setup risks.

Run:

npx aioengine@latest check

Checks for:

• Git repo
• package.json
• .aioengine/config.json
• .gitignore
• env files
• Claude rules
• Cursor rules
• MCP config
• GitHub Actions
• tests

aioengine init

Sets up aioengine in your repo.

Run:

npx aioengine@latest init

Creates missing files only:

.aioengine/config.json
CLAUDE.md
.cursor/rules/aioengine.mdc

aioengine will not overwrite an existing CLAUDE.md.

If CLAUDE.md already exists, aioengine leaves it untouched and saves suggested rules to:

.aioengine/suggested-claude-rules.md

On Windows, Git may show LF/CRLF line-ending warnings when committing. These are normal and do not mean aioengine failed.

aioengine init --github

Sets up aioengine local guardrails and a GitHub Actions workflow for PR checks.

Run:

npx aioengine@latest init --github

Creates missing files only:

.aioengine/config.json
CLAUDE.md
.cursor/rules/aioengine.mdc
.github/workflows/aioengine.yml
.gitignore

The generated workflow runs aioengine on pull requests, writes a Markdown report, uploads the report as an artifact, and comments directly on the PR.

aioengine will not overwrite an existing:

.github/workflows/aioengine.yml

GitHub pull request comments

When you run:

npx aioengine@latest init --github

aioengine creates a GitHub Actions workflow. On pull requests, aioengine runs automatically and comments directly on the PR with a change-control report.

Example passing report:

# aioengine CI Report

**Status:** Passed
**Environment:** GitHub Actions
**Task:** Update landing page headline
**Detected task type:** UI / frontend task

## Summary

- Changed files: 1
- Possible scope drift: 0
- Risky files: 0

## Changed files

- [OK] `src/app/page.tsx`

## Recommendation

No obvious AI change-control issues were detected.

Example scope drift report:

# aioengine CI Report

**Status:** Review required
**Environment:** GitHub Actions
**Task:** Update landing page headline
**Detected task type:** UI / frontend task

## Summary

- Changed files: 2
- Possible scope drift: 1
- Risky files: 1

## Changed files

- [OK] `src/app/page.tsx`
- [SCOPE DRIFT] `supabase/migrations/add-policy.sql` — possible scope drift

## Recommendation

Review these changes before merging. aioengine detected possible scope drift.

By default:

• possible scope drift fails the CI check
• risky files warn but do not fail the CI check
• a Markdown report is uploaded as a workflow artifact
• the same report is posted as a PR comment

Scope profiles

aioengine can automatically guess the task type from your task description, but you can also set it manually.

Use --profile when you already know what kind of change AI was supposed to make:

npx aioengine@latest scope "example: update landing page headline" --profile ui
npx aioengine@latest scope "example: update README docs" --profile docs
npx aioengine@latest scope "example: add CLI command" --profile cli
npx aioengine@latest scope "example: update GitHub Actions workflow" --profile ci
npx aioengine@latest scope "example: add API route" --profile backend
npx aioengine@latest scope "example: update landing page" --profile marketing

Available profiles:

ui - app pages, components, site config, and public assets
docs - README files, markdown docs, and written documentation
cli - aioengine CLI code, package files, and CLI behavior
ci - GitHub Actions and workflow changes
backend - API routes, backend logic, database, auth, and server-side config
marketing - mixed marketing site + docs changes, such as landing page copy and README updates

Profiles help aioengine judge whether changed files make sense for the task. If a PR mixes multiple task types, aioengine may flag scope drift. That is intentional: smaller, focused AI-assisted changes are easier to review safely.

For example, this command tells aioengine the expected change is frontend/UI work:

npx aioengine@latest scope "example: update dashboard header" --profile <profile>

If AI also changed database migrations, billing files, or GitHub workflows, aioengine can flag those files as possible scope drift.

aioengine snapshot

Saves a repo snapshot with Git HEAD, tracked file hashes, and key project context.

Run:

npx aioengine@latest snapshot

Creates:

.aioengine/snapshots/latest.json

You can also name a snapshot:

npx aioengine@latest snapshot --name checkpoint

Creates:

.aioengine/snapshots/checkpoint.json

Snapshots include:

• Git HEAD
• current branch
• dirty working tree status
• tracked file hashes
• package.json context
• guardrail file status
• GitHub workflow context
• lockfile status

Snapshot JSON files are ignored by default so they do not get committed accidentally.

Use snapshots before letting AI make larger changes, so you have a clean record of the repo state before the edit.

aioengine scope

Checks whether changed files match the task you gave your AI coding tool.

Run:

npx aioengine@latest scope "example: update landing page headline"

Or manually set the expected profile:

npx aioengine@latest scope "example: update landing page headline" --profile <profile>

If the task sounds like a UI change but AI modified billing, database, env, dependency, CLI, or deployment files, aioengine will flag possible scope drift.

aioengine review

Reviews current uncommitted changes for risky files.

Run:

npx aioengine@latest review

aioengine will flag changes to files that often deserve extra review, such as:

• env files
• auth files
• billing files
• database files
• deployment config
• dependency files
• GitHub workflow files

aioengine ci

Runs aioengine checks in CI or pull request workflows.

Run:

npx aioengine@latest ci

Or pass a task manually:

npx aioengine@latest ci --task "example: update landing page headline"

Use a manual profile:

npx aioengine@latest ci --task "example: update GitHub Actions workflow" --profile <profile>

Write a Markdown report:

npx aioengine@latest ci --report aioengine-report.md

In GitHub Actions, aioengine tries to detect the task from the pull request title, event payload, or AIOENGINE_TASK.

Example GitHub Actions workflow

aioengine init --github can create this automatically:

name: aioengine

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]
  workflow_dispatch:

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  ai-change-control:
    name: AI change control
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Set up Node
        uses: actions/setup-node@v6
        with:
          node-version: 24
          package-manager-cache: false

      - name: Run aioengine
        run: npx aioengine@latest ci --report aioengine-report.md

      - name: Comment aioengine report on PR
        if: always() && github.event_name == 'pull_request'
        env:
          GH_TOKEN: ${{ github.token }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          REPO: ${{ github.repository }}
        run: gh pr comment "$PR_NUMBER" --repo "$REPO" --body-file aioengine-report.md --edit-last --create-if-none

      - name: Upload aioengine report
        if: always()
        uses: actions/upload-artifact@v6
        with:
          name: aioengine-report
          path: aioengine-report.md

aioengine rules

Generates starter AI coding rules for Claude Code and Cursor.

Run:

npx aioengine@latest rules

Creates missing files only. aioengine will not overwrite an existing CLAUDE.md.

If CLAUDE.md already exists, suggested Claude rules are saved to:

.aioengine/suggested-claude-rules.md

This command creates or skips:

CLAUDE.md
.cursor/rules/aioengine.mdc
.aioengine/suggested-claude-rules.md

Example workflow

npx aioengine@latest init --github
npx aioengine@latest check

# Recommended: create a branch before larger AI-assisted changes,
# especially if you want GitHub PR comments.
git checkout -b branch-name

# Save the current repo state before AI edits.
npx aioengine@latest snapshot --name checkpoint

# Ask your AI coding tool to make a focused change.

# Check whether the changed files match the task.
npx aioengine@latest scope "example: update landing page headline" --profile <profile>

# Review risky files before committing.
npx aioengine@latest review

# Save a local Markdown report.
npx aioengine@latest ci --report aioengine-report.md

# If everything looks good, commit the focused diff.
git add .
git commit -m "Describe the focused change"

# Open a pull request.
# aioengine will run in GitHub Actions and comment with a report.

Security notes

aioengine is read-only by default.

It does not:

• run AI-generated shell commands
• start a local server
• connect to a CRM
• expose localhost ports
• collect code or secrets
• upload your source code to an aioengine server

Snapshots are saved locally inside your repo under:

.aioengine/snapshots/

Snapshot files contain file hashes and project context, not full source code contents.

The generated GitHub workflow uses limited permissions so it can read the repository, run the check, upload a report artifact, and comment on pull requests.

Early feedback

aioengine is early and intentionally opinionated.

If you try it, feedback is welcome in GitHub Issues. Helpful feedback includes:

• what AI coding tool you used
• whether setup was confusing
• whether aioengine flagged the right files
• false positives or missed risky changes
• what command output was unclear
• what would make this useful in a real project

Please open an issue for bugs, confusing output, false positives, or feature requests.

https://github.com/oliviaheninger-ux/aioengine/issues

Current status

aioengine is in early development.

The first goal is simple: help AI-assisted developers catch risky or out-of-scope changes before committing or merging code.

Future goals include:

• better risk detection
• snapshot comparison
• prettier local reports
• custom rules
• saved reports
• team policies
• dashboard history
• paid CI features

License

MIT