Adelie

Autonomous AI Orchestration System
_{10 specialized agents · 6-phase lifecycle · zero human intervention}

Quick Start · How It Works · Architecture · CLI · Dashboard · Configuration

Overview

Adelie is an autonomous AI orchestrator that plans, codes, reviews, tests, deploys, and evolves software projects through a coordinated multi-agent loop. It ships as a single CLI (npm install -g adelie-ai) and requires only an LLM provider — no cloud backend, no account.

    (o_    Adelie v0.2.1
    //\    ollama · deepseek-v3.1:671b-cloud
    V_/_   Phase: mid_2

What Adelie does in every cycle:

Writer curates the Knowledge Base
Expert makes strategic decisions — what to build next, what to fix
Research gathers external context from the web
Coder generates code in 3 dependency layers
Reviewer scores code quality; rejects until standards are met
Checkpoint snapshots the project before promotion
Tester runs tests and reports failures
Runner builds, installs, deploys
Monitor watches system health
Phase gates decide when to advance the project lifecycle

The loop runs continuously at a configurable interval (default 30 s), or once with adelie run once.

Quick Start

Prerequisites

Requirement	Version
Python	3.10+
Node.js	16+
LLM	Gemini API key or Ollama instance

Install

npm (recommended)

npm install -g adelie-ai

curl (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/Ade1ie/adelie/main/install.sh | bash

PowerShell (Windows)

irm https://raw.githubusercontent.com/Ade1ie/adelie/main/install.ps1 | iex

Homebrew (macOS / Linux)

brew tap Ade1ie/tap
brew install adelie

From source

git clone https://github.com/Ade1ie/adelie.git
cd adelie
pip install -r requirements.txt
python adelie/cli.py --version

Update

# npm
npm install -g adelie-ai@latest

# curl / PowerShell — re-run the install command above

# Homebrew
brew upgrade adelie

# Check current version
adelie --version

Configure

cd your-project/
adelie init

# Gemini
adelie config --provider gemini --api-key YOUR_KEY

# or Ollama (local, free)
adelie config --provider ollama --model gemma3:12b

Run

# Continuous autonomous loop
adelie run --goal "Build a REST API for task management"

# Single cycle
adelie run once --goal "Analyze and document the codebase"

The real-time dashboard opens automatically at http://localhost:5042.

How It Works

Agents

Agent	Role	When
Writer	Curates Knowledge Base — skills, logic, dependencies, exports	Every cycle
Expert	Strategic JSON decisions — action + coder tasks + phase vote	Every cycle
Scanner	Scans existing codebase on first run	Once
Coder	Multi-layer code generation with dependency ordering	On demand
Reviewer	Quality review (1–10 score) with retry-on-reject	After coding
Tester	Executes tests, collects failures, feeds back to coder	After review
Runner	Installs deps, builds, deploys (whitelisted commands)	Mid-phase +
Monitor	System health, resource checks, service restarts	Periodic
Analyst	Trend analysis, insights, KB synthesis	Periodic
Research	Web search → KB for external knowledge	On demand

6-Phase Lifecycle

Each phase transition is gated by quality metrics — KB file count, test pass rate, review scores, stability indicators. The Expert AI votes on phase transitions; the system enforces the gates.

Layered Code Generation

The Coder Manager dispatches tasks across three dependency layers:

Layer 0 — Features and pages (parallel execution)
Layer 1 — Connectors and integrations (depends on Layer 0)
Layer 2 — Infrastructure and configuration (depends on Layer 1)

Failed layers trigger targeted retries with reviewer feedback.

Architecture

Dashboard

Adelie serves a real-time monitoring UI at http://localhost:5042 (auto-starts with adelie run).

Agent grid — live status of all 10 agents (idle / running / done / error)
Log stream — real-time SSE-powered log feed with category filtering
Cycle metrics — tokens, LLM calls, files written, test results, review scores
Phase timeline — visual progress through the 6-phase lifecycle
Cycle history chart — last 30 cycles at a glance

Built with zero external dependencies — Python http.server + SSE + embedded HTML/JS.

Setting	Default	Env var
Enable	`true`	`DASHBOARD_ENABLED`
Port	`5042`	`DASHBOARD_PORT`

CLI

adelie --version                  # Show version
adelie help                       # Full command reference

Workspace

adelie init [dir]                 # Initialize .adelie workspace
adelie ws                         # List all workspaces
adelie ws remove <N>              # Remove workspace

Execution

adelie run --goal "…"             # Start continuous loop
adelie run once --goal "…"        # Single cycle
adelie run ws <N>                 # Resume workspace #N

Configuration

adelie config                     # Show current config
adelie config --provider ollama   # Switch LLM provider
adelie config --model gpt-4o     # Set model
adelie config --api-key KEY       # Set Gemini API key
adelie config --ollama-url URL    # Set Ollama server URL

Settings

adelie settings                   # View all settings
adelie settings --global          # View global settings
adelie settings set <key> <val>   # Change workspace setting
adelie settings set --global <key> <val>  # Change global setting
adelie settings reset <key>       # Reset to default

Available settings: dashboard, dashboard.port, loop.interval, plan.mode, sandbox, mcp, browser.search, browser.max_pages, fallback.models, fallback.cooldown, language

Monitoring

adelie status                     # System health & provider status
adelie inform                     # AI-generated project report
adelie phase                      # Show current phase
adelie phase set <phase>          # Set phase manually
adelie metrics                    # Cycle metrics & history

Knowledge Base & Project

adelie kb                         # KB file counts by category
adelie kb --clear-errors          # Clear error files
adelie kb --reset                 # Reset entire KB
adelie goal                       # Show project goal
adelie goal set "…"               # Set project goal
adelie feedback "message"         # Inject feedback into AI loop
adelie research "topic"           # Web search → KB
adelie spec load <file>           # Load spec (MD/PDF/DOCX) into KB
adelie git                        # Git status & recent commits

Integrations

adelie telegram setup             # Configure Telegram bot
adelie telegram start             # Start Telegram bot
adelie ollama list                # List Ollama models
adelie ollama pull <model>        # Download model
adelie ollama run [model]         # Interactive chat

Configuration

Environment (`.adelie/.env`)

Variable	Default	Description
`LLM_PROVIDER`	`gemini`	`gemini` or `ollama`
`GEMINI_API_KEY`	—	Google Gemini API key
`GEMINI_MODEL`	`gemini-2.0-flash`	Gemini model name
`OLLAMA_BASE_URL`	`http://localhost:11434`	Ollama server URL
`OLLAMA_MODEL`	`llama3.2`	Ollama model name
`FALLBACK_MODELS`	—	Fallback chain (`gemini:flash,ollama:llama3.2`)
`LOOP_INTERVAL_SECONDS`	`30`	Cycle interval in seconds
`DASHBOARD_ENABLED`	`true`	Dashboard on/off
`DASHBOARD_PORT`	`5042`	Dashboard port
`PLAN_MODE`	`false`	Require approval before execution
`SANDBOX_MODE`	`none`	`none`, `seatbelt`, or `docker`

Docker Sandbox

Optional .adelie/sandbox.json:

{
  "docker": {
    "image": "adelie-sandbox:latest",
    "workspaceAccess": "rw",
    "network": "none",
    "memoryLimit": "512m",
    "cpuLimit": 1.0
  }
}

Custom Skills

Place custom skills in .adelie/skills/<name>/SKILL.md:

---
name: react-specialist
description: React/TypeScript best practices
agents: [coder, reviewer]
trigger: auto
---
Use functional components with TypeScript props…

Platform Features

Feature	Description
💾 Checkpoints	Auto-snapshot before promotion, instant rollback
🐳 Docker Sandbox	Configurable workspace isolation, network policy, resource limits
🌐 REST Gateway	HTTP API — `/api/status`, `/api/tools`, `/api/control`
🧩 Skill Registry	Install/update skills from Git repos or local directories
📡 Multichannel	`ChannelProvider` ABC — Discord, Slack, custom channels
🤝 A2A Protocol	Agent-to-Agent HTTP for external agent integration
🔧 MCP Support	Model Context Protocol for external tool ecosystems
📊 Dashboard	Real-time web UI with SSE streaming on port 5042
🔄 Loop Detector	5 stuck-pattern types with escalating interventions
⚡ Scheduler	Per-agent frequency control with cooldown/priority

Testing

python -m pytest tests/ -v    # 197 tests

Project Structure

adelie/
├── orchestrator.py          # Main loop — state machine + phase gates
├── cli.py                   # All CLI commands
├── config.py                # Configuration & env loading
├── llm_client.py            # LLM abstraction (Gemini + Ollama + fallback)
├── interactive.py           # REPL + dashboard integration
├── dashboard.py             # Real-time web server (HTTP + SSE)
├── dashboard_html.py        # Embedded dashboard UI template
├── agents/                  # 10 specialized AI agents
│   ├── writer_ai.py         #   Knowledge Base curator
│   ├── expert_ai.py         #   Strategic decision maker
│   ├── coder_ai.py          #   Code generator
│   ├── coder_manager.py     #   Layer dispatch & retry
│   ├── reviewer_ai.py       #   Quality reviewer
│   ├── tester_ai.py         #   Test runner
│   ├── runner_ai.py         #   Build & deploy
│   ├── monitor_ai.py        #   Health monitor
│   ├── analyst_ai.py        #   Trend analyzer
│   ├── research_ai.py       #   Web researcher
│   └── scanner_ai.py        #   Initial codebase scanner
├── kb/                      # Knowledge Base (retriever + embeddings)
├── channels/                # Multichannel providers (Discord, Slack)
├── a2a/                     # Agent-to-Agent protocol
├── checkpoint.py            # Snapshot & rollback
├── sandbox.py               # Docker/Seatbelt isolation
├── gateway.py               # REST API gateway
├── skill_manager.py         # Skill registry
├── loop_detector.py         # Stuck-pattern detection
├── scheduler.py             # Per-agent scheduling
├── phases.py                # Lifecycle phase definitions
├── hooks.py                 # Event-driven plugin system
├── process_supervisor.py    # Subprocess management
└── env_strategy.py          # Runtime environment detection

Contributing

git clone https://github.com/Ade1ie/adelie.git
cd adelie
pip install -r requirements.txt
python -m pytest tests/ -v   # Ensure all tests pass

Fork → branch → implement → test → PR
Follow existing code style and patterns
Add tests for new features

License

MIT

_{Built with 🐧 by the Adelie team}

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
.agents/workflows		.agents/workflows
.github/workflows		.github/workflows
adelie		adelie
bin		bin
coder		coder
docs		docs
scripts		scripts
staging/src		staging/src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
install.ps1		install.ps1
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

Adelie

Overview

Quick Start

Prerequisites

Install

npm (recommended)

curl (macOS / Linux)

PowerShell (Windows)

Homebrew (macOS / Linux)

From source

Update

Configure

Run

How It Works

Agents

6-Phase Lifecycle

Layered Code Generation

Architecture

Dashboard

CLI

Workspace

Execution

Configuration

Settings

Monitoring

Knowledge Base & Project

Integrations

Configuration

Environment (.adelie/.env)

Docker Sandbox

Custom Skills

Platform Features

Testing

Project Structure

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Environment (`.adelie/.env`)

Packages