AELVO Omega

Automated Engineering & Logic-Verification OS

AELVO is a web + terminal multi-agent engineering system that plans and executes complex software engineering tasks using seven specialized AI agents coordinated through a canonical pipeline with cross-cutting verification, recovery, and memory.

User → HERMES → ARCHITECT → ORACLE → FORGE → SENTINEL → TERMINUS → HERALD
         ↑                          Memory & Intelligence Layer                ↓
         ←──────────────────── Verification & Recovery ──────────────────────→

---

Why AELVO Exists

Single-agent coding tools hit a wall on complex tasks. One agent cannot simultaneously:

• Calibrate to your communication style and expertise level
• Plan with repository-aware dependency analysis and risk assessment
• Research facts and verify claims against live sources
• Generate code with institutional pattern memory and error recovery
• Secure every change against vulnerabilities and credential leaks
• Execute DevOps commands safely with rollback planning
• Report results with strategic communication advisory

AELVO solves this with seven specialized agents that collaborate through a shared coordination layer with visible handoffs, role specialization, and state passing.

---

Key Capabilities

Capability	How AELVO Does It
7 Specialized Agents	HERMES, ARCHITECT, ORACLE, FORGE, SENTINEL, TERMINUS, HERALD
Repository Intelligence	Symbol graph, dependency graph, call graph, impact analysis
Architect Intelligence	14-section strategic plans with verification and recovery design
Verification Pipeline	Lint, typecheck, security scan, graph consistency, sandbox validation
Recovery Engine	Failure classification, retry safety, governance, learned recovery memory
Execution Graph	DAG-based execution with node states, retry policies, output contracts
Event System	Typed async event bus with replayable logging
Memory Systems	Dual-sync (SQLite + ChromaDB vector), cross-specialist memory
Learning Engine	Pattern extraction from execution deltas, confidence calibration
Web + Terminal UI	Web dashboard with chat/Files/agent metrics, plus a CodeBuff-style terminal CLI
Multi-Provider	22+ providers: OpenAI, Anthropic, Google, Groq, Mistral, Cohere, xAI, DeepSeek, Together, Fireworks, Perplexity, OpenRouter, Hugging Face, NVIDIA, Azure, Bedrock, Vertex + local (Ollama, LM Studio, vLLM, llama.cpp)
Long-Horizon Planning	Session continuity, goal hierarchy, multi-session awareness
Plan Calibration	Track outcomes vs plans, adjust future strategies automatically

---

Quickstart

Install via npm (recommended)

# One-liner — installs the CLI, creates a Python venv, and installs deps
npm install -g aelvo   # https://www.npmjs.com/package/aelvo

# Activate from ANY folder — the command is the activation (claude/codex style)
aelvo

aelvo opens the current working directory. aelvo <folder> opens any folder. Per-folder state (memory, anchor, backups) lives in a hidden .aelvo/ directory inside the opened folder, so your project tree stays clean and every folder gets its own isolated memory. Global state (credential vault, global memory, logs) lives in ~/.aelvo/ (AELVO_DATA_DIR to override). The Rust sandbox is optional — a pure-Python fallback provides the same file tools + policy when it's absent.

Install from source

git clone https://github.com/aelvolabs/aelvo.git
cd aelvo
pip install -r requirements.txt

# Optional: compile the Rust sandbox for sandboxed execution
cd sandbox_core && cargo build --release && cd ..

Provider Setup

# Copy the example environment file
cp .env.example .env

# Edit .env with your LLM provider API key:
#   LLM_PROVIDER=openai
#   API_KEY=sk-...
#   MODEL=gpt-5
#
# Or use NVIDIA:
#   LLM_PROVIDER=nvidia
#   NVIDIA_API_KEY=nvapi-...
#   MODEL=nvidia/nemotron-3-super-120b-a12b

Launch

# Activate in the current folder (npm-installed or from source)
aelvo                 # opens the current directory
aelvo ./my-project    # opens any folder
aelvo "refactor the auth module"   # one-shot prompt in the current folder

# From source, these are equivalent:
python -m cli                         # opens the current directory
python -m cli ./my-project            # opens any folder
python -m cli -w ./my-project --provider openai --model gpt-5

# Full boot → CLI (runs the whole platform first)
python main.py

# Launch the web dashboard instead
python main.py --web

---

Terminal CLI (aelvo, python -m cli)

A dedicated interactive terminal agent in the spirit of CodeBuff / Claude Code, reusing the exact same backend as the web dashboard. python -m cli boots a lean backend (kernel, filesystem, memory, orchestrator, provider runtime) and skips the heavy optional subsystems the web boot runs (MCP discovery, long-horizon planning, repo scans), so the prompt appears in a couple of seconds. Type any natural language task — Enter submits, Esc+Enter inserts a newline, and tool calls (read/write/bash/scrape/memory) render live as the agent works.

❯ refactor the authentication module to use async database sessions
  ✓ ✏️ write_file core/auth/session.py
  ✓ ⚙️ bash_exec python -m pytest tests/test_auth.py
  …
  **Done.** Migrated the session store to an async engine and verified it.

Force-route to specific specialists with @SPECIALIST prefixes:

❯ @FORGE fix the race condition in worker.py
❯ @ORACLE research the latest changes to Python 3.13
❯ @ARCHITECT design a database schema for the new reporting feature

Slash Commands

Command	Description
/help	Show all commands
/exit · /quit	Exit the CLI
/clear [history]	Clear the screen; /clear history resets the conversation
/pwd	Print the active folder
/status	Provider, model, folder + live agent metrics
/provider [name] [key]	Two-step interactive picker: choose a provider, then one of its models (or /provider <name> [key] directly); the API key is asked inline as part of selection — existing keys can be replaced/rotated right in the picker — and stored in the encrypted vault
/model [name]	Open an interactive picker to switch the active model (or /model <name> directly)
/mode [low|medium|high|max]	Dial the agent effort: low plain chat, medium chat + tools, high full agent pipeline (default), max collaborative Mode B

Effort Modes

Small messages don't need the whole multi-agent ceremony. Use /mode (or set AELVO_MODE in the environment) to pick how much machinery runs per turn:

Mode	What runs
low	One direct answer — no tools, no specialists, no plan. Fastest
medium	Direct answer, but tools are available when needed (Claude Code style)
high	Full consolidated pipeline: HERMES → ARCHITECT → FORGE → … → HERALD (default)
max	Collaborative task-board pipeline with decomposition, consensus, verification, recovery

There is no workspace registry or /workspace command — aelvo opens any folder directly (the current directory by default, or aelvo <folder>), and per-folder state lives in .aelvo/ inside that folder. API keys are stored in the universal AELVO space (~/.aelvo), never inside the opened folder.

Local runtimes (Ollama, LM Studio, vLLM, llama.cpp) are first-class providers: pick them like any other — no API key needed. The model list is fetched live from your local server (localhost:11434, :1234, :8000, :8080 respectively), with the curated catalog as fallback. | /log [lines] | Tail the AELVO log file | | /version | Show version and environment info | | /retry | Re-run the previous prompt | | /ask <prompt> | Run a prompt without the agent loop |

---

Web Dashboard (python main.py --web)

python main.py --web serves the web dashboard (HTTP + WebSocket bridge): chat, a terminal-style Files page with an Open as Workspace action, agent metrics, and provider setup from the browser. The terminal CLI is the default interface; add --no-browser to run the server headless.

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        AELVO OMEGA                               │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │ HERMES    │→│ ARCHITECT│→│ ORACLE   │→│ FORGE    │        │
│  │ Calibrate │  │ Plan     │  │ Research │  │ Code     │        │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │
│       ↓              ↓              ↓             ↓            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                     │
│  │ SENTINEL │→│ TERMINUS │→│ HERALD   │                     │
│  │ Security │  │ DevOps   │  │ Report   │                     │
│  └──────────┘  └──────────┘  └──────────┘                     │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │               Cross-Cutting Subsystems                    │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐  │  │
│  │  │ Runtime   │  │ Verify   │  │ Recovery │  │ Memory  │  │  │
│  │  │ Pipeline  │  │ Pipeline │  │ Engine   │  │ Systems │  │  │
│  │  └──────────┘  └──────────┘  └──────────┘  └─────────┘  │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐    │
│  │ Repo     │  │ Architect│  │ Learning │  │ Provider     │    │
│  │ Intel    │  │ Brain    │  │ Engine   │  │ Runtime      │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Key Files

File	Purpose
main.py	Entry point, AelvoAgent, web/CLI boot
cli/app.py	Terminal CLI — REPL, live tool rendering, slash commands
core/orchestration/orchestrator.py	Orchestrator — central coordinator
core/orchestration/pipeline.py	RuntimePipeline — canonical execution pipeline
specialists/*.py	7 specialist implementations
runtime_next/engine/engine.py	ExecutionGraph & ExecutionEngine
runtime_next/events/bus.py	Async typed EventBus with replay
runtime_next/recovery/engine.py	RecoveryEngine — failure classification & recovery
runtime_next/verification/pipeline.py	VerificationPipeline — plugin-based verifiers
runtime_next/plan/architect.py	ArchitectOrchestrator — strategic planning
runtime_next/plan/brain.py	13-engine ArchitectIntelligenceBrain
repo_intelligence/engine.py	RepoIntelligenceEngine — symbol & dependency graphs
learning/engine.py	PatternExtractionEngine — execution pattern learning
cognition/engine.py	CognitiveEngine — goals, planning, research, consensus
web/	Web dashboard (React frontend + WebSocket bridge)

---

Example Workflow

$ cd ~/projects/my-app          # open any folder — no workspace setup needed
$ aelvo
AELVO
────────────────────────────────────────────────────────────────
  project: my-app   provider: nvidia   model: nvidia/nemotron-3-super
  folder: C:/Users/you/projects/my-app

type /help for commands · Esc+Enter for a newline · Ctrl+C to exit
❯ Fix the race condition in the worker pool module

[Thinking] ⠋
✓ Pipeline completed: SUCCESS in 12.3s with 7 phases (1 LLM call)

  ── AELVO PIPELINE EXECUTION ──
  Phases: calibration → planning → research → implementation → security → execution → reporting
  Result: ✅ SUCCESS
  Duration: 12300ms
  Memory: Consolidated

  Verification:
    ✓ calibration: verification passed
    ✓ planning: verification passed
    ✓ implementation: verification passed
    ✓ security: verification passed
    ✓ execution: verification passed

[AELVO] Fixed the race condition in worker_pool.py by replacing the
shared mutable state with an asyncio.Queue and adding proper worker
lifecycle management. The fix was verified with type checks and tests.

AELVO never litters your project — all per-folder state lives in a hidden .aelvo/ directory inside the opened folder, so git status stays clean:

$ ls -a ~/projects/my-app
.  ..  .aelvo  worker_pool.py

$ ls ~/projects/my-app/.aelvo
anchor.md    backups/    history    memory.db

---

License

MIT — see LICENSE for details.