Installation & Update
npm (Recommended)
Works on macOS, Linux, Windows.
Requires Python 3.10+
Auto-creates venv on first run.
LLM Provider
Gemini API key or local Ollama.
# 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)
brew tap Ade1ie/tap && brew install adelie
# Check version
adelie --version
adelie --update β Update in place
Checks npm registry and updates to the latest version automatically.
adelie --update
# β npm install -g adelie-ai@latest runs automatically
# β Shows cute π§ notification when a new version is available on splash screen too
Quick Start
New project with Gemini
mkdir my-app && cd my-app
adelie init
adelie config --provider gemini --api-key YOUR_KEY
adelie run --goal "Build a REST API with FastAPI and PostgreSQL"
Existing project with Ollama (local)
cd /path/to/project
adelie init
adelie config --provider ollama --model gemma3:12b
adelie scan # Analyze existing codebase β KB
adelie run --goal "Refactor to microservices"
How It Works
Adelie runs a continuous loop of 13 specialized AI agents. Each cycle:
1. Writer AI
Updates architecture docs, README, and project vision.
2. Expert AI
Analyzes KB + goal, decides next action for this cycle.
3. Research AI
Web search β stores findings in Knowledge Base.
4. Coder Manager
Coordinates multi-layer code generation (L0βL2).
5. Reviewer AI
Reviews changes, approves or provides feedback.
6. Tester AI
Writes and runs tests, reports results to KB.
7. Runner AI
Executes build/run commands, handles errors.
8. Monitor AI
Track cycle health, token usage, success rates.
9. Inform AI
Generates human-readable status reports.
10. Security AI
Scans for vulnerabilities, checks dependencies.
11. Dependency AI
Manages package updates and compatibility.
12. Scanner AI
Reads codebase, populates Knowledge Base docs.
13. Notifier
Sends Telegram/alerts for critical events.
π‘ The Knowledge Base (KB) is the shared memory between all agents β stored as Markdown files in
.adelie/workspace/.
Workspace Management
adelie init β Initialize workspace
Creates .adelie/ with KB structure, .env config, and OS-specific context.
adelie init # Current directory
adelie init /path/to/project # Specific directory
adelie init --force # Reinitialize (keeps .env)
| Option | Description |
|---|---|
| [directory] | Target directory (default: .) |
| --force | Overwrite existing .adelie/ |
β¨ Auto-detects project type: Node.js, React, Vue, Next.js, Python, Rust, Go, Java (Maven/Gradle), Ruby, PHP, and sets appropriate phase.
adelie ws β Manage registered workspaces
adelie ws # List all workspaces
adelie ws remove 2 # Remove workspace #2
AI Loop Execution
adelie run β Start the autonomous loop
adelie run # Auto-generates goal from specs
adelie run --goal "Build a chat app" # Explicit goal
adelie run --once # Run single cycle then exit
adelie run ws 1 # Resume workspace #1
adelie run ws 1 --goal "New direction" # Resume with new goal
| Option | Description |
|---|---|
| --goal "text" | High-level goal for all AI agents |
| --once | Run exactly one cycle then exit |
| ws <N> | Resume registered workspace #N |
β οΈ If no goal is set and no spec files exist, Adelie uses a generic improvement goal. Use
adelie goal set "..." or place spec files in .adelie/specs/ for better results.
Configuration
adelie config β LLM provider & core settings
adelie config # Show current configuration
adelie config --provider gemini # Switch to Gemini
adelie config --provider ollama # Switch to local Ollama
adelie config --model gemini-2.5-flash # Set model
adelie config --api-key YOUR_KEY # Set Gemini API key
adelie config --ollama-url http://... # Custom Ollama endpoint
adelie config --lang ko # Language: ko / en
adelie config --sandbox docker # Sandbox: none / seatbelt / docker
adelie config --plan-mode true # Require approval before execution
adelie settings β Two-tier runtime settings
Settings cascade: Workspace β Global β Default
adelie settings # Show all (workspace + global)
adelie settings --global # Show global only
adelie settings set dashboard false # Disable dashboard (workspace)
adelie settings set --global language en # Set global language
adelie settings reset loop.interval # Reset key to default
| Key | Default | Description |
|---|---|---|
| dashboard | true | Dashboard UI on/off |
| dashboard.port | 5042 | Dashboard web port |
| loop.interval | 30 | Seconds between cycles |
| plan.mode | false | Require approval before each action |
| sandbox | none | none / seatbelt / docker |
| mcp | true | MCP protocol on/off |
| browser.search | true | Browser/web search on/off |
| browser.max_pages | 3 | Max pages per search |
| fallback.models | β | e.g. gemini:flash,ollama:llama3.2 |
| fallback.cooldown | 60 | Fallback cooldown (seconds) |
| language | ko | Display language: ko / en |
Knowledge Base
The KB is a structured Markdown store in .adelie/workspace/ shared by all agents. It has 5
categories:
logic/
Architecture, project goal, design decisions.
skills/
How-to guides, patterns, techniques.
dependencies/
Library docs, API references, changelogs.
errors/
Known issues, error patterns, fixes.
maintenance/
Setup, deployment, infra knowledge.
adelie kb β KB management
adelie kb # Show file counts by category
adelie kb --clear-errors # Delete all files in errors/
adelie kb --reset # Wipe entire KB (requires confirmation)
adelie spec β Load specification files
Load business requirements, design docs, or API specs into KB. Supports .md, .pdf, .docx.
adelie spec load requirements.md # Markdown spec
adelie spec load architecture.pdf # PDF (auto-converts)
adelie spec load api_spec.docx --category dependencies
adelie spec list # Show loaded specs
adelie spec remove spec_requirements # Remove by name
adelie scan β Analyze existing codebase
adelie scan # Scan current directory
adelie scan --directory /path/to/src # Specific directory
adelie goal β Project goal
adelie goal # Show current goal
adelie goal set "Build a realtime chat app" # Set/overwrite goal
adelie feedback β Send feedback to running loop
adelie feedback "Focus on auth first"
adelie feedback "Stop production deploy" --priority critical
adelie feedback --list # List pending feedback
| Priority | When to use |
|---|---|
| low | Nice-to-have suggestions |
| normal | Standard guidance (default) |
| high | Important direction changes |
| critical | Stop / emergency override |
adelie research β Web research β KB
adelie research "FastAPI WebSocket tutorial"
adelie research "Redis pub/sub" --context "high-perf" --category skills
adelie research --list # List recent results
Monitoring & Status
adelie status β System health
adelie status
# Shows: LLM provider, model, connection status, KB file counts, workspace path
adelie inform β AI-generated status report
adelie inform
adelie inform --goal "Microservice migration"
adelie metrics β Cycle performance
adelie metrics # Recent cycles (default: last 20)
adelie metrics --agents # Per-agent token breakdown
adelie metrics --trend # Performance trends over time
adelie metrics --last 50 # Show last 50 cycles
adelie metrics --since 24h # Filter: 1h / 6h / 12h / 24h / 7d
adelie phase β Project lifecycle management
adelie phase # Show current phase
adelie phase set mid_1 # Change phase
Project Phases (Lifecycle)
Adelie adjusts agent behavior based on the current project phase β from initial planning to autonomous evolution.
| Phase | Value | Coder Layers | Focus |
|---|---|---|---|
| π± Initial | initial | β | Vision docs, architecture design |
| π¨ Mid | mid | L0 | Core implementation, testing |
| π Mid 1 | mid_1 | L0β1 | Feature execution, roadmap |
| β‘ Mid 2 | mid_2 | L0β2 | Optimization, deployment |
| π‘οΈ Late | late | L0β2 | Maintenance, new features |
| 𧬠Evolve | evolve | L0β2 | Autonomous evolution |
Ollama Model Management
adelie ollama list # Show installed models (active one marked)
adelie ollama pull gemma3:12b # Download model
adelie ollama remove gemma3:12b # Remove model
adelie ollama run # Interactive chat with current model
adelie ollama run llama3.2 # Chat with specific model
Telegram Bot
Get real-time notifications and control the loop via Telegram.
adelie telegram setup # Interactive token setup (get from @BotFather)
adelie telegram start # Start bot (current workspace)
adelie telegram start --ws 1 # Bind to workspace #1
adelie telegram start --token T # Override saved token
Git
adelie git # Show git status + 5 most recent commits
Prompt Management
Customize the system prompts for any agent.
adelie prompts # List all prompts (package vs user-customized)
adelie prompts export # Copy defaults β .adelie/prompts/ for editing
adelie prompts reset # Remove custom prompts, restore defaults
β¨ Exported prompts live in .adelie/prompts/<agent>.md. Adelie always checks there first
before using package defaults.
Tool Registry
adelie tools # List available tools and their status
adelie tools enable web_search # Enable a tool
adelie tools disable web_search # Disable a tool
Custom Commands
Drop any .md file in .adelie/commands/ to create a custom slash command for the
interactive REPL.
adelie commands # List detected custom commands
Environment Variables
Configured in .adelie/.env (workspace-level) or ~/.adelie/.env (global).
| Variable | Default | Description |
|---|---|---|
| LLM_PROVIDER | ollama | 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 |
| OLLAMA_API_KEY | β | Ollama Cloud API key |
| FALLBACK_MODELS | β | Chain: gemini:flash,ollama:llama3.2 |
| FALLBACK_COOLDOWN_SECONDS | 60 | Cooldown before fallback reset |
| DASHBOARD_ENABLED | true | Web dashboard on/off |
| DASHBOARD_PORT | 5042 | Dashboard port number |
| PLAN_MODE | false | Require approval before actions |
| SANDBOX_MODE | none | none / seatbelt / docker |
| MCP_ENABLED | true | MCP protocol on/off |
| BROWSER_SEARCH_ENABLED | true | Web search on/off |
| BROWSER_SEARCH_MAX_PAGES | 3 | Pages per search query |
| ADELIE_LANGUAGE | ko | ko / en display language |
| LOOP_INTERVAL_SECONDS | 30 | Seconds between cycles |
Quick Reference
adelie init
adelie config --provider ollama
adelie run --goal "..."
adelie --update
adelie --version
adelie status
adelie phase
adelie metrics
adelie kb
adelie spec load <file>
adelie scan
adelie goal set "..."
adelie feedback "..."
adelie research "..."
adelie ws
adelie run ws 2
adelie ollama list
adelie ollama pull llama3.2
adelie prompts export
adelie tools
adelie commands
Changelog
All notable changes to Adelie, following Keep a Changelog format.
β¨ Added
- Test Environment & Dependency Detection β Automated detection of active test runners (vitest/jest/pytest) and installed
devDependenciesinpackage.json(across monorepos). Tester AI now writes precise assertions matching current imports, with built-in assert/test fallbacks. - Fail-Safe Executions β Skips TS/TSX tests when no test runner is available, and executes plain JS tests directly with Node, preventing test environment timeouts.
π Fixed
- Non-Interactive TSX Test Hang β Added the
-yauto-confirm flag to thenpx tsxcommand in Tester AI, preventing 60-second test timeouts caused by npm package prompts.
π Fixed
- Monorepo Scaffolding Loop β Improved scaffolding check to auto-detect workspace directories (nested client/server). Scaffolding validation is now applied relative to sub-workspaces, preventing agent stagnation loops.
β¨ Added
- Auto-Update & Check-for-Updates CLI Options β Added global
--updateflag to check npm registry and auto-update Adelie locally. - Graceful Splash Update Notices β Non-blocking update check (with a 1s timeout) on startup splash welcome screen with a cute penguin alert.
- Async REPL Startup Checks β Background thread update checking for
adelie runcommand loop that displays alerts gracefully. - English Localization for Update Systems β Fully localized all update-checking notices and output logs into English for global npm packages.
π Fixed
- Orchestrator Stability β Fixed new_logic state transition leak by removing premature loop returns.
- Tester Flow β Prevented test suite file leakage by merging newly compiled files rather than replacing.
- Concurrency β Thread-safe deep copies for coder tasks during parallel execution.
- Self-Healing β Active rollback to the latest safe checkpoint when error recoveries are exhausted.
- Stalemate Detection β Adjusted streak tracking to monitor actual promoted files.
π Fixed
- Per-File Limit Trap β Shifted to fullpath matching and raised MAX_CODERS_PER_FILE, preventing deadlocks.
- Dep Sync Validation β Lowercase syntax check and blocklist for hallucinated dependency packages.
- Zero-File Loop β Emergency coder registry reset for stalled coder modules.
π Fixed
- Review Failure Logging β Rejected code details now logged to KB errors, preventing Expert AI from re-issuing identical failing tasks.
- Expert AI Context Gap β
last_coder_resultnow included in system state for cycle-to-cycle continuity. - Reviewer Staging Path β Reviewer now reads from
STAGING_ROOTinstead ofPROJECT_ROOT. - Scaffolding Warning Severity β Reduced from
β οΈ CRITICALtoβΉοΈ NOTEto prevent model over-reaction. - Framework-Specific Coder Guidelines β Next.js
'use client'rules, correct package names, etc. injected into Coder prompt.
β¨ Added
- Configurable LLM Timeout β New
LLM_TIMEOUTenv var (default: 300s, up from hardcoded 120s). Prevents timeouts on large models likegemma4:31bvia Ollama Cloud.
π Fixed
- Framework Detection β Scaffolding check no longer assumes all JS/TS projects use Vite. Added
_detect_framework()supporting Next.js, Nuxt, Remix, SvelteKit, and Angular with framework-appropriate entry file checks. - Path Safety β Fixed
".." in filepathsubstring match incorrectly blocking Next.js catch-all routes like[...nextauth]. Now usesPath.partsfor segment-level traversal detection. - Coder Context β Auto-included config files for coders now cover Next.js, Nuxt, SvelteKit, Remix, and Angular configs alongside Vite.
Transforms Adelie from a static pipeline executor into a self-configuring, policy-enforced, production-aware AI harness. Consolidates v0.2.16βv0.2.20.
π§ Meta Harness β Dynamic Pipeline
- HarnessManager β Dynamic JSON state machine. Expert AI reconfigures pipeline at runtime via
MODIFY_HARNESS. - DynamicAgent β Runtime-created agents with 3-tier permissions. Snapshot rollback on failure.
π‘οΈ Policy Engine β Declarative Constraints
- PolicyEngine β Enforces
constraints.yamlrules (pattern/ast/file). PolicyGate blocks promotion on violation. - AST Checker β Detects
eval(),exec(), wildcard imports, missing docstrings.
π§ Memory Harness β Selective Forgetting
- Phase Scope Filter β KB files visible only during designated phases.
- Archive Manager β Auto-archives resolved errors + completed-phase docs. Summary Tree preserves awareness.
π‘ Production Bridge β CI/CD Feedback
- 3 Adapters β GitHub Actions, Sentry, Custom MCP. Critical verdict β ERROR + hotfix.
- Graceful Degradation β Missing tokens = adapter silently disabled.
β Human Intercept & Monitoring
- CLI β
/intercept,/policy,/health,/memory,/harness, enhanced/status. - Dashboard β Intercept button, Production Health, Policy Engine, Memory Harness, Pipeline Visualizer panels.
β¨ Added
/interceptβ Immediate mid-cycle stop + ERROR state + KB logging./policyβ Policy Engine rules & status display./healthβ Production Bridge verdict & signal monitor./memoryβ Memory Harness statistics (active/archived/scoped)./harnessβ Pipeline structure & dynamic agent display.- Dashboard: Intercept Button β Emergency β stop with confirmation modal.
- Dashboard: Feature Panels β Production Health, Policy Engine, Memory Harness, Pipeline Visualizer.
- Dashboard: Feature SSE β Real-time feature status push on every cycle.
π Changed
/statusβ Full system status with all feature states.- Cycle Header β Feature indicators (π‘οΈ π‘ π§ ).
β¨ Added
- Production Bridge β Connects AI harness to external CI/CD and monitoring. Three adapters: GitHub Actions, Sentry, Custom MCP.
- GitHub Actions Adapter β Polls workflow statuses via REST API or MCP. Detects CI failures as critical signals.
- Sentry Adapter β Polls error issues, detects spikes above threshold.
- Custom MCP Adapter β Auto-discovers production-related MCP tools.
PRODUCTION_ALERTHookEvent β New hook for external alert handling.
π Changed
- Orchestrator β Polls bridge at cycle start. Critical β
ERROR+ KB log + hotfix generation. - Expert AI β Health context injected into decision prompt.
- Config β
PRODUCTION_BRIDGE_ENABLED,PRODUCTION_POLL_INTERVAL.
β¨ Added
- Memory Harness β Selective Forgetting β Controls KB visibility per phase. Three mechanisms: Phase Scope Filter, Archive Manager, Summary Tree.
- Phase Scope Filter β KB files tagged with
phase_scopeare only visible during designated phases. Backward compatible. - Archive Manager β Stale errors (3+ cycles) and completed-phase docs auto-archived to
archive/, removed from active queries. - Summary Tree β Archived files get 1-2 line summaries in
archive/summaries.mdfor minimal historical context.
π Changed
- KB Retriever β
query()andsemantic_query()now acceptcurrent_phasefor phase-aware filtering. - Context Engine β Injects archive summaries (5% budget) into agent context.
- Orchestrator β Phase transitions trigger automatic KB archiving. Cycle-end maintenance archives resolved errors.
β¨ Added
- Declarative Policy Engine β Enforces project constraints from
.adelie/constraints.yaml. Three rule types:pattern(regex),ast(Python AST),file(metrics). Severityblockprevents code promotion. - PolicyGate β Deterministic gate between Reviewer AI and staging promotion. Blocks violating code with automatic Coder retry loop.
- AST Checker β Python
ast-based analysis: forbidden calls (eval,exec), wildcard imports, missing docstrings. - Negative Pattern β
negative_patternfield suppresses false positives (e.g.,requests.getwithtimeout=passes). - Policy Prompt Injection β Active constraints injected into Coder AI and Reviewer AI prompts for prevention at generation time.
π Changed
- Promotion Gate β Now requires
reviewer_approved AND policy_passed. PolicyGate failure triggers Coder feedback retry.
β¨ Added
- Meta Harness Architecture β Static 6-phase Enum pipeline replaced with dynamic JSON-based state machine (
harness.json). Expert AI can autonomously reconfigure the pipeline at runtime viaMODIFY_HARNESSaction. - HarnessManager β Core manager: load/save/validate harness configs, snapshot-based rollback, declarative JSON transition criteria.
- DynamicAgent β Runtime-configurable agent class. Roles, prompts, constraints defined in harness.json and instantiated on-the-fly.
- 3-Tier Permission Model β
observerβanalystβoperatorescalation for dynamic agents. - Harness Rollback β Auto-snapshots before modification; failed changes auto-rollback.
- Orchestrator Phase 5 β New execution phase for dynamic agents with full scheduler integration.
π Changed
phases.pyβ Compatibility Shim βPhaseEnum andPHASE_INFOnow proxy through HarnessManager. All 17+ import points unchanged.- Declarative Transitions β
_check_phase_readiness()uses JSON conditions instead of hardcoded lambdas. - Expert AI Schema β Added
MODIFY_HARNESSaction andharness_payloadfield.
π Fixed
- Testing & Sandbox Paths β Added proper shell-quoting around interpolated directory paths to prevent environment failures when the project directory contains spaces.
- Configuration Reloading Bug β Transitioned
WORKSPACE_PATHandPROJECT_ROOTdirect module imports to dynamic property lookups in agents to correctly reflect CLI context updates. - Version Integrity β Synchronized
pyproject.tomlanddocs/index.htmlto reflect the current deployment version alongside global builds.
π Fixed
- Testing suite stability β Fixed test failures caused by
ModuleNotFoundErrorfor Playwright, and `TimeoutError` in Python 3.9 during parallel execution.
π Fixed
- Python 3.9 compatibility β Fixed a SyntaxError in
_helpers.pywhere a backslash was used inside an f-string expression.
π Security & Stability
- Windows shell injection β Blocks single
&and>in runner/tester command filters - Thread safety β
_usage_lockprotects token counters from race conditions - Staging race condition β
_staging_lockprevents concurrent file operations in Phase 3 - Path traversal β
Path.resolve()verification for Windows absolute path bypass
π Fixed
- Reviewer logic β Retry limit no longer force-approves rejected code
- Windows
python3stub β Usessys.executableinstead of Microsoft Store shim - Windows venv activation β Generates
activate.batwrapper,cmd /cresolver - KB glob pattern β
glob("*.md")excludes non-content files - Writer similarity β Fixed edge case in content deduplication
π Changed
- Cross-platform tests β 6 previously-failing Windows tests now pass
π Fixed
cmd_initpath resolution β Resolves relative to user's CWD, not npm package location
β¨ Added
- GitHub Pages documentation β Full command reference site with dark theme
π Fixed
- CLI execution β Correct
sys.pathviapython -m adelie.cli
β¨ Added
- Auto update checker β
adelie --update - CI/CD pipeline β Auto npm publish on merge to main
π Changed
- CLI refactor β Split
cli.pyintoadelie/commands/package
π Fixed
- Module importability β Added
PYTHONPATHto npm binary wrapper
β¨ Highlights
- Initial public release on npm (
adelie-ai) - Multi-provider LLM β Gemini & Ollama support with fallback chains
- 13 AI Agents β Expert, Writer, Coder, Reviewer, Tester, Runner, Monitor, Analyst, Scanner, Research, Inform
- Knowledge Base β Semantic retrieval, spec auto-sync
- Real-time dashboard β SSE-powered web UI
- OS detection β Auto-generated context for Windows/macOS/Linux
- State persistence β Resume from Ctrl+C
- Telegram integration β Bot for remote monitoring
- Plan Mode β Human-in-the-loop approval for code changes
π Full changelog: CHANGELOG.md on GitHub