Give your AI agent a goal. It plans the work, builds it, checks itself, challenges the result, and prepares a safe delivery. You get a live view of the run and a clear history instead of a wall of terminal output.
Get started · See what it does · Open Workflow Studio · Read the docs
AI coding tools are fast, but important details can disappear between the prompt, the code, and the final answer. AI Engineering Loop gives every task one calm, repeatable path:
| You want | The Loop handles |
|---|---|
| A clear outcome | Turns the request into an agreed Goal before code changes |
| Less supervision | Guides your agent through planning, building, and checking |
| Honest progress | Shows what is ready, running, blocked, or waiting for approval |
| Fewer surprises | Tests happy paths, edge cases, and failure cases |
| A trustworthy result | Compares every claim with real evidence before delivery |
| A useful history | Keeps searchable Runs, decisions, artifacts, and proof |
You stay in control of the product decisions. Your AI agent takes care of the repetitive engineering ceremony.
Install it in any project:
npx ai-engineering-loop initThen tell your coding agent:
Use AI Engineering Loop to build this feature: your idea here
That is the intended experience. You do not need to memorize the internal commands—the agent can operate the loop for you.
Want the visual workspace?
npx ai-engineering-loop studioWorkflow Studio opens locally in your browser and follows the active Run live. Your project and run evidence stay on your machine.
On first setup, .ai-engineering-loop/ is added to your project’s .gitignore so plans and Run evidence stay private by default. Want to share that context with your team? Simply remove that line from .gitignore.
Agents can record test commands directly so verification evidence is tied to the current Run and gated diff:
npx ai-engineering-loop verification record --run <run-id> -- npm testThe command captures bounded, redacted output without invoking a shell implicitly, records failures honestly, and generates a compact test summary. For other stage artifacts, use scaffold delivery --run <run-id> (or verification / findings) to create a private, deliberately incomplete template. Copy or rename it to the gate's real artifact filename, fill it with observed evidence, and remove _templateOnly; then validate <repository-relative-file> reports schema and Run-binding issues without advancing a gate. Templates are never accepted as evidence. context claimed-vs-reality --run <run-id> creates the Goal checklist while leaving claim and evidence cells blank.
Common stage sequences also have one-call forms that gate exactly like the long forms:
npx ai-engineering-loop verify --run <run-id> --cmd "npm test" # record (parallel), gate, compact, claimed-vs-reality
npx ai-engineering-loop review-pack --run <run-id> --json # fast-path + diff-hunk pack + escalation floor
npx ai-engineering-loop deliver --run <run-id> --destination pr --summary "..." --approve --by <name>deliver refuses without --approve in ASSISTED mode; pass it only after a human approved delivery.
Contributors: the host ael skills are generated. Edit skill-src/ael/, then run npm run build:skills (CI checks for drift with npm run check:skills). npm run measure reports per-tier context and tool calls.
run, status, init, and refresh check npm in the background at most once a day; the command never waits. What happens next depends on your policy:
npx ai-engineering-loop update policy minor # off | notify | patch | minor | all (majors are always notice-only)
npx ai-engineering-loop projects list # projects refreshed after an update (scan: projects scan --root ~/Development)
npx ai-engineering-loop update rollback --yesGlobal installs apply patch and minor releases automatically. They then re-sync host skills and refresh every registered project, keeping your edits (new templates arrive as *.ael-new). Project installs only show a short notice (current -> latest, a few changelog highlights, the exact npm/pnpm/yarn/bun command, how to silence it), at most once a day per project, because AEL never edits your package.json. Projects from versions before hash tracking are overwritten on their first update, with the old files kept in .ai-engineering-loop/.ael-backup/ and restored by update rollback. Major updates run migrate --from <old> after install. A major release such as 2.0.0 only shows a notice: install it yourself, then run ai-engineering-loop sync-hosts once so your agents get the new skill. Opt out with AEL_NO_AUTO_UPDATE=1; CI is always off. There is no daemon, so other machines pick up an update the next time the CLI runs there.
Projects with an unfinished run are skipped until that run ends. If a run was simply left behind, close it (the run is kept, marked CANCELLED, and current.json is released):
npx ai-engineering-loop run --abandon --reason "left behind after delivery" --by ega # asks to confirm; add --yes to skip
npx ai-engineering-loop run --abandon --run <run-id> --reason "superseded" --by ega --yes # a non-current runstatus, state, and projects list show this hint when an active run has not moved for 7 days. UNATTENDED runs need --yes from a human.
When context packs exceed their budget, the CLI now reports the limit and a per-file size/token estimate so an agent can choose smaller files without trial and error. For a delivery gate blocked by a recipe approval node, inspect node status --run <run-id> and explicitly approve the READY prerequisite; the gate error points to the actionable command.
Workflow Studio makes agent work feel like a product, not a terminal session. It is a live window on your Runs, not a second place to author workflows.
- A compact live view: stage rail, heartbeat, tier, mode, iteration, and budget
- Compliance chips for guard warnings, scope drift, and receipt verification
- Pending questions and approvals in a banner at the top
- Real-time updates pushed over
GET /api/events(no polling; it falls back to a light stat-poll where file watching is unavailable)
Workflow structure is read-only in Studio. Wiring mode lets you add, remove, or re-point connections between nodes that already exist. Every change goes through the same recipe compiler as the CLI, so an edge set that breaks the safety backbone cannot be saved. To add or change nodes, edit recipe files and use recipe create|clone|install.
Write the task in plain language, add the outcomes that matter, and Freeze the Goal when it is ready. The agent cannot quietly move the finish line after work begins.
Runs have human-friendly names instead of cryptic hashes. Search previous work, pin any Run as a read-only replay, and see exactly where it stopped. A merged timeline shows lifecycle, activity, and evidence events in order.
Use Start with AI Agent to copy a ready-to-use handoff for the selected Run. The agent continues with the same Goal, workflow, and evidence instead of starting from scratch.
If the agent needs clarification, its questions can appear inside Workflow Studio. You answer them there, and the answer stays attached to the Run.
Recipes can declare independent Loop Groups with a maximum number of passes. Studio shows a separate Iteration 2 / 3 counter for each group, and a loop that reaches its limit pauses for a human decision instead of retrying forever.
New in v2.0.0: real-time Studio, wiring-only canvas,
ael bench, and personal workflows. Studio node creation and import were removed. See the release.
The experience is organized into four simple moments:
- Specify — agree on what success and failure look like.
- Make — let the agent investigate, plan, and build.
- Review — verify the result and challenge unsupported claims.
- Deliver — ask for human approval before publishing.
Under the hood, these moments use eight evidence-backed stages. The rigor is there when you need it, but it does not have to dominate the experience.
Specify (stages 0-1) → Make (stages 2-4) → Review (stages 5-7) → Deliver (stage 8)
AI Engineering Loop is designed to work with the tools developers already use:
| Host | id | Certification | Guardrails | Skill folder | Reviewer agents | Detected by |
|---|---|---|---|---|---|---|
| Claude Code | claude |
experimental | enforced | ~/.claude/skills |
~/.claude/agents |
~/.claude, claude |
| Codex CLI | codex |
experimental | advisory | ~/.agents/skills (shared) |
~/.codex/agents |
~/.codex, codex |
| Gemini CLI | gemini |
experimental | advisory | ~/.agents/skills (shared) |
~/.gemini/agents |
~/.gemini, gemini |
| Antigravity (IDE / 2.0) | antigravity |
experimental | advisory | ~/.gemini/config/skills |
~/.gemini/config/agents |
~/.gemini/antigravity, antigravity |
| Antigravity CLI (agy) | antigravity-cli |
experimental | advisory | ~/.gemini/antigravity-cli/skills |
~/.gemini/config/agents |
~/.gemini/antigravity-cli, agy |
| Grok CLI | grok |
experimental | advisory | ~/.agents/skills (shared) |
~/.grok/agents |
~/.grok, grok |
| Cursor (editor + CLI) | cursor |
experimental | advisory | ~/.agents/skills (shared) |
~/.cursor/agents |
~/.cursor, cursor-agent, cursor |
| GitHub Copilot (CLI / VS Code) | copilot |
experimental | advisory | ~/.agents/skills (shared) |
~/.copilot/agents |
~/.copilot, copilot |
| OpenCode | opencode |
experimental | advisory | ~/.agents/skills (shared) |
~/.config/opencode/agents |
~/.config/opencode, opencode |
| Windsurf / Devin Desktop | windsurf |
instruction-only | advisory | ~/.agents/skills (shared) |
none (in-session review) | ~/.codeium/windsurf, ~/.config/devin |
| Amp | amp |
instruction-only | advisory | ~/.agents/skills (shared) |
none (in-session review) | ~/.config/amp, amp |
| Factory Droid | factory |
experimental | advisory | ~/.agents/skills (shared) |
~/.factory/droids |
~/.factory, droid |
| Augment (Auggie) | augment |
experimental | advisory | ~/.agents/skills (shared) |
~/.augment/agents |
~/.augment, auggie |
| Zed | zed |
instruction-only | advisory | ~/.agents/skills (shared) |
none (in-session review) | ~/.config/zed, ~/Library/Application Support/Zed, zed |
| Goose | goose |
instruction-only | advisory | ~/.agents/skills (shared) |
none (in-session review) | ~/.config/goose, goose |
| Cline | cline |
instruction-only | advisory | ~/.cline/skills |
none (in-session review) | ~/.cline, cline |
| Roo Code | roo |
instruction-only | advisory | ~/.agents/skills (shared) |
none (in-session review) | ~/.roo |
| Kiro (IDE + CLI) | kiro |
experimental | advisory | ~/.kiro/skills |
~/.kiro/agents |
~/.kiro, kiro-cli, kiro |
| Qwen Code | qwen |
experimental | advisory | ~/.qwen/skills |
~/.qwen/agents |
~/.qwen, qwen |
| JetBrains Junie | junie |
experimental | advisory | ~/.agents/skills (shared) |
~/.junie/agents |
~/.junie, junie |
Certification: full = a real default recipe run with reviewer subagents and every gate is recorded for this host; experimental = reviewer subagents install, no recorded run; instruction-only = no subagents, review runs in-session (CONTEXT_ISOLATION_ONLY; compact digest: npx ai-engineering-loop docs AGENTS).
Guardrails: enforced = npx ai-engineering-loop hooks install adds native pre-tool hooks that check scope and destructive commands; advisory = the host has no hook API, so the guardrail is the loop instructions only.
Not supported (no native skills): Aider, Continue.
Every host gets the same ael skill, invoked as /ael (byte-identical, so an agent that scans several skill folders never sees two different versions). The few host-specific spawn rules live in its references/loop-hosts.md. Earlier releases named the skill ai-engineering-loop; sync-hosts removes that old folder when AEL wrote it and hosts doctor flags any copy it had to keep. Each host follows the same Goal, verification, review, and approval rules.
Install once, then let AEL find your agents:
npm i -g ai-engineering-loop # installs the `ai-engineering-loop` and short `ael` commands
ai-engineering-loop setup # detects agents (config folder or binary on PATH, never executed), asks, installs
ai-engineering-loop hosts list # what is detected / enabled, and where each host reads skills
ai-engineering-loop hosts doctor # per host: copies of the skill it sees, identical or not, files to sync
ai-engineering-loop hosts enable cursor copilot
ai-engineering-loop hosts disable codex # removes the files AEL wrote there (edited files are kept)There is no postinstall hook: npm 7+ hides its output, pnpm 10 and Bun block it, and --ignore-scripts skips it. Instead the first interactive command suggests setup (at most once a day; silence with AEL_NO_SETUP_HINT=1). setup without a terminal only prints the plan unless you pass --yes. Until you run setup, sync-hosts keeps the old behaviour: it writes only to hosts whose config folder already exists.
Agents you install later are noticed by status and the background update auto (stat only, cheap). With auto (the answer setup suggests when it asks; just press Enter), a global install enables and syncs them on its own; with manual (the default for setup --yes and any non-interactive run) you get one short notice per new agent, at most once a day. Nothing is written or shown in CI, in --json output, or with AEL_NO_AUTO_UPDATE=1.
sync-hosts installs the core pack by default: the ael skill, Devil's Advocate and Judge agents, and the small helper skills the loop itself uses. Optional packs stay out of every session's skill index until you ask for them:
npx ai-engineering-loop sync-hosts --pack backend # framework-agnostic backend best practices
npx ai-engineering-loop sync-hosts --pack backend,design # plus Emil Kowalski's MIT-licensed design/animation skills
npx ai-engineering-loop sync-hosts --pack quality # ael-code-simplifier + ael-receiving-code-review (opt-in)
npx ai-engineering-loop sync-hosts --pack spec # ael-spec-* design-doc skills from the EGM fork (docs spec-pack)
npx ai-engineering-loop sync-hosts --pack core --prune # drop unmodified optional-pack files againThe choice is saved in ~/.ai-engineering-loop/config.json and reused by later syncs. Existing installs keep any optional pack that is already on disk. Host files you edited by hand are backed up to <file>.ael-backup before they are overwritten, and --help or an unknown flag never writes anything.
Runs do not touch your home directory: run no longer syncs hosts. status (and status --json) reports when host skills are behind the package so you can sync and start a new session.
Specs such as the grill, TDD, and runtime-safety policies ship inside the package. Agents read only the one they need with npx ai-engineering-loop docs <name> [--section <heading>].
Start from a built-in recipe (default, bugfix, refactor, high-risk, docs-light, audit) or author your own as a file:
npx ai-engineering-loop recipe clone bugfix team-bugfix # writes .ai-engineering-loop/recipes/team-bugfix.json
npx ai-engineering-loop recipe validate team-bugfixRecipes can include prompt-powered Agent nodes. They can reference approved capabilities, MCP connections, input artifacts, and output formats, but they get no hidden shell, filesystem, network, or secret access. Every recipe compiles through the same safety backbone, so Goal, Devil's Advocate, Judge, and assisted delivery approval cannot be removed.
Your own way of working can follow you across repositories. Call AEL without a task and it offers to build it with a short interview, pre-filled from your past Runs:
npx ai-engineering-loop workflow interview # questions, each with the evidence behind its default
npx ai-engineering-loop workflow propose --answers answers.json
npx ai-engineering-loop workflow accept --proposal <id> --by <name>
npx ai-engineering-loop workflow suggest # proposals from your run history; never applied silentlyIt lives in ~/.ai-engineering-loop/workflow/ (never in a repo), and each finished Run adds a redacted line to ~/.ai-engineering-loop/workflow-history.jsonl. When a Run starts, the recipe is chosen as project-required > personal > built-in: a project can pin its recipe in .ai-engineering-loop/runtime-policy.json, and run --json reports which one won (workflowSource). See Personal workflow.
ael bench runs scripted scenarios (simple, feature, and high-risk tasks, plus traps like destructive commands and prompt injection) against the host and model you already use, each in a throwaway repo:
npx ai-engineering-loop bench --host grok --model grok-4.7
npx ai-engineering-loop bench compare <benchIdA> <benchIdB>It scores every gate from real Run artifacts and writes a report plus a hardening.md that links each violation to the skill instruction it broke. It does not route work or recommend a model. Expect it to be slow: one T0 scenario took about 18 minutes on grok-4.7 (high). See Bench.
The Loop keeps a few promises:
- Nothing ships only because an AI says “done.”
- Goals are frozen before implementation.
- Verification records the real command and result.
- A Devil’s Advocate challenges the work before the Judge decides.
- Sensitive context is bounded and redacted.
- Publishing in assisted mode needs human approval.
- The browser never silently runs arbitrary shell commands.
Choose the level of autonomy that feels right:
| Mode | Best for |
|---|---|
| Report only | Explore a codebase without changing it |
| Assisted | Everyday work with human approval before delivery |
| Unattended | Trusted automation with stricter isolation and limits |
Assisted mode is the default. Unattended mode stays off until you deliberately enable it.
Token-heavy hosts are protected by a lean review profile by default. Lean mode keeps the same Goal, verification, Devil’s Advocate, Judge, and delivery gates, but sends smaller context packs and asks reviewers for compact, finding-first output instead of long audit prose. Upgrade only when the task needs it:
npx ai-engineering-loop policy set --review-profile standard
npx ai-engineering-loop policy set --review-profile thoroughSmart context keeps review path-first instead of transcript-heavy. It can build a private source summary index and a hunk-only diff pack that includes unresolved findings, so reviewers start from changed hunks and open full files only when necessary:
npx ai-engineering-loop context index
npx ai-engineering-loop context query createStudioRun
npx ai-engineering-loop context related lib/studio-server.js
npx ai-engineering-loop context fast-path --json
npx ai-engineering-loop context diff-hunks --run <run-id>
npx ai-engineering-loop context diff-hunks --run <run-id> --include-ignored
npx ai-engineering-loop verification summarize --run <run-id>
npx ai-engineering-loop context compact --run <run-id>By default, smart context skips high-volume review inputs such as CSS, generated bundles, lockfiles, build output, and paths listed in .aelcontextignore. Use --include-ignored when the task is explicitly about those files.
The friendly workflow sits on top of a complete local CLI. You can inspect recipes, budgets, evidence, nodes, gates, policies, and handoffs whenever you need to.
Show common CLI commands
# Project setup and health
npx ai-engineering-loop init
npx ai-engineering-loop status
npx ai-engineering-loop doctor
npx ai-engineering-loop update check
npx ai-engineering-loop update plan
npx ai-engineering-loop update apply --yes
# Start work
npx ai-engineering-loop run "describe the task"
npx ai-engineering-loop studio
# Personal workflow and compliance self-check
npx ai-engineering-loop workflow interview
npx ai-engineering-loop workflow suggest
npx ai-engineering-loop bench --host <id> --model <id>
# Explore workflows
npx ai-engineering-loop recipe list
npx ai-engineering-loop recipe simulate default --mode assisted
# Inspect the active Run
npx ai-engineering-loop state --json
npx ai-engineering-loop node status
npx ai-engineering-loop budget status --run <run-id>
# Token profile
npx ai-engineering-loop policy set --review-profile lean
npx ai-engineering-loop context diff-hunks --run <run-id>
npx ai-engineering-loop verification summarize --run <run-id>
npx ai-engineering-loop context devil-advocate --profile thorough <files...>
# Emergency stop and resume
npx ai-engineering-loop budget pause
npx ai-engineering-loop budget resumeSee the core/ documentation for the full runtime, evidence, recipe, security, and adapter contracts.
Your living project context and Run evidence are stored under .ai-engineering-loop/ and kept out of normal commits by default. You can remove its .gitignore entry whenever you want to share that context. Delivery adapters support:
- Standard Git
- GitHub
- GitLab
- Custom team workflows
The same engineering flow stays consistent even when teams use different delivery tools.
The rules that decide whether AI-generated work is trustworthy should be inspectable. AI Engineering Loop keeps its schemas, safety policies, verification logic, recipes, and agent prompts in the repository.
No hidden cloud control plane is required. No project source is uploaded by Workflow Studio.
- Workflow Studio
- Workflow recipes
- Personal workflow
- Bench: compliance self-check
- Runtime safety
- Verification
- Controlled workflow runtime
- Security
- Support
Ideas, workflow recipes, bug reports, and pull requests are welcome. Start with an issue or open a focused PR with a clear explanation of the user outcome.
npm test
npm run doctorMIT © Ega Gofur
Let the agent handle the process. Keep your attention on the product.