AIDEV-CLI

A bounded operating layer for AI-assisted software development.

AIDEV-CLI inspects an existing repository, captures project constraints, generates deterministic milestones and tasks, executes work in isolated Git worktrees, selects bounded context and accepted project memory, verifies every change, and synchronizes review state with GitHub.

ai-development · cli · codex · context-engine · memory-engine · orchestration · terminal-ui

Version 2.0.0 adds an application API, read-only MCP gateway, schema-driven intake and planning, controlled multi-agent orchestration, bounded autonomous execution, reusable components, Codex and Claude Code providers, and a visual intake app.

Why AIDEV-CLI

AI coding tools can produce code quickly, but repositories still need durable intent, bounded context, reproducible execution, verification, recovery, and review boundaries.

AIDEV-CLI provides those controls:

• repository files remain canonical;
• tasks run in isolated branches and worktrees;
• context selection is deterministic and token-bounded;
• durable memory is explicit, reviewable, and revisioned;
• verification cannot be skipped;
• repair attempts, time, and tokens are bounded;
• production-risk work requires explicit approval;
• GitHub synchronization is idempotent;
• the runner never merges or deploys.

Install

Requirements:

• Node.js 22 or newer
• Git
• Codex CLI for the default provider, or a compatible custom agent command
• GITHUB_TOKEN or GH_TOKEN for GitHub synchronization

Global installation:

npm install --global @alanarex/aidev-cli
aidev --version

Run without installing globally:

npx @alanarex/[email protected] inspect .

Development checkout:

corepack enable
pnpm install --frozen-lockfile
pnpm verify
pnpm dev -- inspect .

Linux and macOS are supported directly. Windows users should use WSL until native Windows command generation is implemented.

Quick start

# 1. Inspect the repository
aidev inspect .

# 2. Generate the project operating layer
aidev init .

# 3. Validate the generated contract
aidev validate .

# 4. Generate deterministic milestones and tasks
aidev plan .

# 5. Run the next eligible task
aidev run .

# 6. Inspect execution and review state
aidev status .

The primary workflow is:

inspect
  → init
  → validate
  → plan
  → context and memory selection
  → run / run-all
  → verification and bounded repair
  → review
  → GitHub synchronization
  → merge reconciliation

See Getting started for a complete walkthrough.

Structured terminal interface

AIDEV-CLI replaces dense one-line output and default raw object dumps with structured sections, aligned metadata, wrapped values, status symbols, and color-aware presentation.

Example:

Task execution
────────────────────────────────────────

  Task Id       TASK-001
  Status        completed
  Branch        aidev/task-001
  Worktree      .ai-dev/worktrees/task-001

Verification
  Passed        true
  Attempts      1
  Duration Ms   14820

Pull Request
  Number        42
  State         draft

Output modes:

# Automatic: pretty in a TTY, plain when redirected
aidev status .

# Explicit styled terminal output
aidev status . --output-mode pretty

# Multiline output without ANSI escapes
aidev status . --output-mode plain

# Stable machine-readable output
aidev status . --output-mode json
aidev status . --json

Disable color:

aidev status . --no-color
NO_COLOR=1 aidev status .

The renderer is width-aware and switches narrow terminals from horizontal tables to vertical records. Color is never the only status indicator.

See Terminal output contract.

Command map

Project setup and planning

aidev inspect [directory]
aidev init [directory]
aidev validate [directory]
aidev plan [directory]

Initialization detects repository technologies through modular adapters and generates a durable project operating layer without silently overwriting tracked intent.

Planning produces validated milestones and tasks with dependencies, resources, risk, approval, verification, priority, and lifecycle metadata.

Execution and lifecycle

aidev run [directory]
aidev run-all [directory]
aidev queue [directory]
aidev workers [directory]
aidev scheduler-history [directory]
aidev status [directory]
aidev resume <task-id> [directory]
aidev retry <task-id> [directory]
aidev cancel <task-id> [directory]
aidev cleanup [task-id] [directory]
aidev complete <task-id> [directory]
aidev history [directory]
aidev doctor [directory]

Common execution controls:

--agent-command
--profile
--model
--reasoning
--sandbox
--approval
--attempt-timeout-ms
--max-agent-duration-ms
--max-agent-tokens
--context-token-budget
--max-repairs
--dry-run
--no-pr
--keep-worktree
--approve-risk
--base-branch
--json

Each task runs in an isolated branch and worktree. Verification is mandatory. Repair attempts, provider duration, provider tokens, context selection, and concurrency are bounded.

Context Engine

aidev context index [directory]
aidev context status [directory]
aidev context doctor [directory]
aidev context clean [directory]
aidev-context preview <task-id> [directory]

The Context Engine builds a disposable repository index and selects bounded, task-relevant information instead of dumping the repository or replaying conversations.

It indexes summaries, symbols, imports, dependency edges, architecture areas, and nearby tests. Repository rules and source excerpts are bounded and secret-redacted before prompt rendering. Full source files and generated prompts are not persisted in execution state.

Memory Engine

aidev-memory add <title> <content>
aidev-memory list
aidev-memory show <memory-id>
aidev-memory update <memory-id>
aidev-memory accept <memory-id>
aidev-memory reject <memory-id>
aidev-memory archive <memory-id>
aidev-memory retrieve <task-id>
aidev-memory doctor
aidev-memory export
aidev-memory import <file>
aidev-memory migrate

Memory supports deterministic IDs, categories, proposed/accepted/rejected/archived states, confidence, tags, provenance, supersession, immutable revision history, diagnostics, import/export, and schema migration.

Only accepted, active, task-relevant memory enters execution prompts. Generated memory starts as proposed knowledge and requires review.

MCP control gateway

AIDEV 2.0 includes a read-only MCP server for Codex and other STDIO clients:

aidev-mcp --root .
aidev mcp install codex . --dry-run
aidev mcp install codex .

The gateway exposes bounded project, plan, status, context, queue, memory, and execution-history reads. It cannot run tasks or mutate project state, and all project paths must stay inside the configured root.

See MCP gateway for the tool and resource contract.

GitHub integration

aidev github sync-issues [directory]
aidev github reconcile-merges [directory]
aidev github sync-project [directory]

AIDEV-CLI uses Octokit directly. It can create and reuse draft pull requests, synchronize managed issues and labels, reconcile verified merged work, and optionally synchronize GitHub Projects V2.

Tokens are read from the process environment and are not persisted.

Codex provider

Built-in profiles:

• fast: low reasoning for small, low-risk work;
• balanced: medium reasoning and the default profile;
• deep: high reasoning for complex work.

aidev run . --profile deep
aidev run . --model <model>
aidev run . --reasoning high
aidev run . --sandbox workspace-write
aidev run . --approval never
aidev codex doctor .

Custom process-backed providers remain available through --agent-command.

Generated project layer

AGENTS.md
.ai-dev/
├── project.yaml
├── policies.yaml
├── manifest.yaml
├── context.yaml
├── github-project.yaml
├── memory/
│   └── memories.yaml
├── state/
├── worktrees/
└── bin/
    ├── setup
    ├── test
    ├── lint
    ├── build
    └── verify
backlog/
├── milestones.yaml
└── tasks.yaml

Tracked project intent and accepted durable knowledge remain repository files. Runtime execution state, scheduler history, derived context indexes, and worktrees remain local and recoverable.

Documentation

| Guide | Purpose | |---|---| | Getting started | Installation through the first bounded execution | | Terminal output | Pretty, plain, JSON, width, color, and stream guarantees | | Component registry | Versioned discovery, compatibility, upgrades, and contribution boundaries | | MCP gateway | Read-only tools, resources, Codex installation, and safety boundaries | | Visual intake | Local schema-driven intake and readiness app | | Release operations | Versioning, tags, npm publication, recovery, and rollback | | Security policy | Vulnerability reporting and credential boundaries | | Changelog | Versioned product changes |

Release verification

pnpm install --frozen-lockfile
pnpm release:check
npm pack --dry-run

A vX.Y.Z tag pointing to a commit contained in main triggers the release workflow. The workflow validates the tagged source, packages the exact verified artifact, publishes @alanarex/aidev-cli, and creates or repairs the matching GitHub Release.

Security

Report vulnerabilities privately as described in SECURITY.md. Do not include real credentials or private repository content in reports.

Provider, GitHub, and npm credentials are read from the process environment and are never persisted by AIDEV-CLI.

License

MIT. See LICENSE.

Autonomous project execution

After intake, planning, and orchestration are ready, start bounded execution with:

aidev start . --workers 4 --approve-task TASK-001
aidev start-status . --json

AIDEV executes dependency waves in isolated task worktrees, creates review pull requests by default, persists compact state in .ai-dev/state/project-run.json, and stops at approval, verification, and review boundaries. It never merges pull requests or deploys production as part of project_start. Use --dry-run to inspect the run without mutation.

Reusable component registry

AIDEV can read a versioned GitHub-backed component catalog, validate manifests, select compatible exact versions, explain rejection reasons, generate reviewable installation and codemod plans, detect updates, and create non-submitted upstream proposals. Shared registry mutation always requires a separate registry worktree, maintainer, independent reviewer, and pull request. See Component registry.

Visual intake app

Start the optional localhost-only intake interface with:

aidev-app --root . --port 4173

The multi-step form uses the canonical intake schema, previews readiness without writes, and creates aidev.yaml only after explicit submission. See Visual intake.