Deterministic Iterative Agent Loop
A Rust library and CLI for autonomous AI-assisted software development. Persistent memory. Failure pattern detection. Structured task execution. Build entire projects iteratively without losing context or repeating mistakes.
Quick Start · Getting Started · Project Wizard · Why Specs Matter · Templates · Manual Workflow · Library · CLI Reference · AI Integration
The Problem
When you use AI coding assistants (Claude Code, Codex, Gemini, GitHub Copilot, Cursor) to build software iteratively, they hit predictable failure modes:
- Context window exhaustion - conversation history grows until the AI loses track of what it already built
- Reasoning loss between loops - decisions made 10 iterations ago are forgotten
- Duplicate implementation - the AI rewrites code that already exists
- Placeholder code - incomplete implementations with TODO comments
- Cascading failures - one error triggers increasingly desperate "fixes" that break more things
- Specification drift - the implementation diverges from requirements as the AI stops referencing them
DIAL solves these by externalizing memory to SQLite, linking tasks to specifications, detecting failure patterns automatically, building a trust-scored solution database, and enforcing one-task-at-a-time discipline.
Architecture
DIAL is structured as a Rust workspace with three crates:
dial/
├── dial-core/ # Library crate — Engine, events, providers, persistence
├── dial-cli/ # Binary crate — CLI interface
└── dial-providers/ # Provider implementations (Claude, Codex, etc.)
The core library (dial-core) is embeddable — you can build custom tools, dashboards, or CI integrations on top of it. The CLI is one consumer of the library.
The Loop
dial iterate
|
Get next task
|
Gather context from DB
(linked spec, related specs,
trusted solutions, learnings)
|
AI implements the task
|
dial validate
/ \
Pass Fail
| |
Git commit Record failure
Next task Detect pattern
Find solutions
Retry (max 3)
Quick Start
Install
Choose one install method. DIAL is a global CLI: install it once for your user or machine, then use it in any project directory. The .dial/ folder that appears later is per-project working data, not the program install location.
Pre-built binaries (no Rust required):
# macOS (Apple Silicon)
|
# macOS (Intel)
|
# Linux (x86_64)
|
# Linux (ARM64)
|
npm (requires Node.js 18+):
This installs the global dial command and downloads the matching prebuilt binary for your platform from the GitHub release for the current npm package version.
Windows: Download dial-x86_64-pc-windows-msvc.zip from the latest release, extract dial.exe into a permanent folder, and add that folder to your user PATH. See Getting Started for step-by-step Windows instructions and a plain-language explanation of PATH.
Via Cargo (requires Rust 1.70+):
From source:
On Windows, the compiled binary is target\\release\\dial.exe. The binary is fully self-contained with no runtime dependencies.
Upgrade or Remove DIAL
Once DIAL is installed, you can let DIAL manage the CLI install itself:
dial upgrade detects how DIAL was installed:
- Cargo install: runs the equivalent of
cargo install dial-cli --force - npm install: runs the equivalent of
npm install -g @victorysightsound/dial-cli - direct binary install: downloads the matching release asset and replaces the current binary
dial uninstall removes the CLI itself but leaves every project's .dial/ directory alone.
On Windows, dial upgrade and dial uninstall may open a follow-up console window and finish there after the current dial process exits. That avoids the normal locked-.exe problem on Windows.
Project Wizard
The fastest way to start a project. One command walks you from zero to autonomous iteration through 9 AI-guided phases:
The wizard can run through codex, claude, copilot, gemini, or an OpenAI-compatible API. If DIAL can detect the current agent session, it uses that backend automatically. Otherwise, pass one explicitly:
The wizard is guided by default. You do not need to craft a special AI prompt for each phase; DIAL sends structured prompts internally and explains what it is doing as it moves through the flow.
Current release verification covers fresh macOS wizard runs with Codex and Copilot, native Windows wizard runs with Codex and Copilot, native Windows existing-repo dial new plus dial auto-run --cli codex end-to-end validation against the mini-note-formatter fixture scenario, and agent-file mode validation on both macOS and Windows.
For wizard and auto-run use, make sure the selected backend CLI is installed, on your PATH, and already authenticated before you start.
The wizard works in both of these common setups:
- brand-new repo: start in an empty repo and let DIAL generate the PRD, tasks, build/test commands, and iteration mode
- existing repo: run from the repo root and pass
--fromwith an existing PRD, spec, or architecture doc so the wizard can refine what you already know about the codebase
| Phase | Name | What Happens |
|---|---|---|
| 1 | Vision | AI identifies the problem, target users, success criteria |
| 2 | Functionality | AI defines MVP features, deferred features, user workflows |
| 3 | Technical | AI covers architecture, data model, integrations, constraints |
| 4 | Gap Analysis | AI reviews everything for gaps, contradictions, missing details |
| 5 | Generate | AI produces structured PRD sections, terminology, and initial tasks |
| 6 | Task Review | AI reorders tasks, adds dependencies, assigns task acceptance criteria, and flags UI work that needs manual browser verification |
| 7 | Build & Test | AI suggests build/test commands and validation pipeline based on tech stack |
| 8 | Iteration Mode | AI recommends how to run: autonomous, review every N tasks, or review each |
| 9 | Launch | Prints summary of everything configured, ready for dial auto-run |
Some later phases can be quiet for a bit, especially with CLI-backed providers on Windows. That is normal. The wizard will keep reporting where it is in the flow, and you can safely stop and resume later.
Agent file handling defaults to local: DIAL creates AGENTS.md for local AI tooling and hides it from git status with .git/info/exclude. Use --agents shared if you want to commit it intentionally, or --agents off to skip it.
After the wizard completes, start building:
dial auto-run is always a separate explicit step. The wizard never starts autonomous implementation on its own.
Supported auto-run CLIs are claude, codex, copilot, and gemini.
Pause & Resume
Close the terminal at any phase. Pick up where you left off:
State is persisted in prd.db after every phase — nothing is lost.
Refine an Existing Document
Have an existing PRD, spec, or architecture doc? Feed it through the wizard:
The AI extracts information from your document alongside each phase's questions.
If you are planning inside an existing code repository, run the wizard from that repository's root. The best results come from pairing the repo with a document that describes the intended behavior instead of expecting the wizard to infer the whole architecture from source alone.
Iteration Modes
Phase 8 configures how auto-run behaves:
| Mode | Config Value | Behavior |
|---|---|---|
| Autonomous | autonomous |
Run all tasks, commit on pass, no stops |
| Review every N | review_every:N |
Pause for review after every N completed tasks |
| Review each | review_each |
Pause after every task for approval |
When paused, resume with dial approve or stop with dial reject.
Templates
Templates define the section structure the AI follows when generating your PRD. Pick the one that matches what you're building:
spec — General Product Requirements
Best for: products with clear functional requirements and acceptance criteria.
Problem Statement → Requirements (Functional, Non-Functional) → Features → Data Model → Constraints → Acceptance Criteria
architecture — System Architecture
Best for: system design documents, multi-service architectures, infrastructure planning.
Overview → Components (Interactions) → Data Model → Integrations → Deployment → Security
api — API Specification
Best for: REST/GraphQL APIs, microservices, developer-facing products.
Overview → Authentication → Endpoints (Resources, Actions) → Data Types → Error Handling
mvp — Minimum Viable Product
Best for: quick prototypes, hackathons, getting something working fast.
Problem → MVP Features → Technical Stack → Data Model
The template determines what sections the AI generates in phase 5 and what structure tasks are linked to. You can always add more sections manually after the wizard completes.
Why Specs Matter
Without a spec, DIAL assembles context from learnings, solutions, and failures — useful, but the AI has no requirements to validate against. With a spec:
- Each task carries what to build alongside how previous attempts went
- FTS search surfaces relevant requirements even for unlinked tasks
- Specification drift is prevented because the AI re-reads requirements every iteration
This is the key difference between DIAL and running an AI assistant in a loop. The spec is externalized memory — it ensures the AI re-reads requirements at every iteration instead of relying on conversation history that degrades over time.
Manual Workflow
If you prefer to control each step yourself instead of using dial new:
# 1. Initialize
# 2. Import or create a spec
# 3. Add tasks
# 4. Run
# or
dial spec wizard runs phases 1-5 only (PRD generation). Use dial new for the full 9-phase flow.
Querying the PRD
Library Usage
Add dial-core to your Cargo.toml:
[]
= "4.2"
= { = "1", = ["full"] }
Basic Example
use ;
use Arc;
;
async
See dial-core/examples/ for more: custom providers, event handlers, and validation pipelines.
Features
Task Management
Specification & PRD
Configurable Validation Pipeline
Steps run in order. Required steps abort on failure. Optional steps log and continue.
Approval Gates
Tasks can now carry explicit acceptance criteria and an optional manual browser-verification gate. When a task requires a UI check, dial validate and dial auto-run stop after local validation until you record the manual check with dial task verify-browser ....
Failure Pattern Detection
DIAL categorizes build/test errors into 21 patterns across 5 categories (import, syntax, runtime, test, build). When a failure recurs, DIAL surfaces previously successful solutions.
Trust-Scored Solutions
Solutions start at 0.3 confidence. Success adds +0.15; failure subtracts -0.20. Solutions at 0.6+ are "trusted" and automatically included in context.
Metrics & Trends
dial progress renders a readable task ledger plus the most recent iteration outcomes. DIAL also keeps matching artifact files in .dial/ so you can inspect progress without querying the database directly.
Project Health Score
Six weighted factors: success rate, success trend, solution confidence, blocked task ratio, learning utilization, and pattern resolution rate. Trend detection compares current score vs 7 days ago.
Dry Run / Preview Mode
Shows context items included/excluded with token sizes, prompt preview, suggested solutions, and dependency status — without creating iteration records or spawning subagents.
Cross-Iteration Failure Tracking
Tasks track total_attempts and total_failures across all iterations. Auto-run auto-blocks tasks exceeding max_total_failures (default: 10).
Per-Pattern Metrics
Checkpoint System
Automatic git stash-based checkpoints before task execution. On validation failure, the working tree is restored to pre-task state before retry. Controlled via enable_checkpoints config (default: true).
Structured Subagent Signals
Subagents write .dial/signal.json with typed signals (Complete, Blocked, Learning) instead of printing DIAL_ lines to stdout. Falls back to regex parsing for backward compatibility.
Transaction Safety
All multi-step database mutations (record_failure, task_done, iterate, prd_import) are wrapped in BEGIN IMMEDIATE transactions with automatic rollback on error.
Crash Recovery
Project Learnings
Learnings are auto-linked to failure patterns when recorded during an iteration with failures.
Project Structure
your-project/
├── .dial/
│ ├── mvp.db # Engine state (tasks, iterations, failures, solutions)
│ ├── prd.db # PRD database (sections, terminology, wizard state)
│ ├── current_phase # Active phase name
│ ├── current_context.md # Latest context (auto-generated)
│ ├── subagent_prompt.md # Latest sub-agent prompt (auto-generated)
│ ├── progress.md # Human-readable iteration journal
│ ├── patterns.md # Stable codebase patterns and trusted solutions
│ └── task-ledger.md # Human-readable task queue summary
├── specs/ # Original source documents (stay intact)
│ └── PRD.md
└── ... your project files
Performance
| Metric | Value |
|---|---|
| Startup time | ~14ms |
| Binary size | ~4MB |
| Dependencies | None (static binary) |
| Database | SQLite with WAL mode + FTS5 |
License
MIT OR Apache-2.0 — see LICENSE-MIT and LICENSE-APACHE.
Copyright and Branding
Copyright (c) 2026 Victory AV, LLC.
DIAL is authored and maintained by John Deaton / Victory AV, LLC. The repository's open-source licenses grant rights to the code under their stated terms, but they do not grant trademark or branding rights beyond what applicable law otherwise allows.
If you redistribute DIAL or publish modified versions, preserve the copyright and license notices and do not use the DIAL name, logos, or branding in a way that suggests endorsement, affiliation, or official upstream status without written permission.
See NOTICE.