Daedalus

Local-first terminal-based AI coding assistant.

Read the design thesis in the Daedalus Manifesto and the architectural foundations in the B.R.A.G. & Marathon Whitepaper — grounded output, honest failure, and a CLI that will absolutely roast your type errors on the way to fixing them.

Daedalus connects to local LLM servers (LM Studio, Ollama, llama.cpp, vLLM) or remote providers (OpenAI, Groq, OpenRouter, Anthropic), routes requests across models, and gives your AI agent access to your file system, terminal, git, web search, and codebase indexing.

For full guides, configuration reference, and examples, visit the documentation site: https://bgill55.github.io/daedalus/

╔═══════════════════════════════════════════════════════════════════╗
║  ██████╗  █████╗ ███████╗██████╗  █████╗ ██╗     ██╗   ██╗███████╗║
║  ██╔══██╗██╔══██╗██╔════╝██╔══██╗██╔══██╗██║     ██║   ██║██╔════╝║
║  ██║  ██║███████║█████╗  ██║  ██║███████║██║     ██║   ██║███████╗║
║  ██║  ██║██╔══██║██╔══╝  ██║  ██║██╔══██║██║     ██║   ██║╚════██║║
║  ██████╔╝██║  ██║███████╗██████╔╝██║  ██║███████╗╚██████╔╝███████║║
║  ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═════╝ ╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚══════╝║
║                                                                   ║
║  o  local-first · embedded router · multi-agent · not sentient o  ║
╚═══════════════════════════════════════════════════════════════════╝

Looking to build and sell your own AI CLI?

Check out Daedalus-Lite — the zero-dependency, rebrandable TypeScript starter template designed for developers to build, rebrand, and sell their own custom AI coding tools! Visit Daedalus-Lite →

Fun fact: Daedalus itself was built using Daedalus-Lite as a starting point, then extended with advanced features like multi-agent orchestration, codebase indexing, and autonomous workflows. See what's possible with Daedalus-Lite for inspiration.

Quick Start

npm install -g daedalus-cli
daedalus

To launch with the interactive terminal dashboard layout:

daedalus --tui

To run a single autonomous task and exit (non-interactive / headless mode):

daedalus --goal "add a --dry-run flag to the build script and update the README"
# also:  daedalus run "..."   (alias)

The one-shot run auto-approves plans and tool calls so it completes without waiting for stdin, then exits with the turn's result.

On first run, Daedalus scans for local LLM servers and guides you through setup. If none are found, it prompts for a remote provider.

From source: git clone https://github.com/bgill55/daedalus.git && cd daedalus && npm install && npm run build

Why Daedalus?

AI assistance without:

• Sending your code to third-party servers
• Per-token pricing for every interaction
• Being locked into a single provider
• Losing conversation history between sessions

The B.R.A.G. Architecture: Solving Long-Horizon Autonomy

Standard AI coding assistants hit a performance cliff after 15–30 minutes due to context rot (polluted transcripts), the regression trap (circular repair churn), and transcript bias (models falsely validating their own broken output).

Daedalus overcomes this with the B.R.A.G. Framework and the Harness-of-Harness (HoH) Marathon Engine (/marathon):

┌─────────────────────────────────────────────────────────────────────────────┐
│                      THE B.R.A.G. AUTONOMOUS FRAMEWORK                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  B — BUILD    : Metis Milestone DAG Task Decomposition                      │
│  R — RETRIEVE : Σ-Mem & FTS5 Semantic Codebase RAG                          │
│  A — AUDIT    : Apollo Air-Gapped Verification & Zero-Byte Gates            │
│  G — GENERATE : Hephaestus Production Code Delivery & Stacked PRs           │
└─────────────────────────────────────────────────────────────────────────────┘

• B — BUILD: Metis decomposes high-level goals into an ordered milestone Directed Acyclic Graph (DAG), documenting progress in a live MARATHON_ROADMAP.md to prevent out-of-order execution and infinite loops.
• R — RETRIEVE: $\Sigma$-Mem recalls past compiler anti-patterns (project-mem.sqlite) and codebase symbols via FTS5 RAG to inject hyper-targeted local context and prevent repeating past mistakes.
• A — AUDIT: Apollo operates in an air-gapped, isolated LLM context (zero coder transcript leakage), enforcing Deterministic Pre-LLM Gates (instantly rejecting 0-byte stubs) and executing hard git rollbacks (git reset --hard) on regression loops.
• G — GENERATE: Hephaestus delivers production code, mints git checkpoints (daedalus-checkpoint/m-*), and automatically packages completed runs into verified Stacked Pull Requests on GitHub.

Architecture Deep Dive: Read the full B.R.A.G. & Marathon Technical Whitepaper and Autonomous Case Study.

Features

Core

• Interactive Terminal Dashboard (TUI) — premium side-by-side dashboard with real-time CPU/RAM monitor gauges, model selection overrides, and an interactive file tree to toggle prompt context dynamically.
• Local-first — works entirely on your machine with local LLMs
• Embedded model router — priority, round-robin, or fastest-response routing across multiple models with real-time tokens-per-second (tok/s) stream telemetry, plus Multi-Model Fallback for zero-interruption auto-failover on rate limits (429) or 5xx errors.
• Dynamic complexity-based routing — classifies each task on arrival (quick/trivial → fast tier, heavy/multi-file → intelligence tier) and re-routes on the fly mid-task as the work evolves, with hysteresis to avoid flapping and a token budget that resets on downgrade so it never ping-pongs. Repeated tool failures trigger automatic escalation to the next model in the chain.
• Multi-agent orchestration — spawns Metis (planner), Hephaestus (coder), Apollo (reviewer), Asclepius (debugger), and Mnemosyne (researcher) sub-agents — each carrying a divine callsign — with OpenAI Swarm-Style Dynamic Handoffs (handoff_task) and shared Context Variables (contextVariables) for seamless mid-turn role transfers. In single-agent REPL mode the active agent can also auto-route a large multi-phase task to helper agents in parallel via route_task (after explicit user approval through ask_user), so the user never has to spawn agents manually.
• Harness-of-Harness (HoH) Marathon Engine (/marathon) — multi-day autonomous software development powered by the B.R.A.G. framework (Build DAGs, Retrieve memory, Audit air-gapped, Generate stacked PRs); Metis milestone DAG planning, air-gapped Apollo evaluation (isolated prompt context), git checkpoint rollbacks (daedalus-checkpoint/m-*), $\Sigma$-Mem anti-pattern persistence across days, and automated Stacked PR generation (/marathon pr) on GitHub.
• Companion Web UI & Sovereign Mobile PWA Companion (/webui) — native local HTTP, WebSocket & Server-Sent Events telemetry dashboard (http://localhost:3888) featuring a sleek Greek mythic dark-mode interface, real-time token streaming, Chronicles session archives, active model switcher modal, in-chat tool accordions, hover code copy, and multimodal paste/drag-and-drop. Fully installable as a mobile-first Progressive Web App (PWA) with offline service worker caching (sw.js), 48px tactile touch targets, QR Code Remote Pairing (/api/qr) over LAN/Tailscale, and real-time Milestone Push Notifications.
• Autonomous Finn Loop — interactive requirements gathering (/spec), GitHub Issues tracking, background daemon execution (daedalus --loop), and Discord PR review webhook embeds.
• CaSKG Procedural Skill Graph Engine — counterfactual-causal skill dependency graphs (src/skills/graph.ts) that resolve prerequisites and leadsTo relationships, retrieving topologically sorted, compact skill bundles to eliminate orphan execution and step thrashing.
• Self-Healing & Immunity Engine — Programmatic Codebase Constitution (src/config/constitution.ts), default Test Suite Read-Only Lock (*.test.ts, vitest/jest runner configs, CI workflows), Reviewer Diff Immunity Audit Checklist (protecting against type-loosening, error-swallowing, and assertion weakening), and Self-Generated Skill Synthesis (.daedalus/skills/drafts/).
• Loop Engineering & Self-Repair — automatic stack-aware compile/build verification checks (e.g., npx tsc --noEmit, cargo check, go build) with dynamic stdout/stderr feedback loops for self-repair, Automated Workspace Rollback to revert patches upon task failure, and Git-Aware Smart Testing (/test -g) to run only affected unit tests in < 200ms.
• Codebase indexing & Live Watcher — FTS5-powered symbol search, definitions, and call-graph references across 10+ languages with background Live File-Watcher (/watch) for automatic re-indexing on save.
• MCP Marketplace & Explorer (/mcp explore) — Model Context Protocol server marketplace with one-click installation (/mcp install <name>) via stdio and HTTP/SSE.
• Stack-aware prompting — automatically scans your project tech stack on startup to prevent library and platform boundary hallucinations
• Dynamic task checklist — injects the active todo list into each prompt turn to maintain execution context
• Session management — SQLite-backed history with save, load, JSONL export
• Persistent memory & Anti-Pattern Learning — $\Sigma$-Mem reliability engine rewards verified patterns and records known pitfalls/compiler failures into a persistent project ledger (project-mem.sqlite), steering agents away from repeating past mistakes; /profile and /style persist across sessions.
• Cursor & Claude Code Compatibility — automatically detects and inherits instructions from CLAUDE.md, .cursorrules, and .daedalusrules files in the project root on startup.
• MCP support — Model Context Protocol servers via stdio and HTTP/SSE
• Windows + Unix — full cross-platform support

Interface & Experience

• Syntax-highlighted responses — assistant code blocks render language-aware, line-numbered, and colorized in the terminal (via cli-highlight), so diffs and snippets are easy to scan.
• Persistent command history — your REPL input history is saved to ~/.daedalus/history and recalled with ↑/↓ across sessions (deduped, capped at 1000 entries).
• Tip of the day — a rotating practical tip prints under the banner on startup to surface lesser-known workflows.
• Themeable UI — /theme [dark|light|auto] switches the palette live (light mode stays legible on white terminals) and persists to config.
• Cost-aware footer — with ui.showCost on, each reply shows an estimated per-turn cost for cloud models (local models stay $0).
• Buffered or streaming replies — ui.streaming toggles token-by-token streaming vs. a single rendered block.
• Side-by-side diffs — set ui.diffStyle to side-by-side for a two-column old-vs-new view in the patch approval UI.

Tools

• Context-Aware Dynamic Tool Selection — dynamically prunes and ranks tool definitions per turn (prioritizing LSP on compiler diagnostics, symbol graphs on refactors, web on URLs), cutting prompt token overhead by 50%+ and sharpening model attention.
• File tools — read, write, patch with interactive diff UI; fuzzy whitespace matching, syntax validation with auto-revert
• Trust layer — write-without-read guardrail, terminal + patch circuit breakers, batch short-circuit on failed file edits, actionable edit hints, import/export validation, auto-test loop, large-rewrite annotation
• Terminal — cross-platform shell execution (bash/cmd/powershell) with custom preference support, timeout, and abort
• Git — status, diff, stage-all-and-commit, undo; real-time interactive working tree visual diff viewer in Companion WebUI
• Web & Browser Automation — DuckDuckGo search, URL fetching, and interactive headless browser automation (browse_page) with SPA DOM rendering, console error sniffing, element clicking/typing, JS evaluation, and vision screenshot capture
• Image Generation — local Stable Diffusion WebUI integration with automatic zero-config Pollinations AI fallback (/image command & generate_image tool) for generating UI assets, logos, and graphics without requiring an API key
• Codebase — index, find, definitions, references
• Logger — unified src/tools/logger.ts with ConsoleLogger and SilentLogger for configurable output
• REPL — persistent context REPL (src/tools/repl.ts) for interactive experimentation
• Telemetry — lightweight performance timing utilities (src/tools/telemetry.ts)
• Dependency fallback — src/tools/deps.ts to verify required commands and provide helpful install guidance

Commands

Multi-Agent, Orchestration & Autonomous Marathon

| Command | Description | |---------|-------------| | /orchestrate <goal> / /orc / /run / /o | Orchestrate agents for a goal | | /marathon <goal> \| status \| resume \| pr \| rollback \| abort | Multi-day autonomous software development (Harness-of-Harness meta-loop) | | /autopilot <feature> | Autonomously implement a feature: branch, code, test, commit, and PR | | /hunt <bug description> / /bug | Autonomously hunt down and fix a bug: reproduce, locate root cause, fix, verify | | /spawn [--bg] <role> <task> / /delegate | Spawn sub-agent: /spawn [--bg] | | /task <id> | Manage background task: /task | /task kill | | /tasks | List background agent tasks | | /ensemble <goal> | Ensemble model drafting pipeline | | /debug <command> | Run command and autonomously debug failures | | /spec | Generate or view a SpecFirst contract (.daedalus/spec.json & spec.md) |

Codebase Search & Live Watcher

| Command | Description | |---------|-------------| | /watch [start\|stop\|status] / watch | Start or stop background codebase file-watcher for automatic FTS5 symbol re-indexing | | /index | Index codebase for symbol search | | /find <query> | Search indexed symbols | | /refs <symbol> | Find symbol references (callers) | | /def <symbol> | Get symbol definition | | /callgraph <symbol> [depth] | Display bidirectional call graph for a symbol | | /impact <symbol> | Analyze refactoring impact & blast radius for a symbol |

Developer Tools, Git, MCP & Web UI

| Command | Description | |---------|-------------| | /webui [start\|stop\|open\|status\|rate <ms>] | Companion Web UI dashboard manager | | /test [n] [-g] / test | Run test loop and fix failures (supports --git-aware / -g for smart test selection) | | /commit [msg] | Stage and commit changes | | /branch [name] | Git branch operations | | /pr [base] | Generate PR description Compared to base branch | | /mcp <explore\|search\|install\|list\|rm> | Manage MCP servers: explore, search, install, list, remove, info | | /image | Generate an image using local Stable Diffusion WebUI or Pollinations AI | | /undo | Undo file edits (usage: /undo [count|list]) | | /ci [review\|fix] | Run headless CI/CD PR review or auto-fix simulation locally | | /badge [custom <label> <message> [color]] [--write] | Generate Shields.io README badges or build custom badges | | /scan-ai-repos [--top N] [--query "topic:..."] [--issue] [--repo owner/name] | Scan top AI repos on GitHub, diff their patterns against this project, and optionally open a GitHub issue with file-specific suggestions. |

Memory, Conventions & Config

| Command | Description | |---------|-------------| | /project [set <key> = <val>] | View or set project config settings (.daedalusrc) | | /config [set <key> = <val>] | Show or modify global configuration | | /profile | View or set user profile info | | /style | Set your coding style preferences | | /fact [text] | Add a project fact to memory | | /convention [text] | Add a project convention to memory | | /memory | View project memory (facts & conventions) | | /extract | Manually extract facts from session | | /session [name] | Manage chat sessions & branches: /session <list|load|new|branch|checkout|merge|export> |

Context & CLI Utilities

| Command | Description | |---------|-------------| | /add | Add file to context | | /remove | Remove file from context | | /context | Show active file context | | /paste | Paste clipboard text/image as message | | /clear | Clear conversation history | | /summarize / /compress | Summarize older conversation history to save tokens and speed up turns | | /system | Print the current active system prompt (including loaded rules) | | /health / health | Display model router provider latency, health status, and API key status | | /models | List available and healthy models | | /doctor | Diagnose connection and discovery | | /changelog | View the latest CLI changes | | /help / ? / help | Show available commands or detailed help for a specific command | | /exit / /quit / /bye | Save session and exit | | /preview <filepath-or-url> | Screenshot a local HTML file or URL and save the image | | /spinner [list \| braille \| tracker \| aurora] / spin | List or switch the "thinking" spinner style on the fly |

Additional Commands

| Command | Description | |---------|-------------| | /theme / theme | Set or show the UI color theme (dark, light, auto). | | /lite | Show Daedalus Lite documentation | | /history / /h | Show recent turns with tool calls from the session log | | /onboard | First-time setup — discover local models, configure, and test | | /tui | Toggle the Terminal User Interface (TUI) dashboard | | /sigma / /memory | Inspect active Σ-Mem (Sigma-Memory) knowledge items & scores | | /routing | Explain the last routing decision and show skipped models | | /providers | List supported model providers and BYOK setup hints | | /blacklist | Show or clear the session model blacklist | | /stats / stats | Display session analytics, token usage, index count, and router status | | /preset / preset | View or apply preset LLM router configurations | | /model / models-manage | Manage router models (list, select/switch, add, remove, enable, disable, sync) | | /shortcut / /sc | Manage custom slash-command aliases | | /feedback / report | Send bug reports or feature requests to the Daedalus team | | /skills | List active skills and pending skill drafts; approve or discard agent-proposed drafts. | | /enhance / prompt / refine | Auto-expand a casual user request into a structured, high-performing engineering prompt | | /cheatsheet / cheat / guide | Display the Daedalus local-first onboarding cheat sheet | | /faq / questions / faqs | Display the Daedalus local-first FAQ (setup, architecture, troubleshooting) | | /recipe | Manage and run portable YAML recipes (/recipe [list | run | create ]) | | /gitautobranch / gitautobranch | Toggle automatic branch-from-base for single-agent tasks |

Tab completion works on all commands. You can get detailed manuals, parameter lists, and subcommand options for any command directly inside the CLI by running /help <command> (for example, /help config or /help mcp).

Configuration

Daedalus stores config at ~/.daedalus/config.json. Key sections:

{
  "router": {
    "strategy": "priority",
    "autoEscalate": true,
    "complexityRouting": true,
    "minModel": "your-strong-model",
    "chain": [
      { 
        "name": "local", 
        "endpoint": "http://localhost:1234/v1", 
        "model": "auto", 
        "enabled": true, 
        "priority": 1,
        "supportsTools": true,
        "tier": "intelligence"
      }
    ]
  },
  "indexing": { "enabled": true, "watch": true, "exclude": ["node_modules", "dist", ".git"] },
  "tools": { "sandbox": "none", "sandboxImage": "node:20" }
}

Router strategies: priority (default), round-robin, fastest.

router.complexityRouting (default true) enables dynamic complexity-based routing — trivial tasks hit your fast tier, heavy tasks hit intelligence, and Daedalus re-routes mid-task as the work evolves. router.autoEscalate (default true) switches to the next chain model after repeated tool failures. Set modelOverride (via /config set modelOverride = <model> or /model) to pin one model and bypass routing entirely. Set DAEDALUS_DEBUG=true to enable verbose [ROUTE] telemetry (per-turn classification and end-of-turn routing summaries).

Per-project config is stored at ~/.daedalus/config/<project-hash>.json and can be set via /project set <key> <value>.

Companion WebUI & Real-Time Chat Console (/webui)

Daedalus includes a native, zero-dependency Companion WebUI (http://127.0.0.1:3888) powered by an embedded HTTP server and real-time Server-Sent Events (SSE). It gives you an illuminated sanctum to interact with Daedalus from your browser while synchronizing seamlessly with the active CLI session:

• ⚡ Real-Time SSE Token Streaming: Experience instant, token-by-token streaming responses with zero turn lag.
• 🏛️ Chronicles (Saved Sessions): Browse, resume, create, and delete SQLite chat sessions with one click from the sidebar archives.
• ⚡ Router Oracles (Active Model Switcher): Inspect active model routing in the header and switch between dynamic auto-routing, speed/intelligence tiers, or specific models via modal.
• 📜 In-Chat Tool Accordions: Interactive collapsible accordions showing live execution state and payloads for file edits, shell commands, and indexing.
• ⌗ Syntax Highlighting & Hover "COPY CODE": Clean syntax-highlighted code blocks with language pills and one-click clipboard copying.
• ⌨️ Multi-Line Auto-Expanding Textarea: Flexible prompt editor with Shift + Enter for newlines and Enter to transmit.
• 🖼️ Multimodal Offerings & Clipboard Paste (Ctrl + V): Direct image paste, drag-and-drop artifacts, and file attachment offerings for vision-capable models.
• ✦ NEW RITE Console Reset: Fast single-click console purge and fresh turn initialization.
• 📁 Interactive Labyrinth Tree & Sanctum Context: Browse the file tree and toggle active turn context tokens visually.

How to Launch:

# Inside the Daedalus CLI REPL:
/webui open        # Starts the local server and opens your browser
/webui rate 500    # Adjust telemetry refresh interval in ms

Read the full Companion WebUI Documentation Guide for architecture, keyboard shortcuts, and REST API specs.

Detailed Documentation Guides

For in-depth explanations, configuration options, and hardware optimization tips, see the modular guides below:

• Companion WebUI & Real-Time Chat Guide — Real-time streaming, Chronicles session persistence, model switcher modal, and SSE/REST API reference.
• Model Routing & Tuning Guide — Endpoints, failover chains, routing strategy configs, and GPU/LM Studio tuning recommendations.
• Multi-Agent Orchestration — Overview of the planning, coding, and review loops, recovery checkpoints, and background task runners.
• Autonomous Finn Loop — Interactive requirements specification, GitHub issue tracking, background daemon execution, and Discord webhook notifications.
• Execution Sandboxing — Running commands inside isolated Docker containers or WSL distributions.
• Model Context Protocol (MCP) Integration — Configuring stdio and HTTP/SSE servers to expand your agent's capabilities.
• Configuration Reference Guide — Reference list of all global configuration keys (router.*, agents.*, tools.*, ui.*, etc.).
• API Reference — Auto-generated TypeScript API documentation showing all exported classes, functions, and modules.

Development

npm run dev       # hot-reload
npm run build     # compile TypeScript
npm test          # vitest (470+ tests)
npm run lint      # eslint (flat config)
npx tsc --noEmit  # type check
npm run audit     # full CI pipeline (lint + build + test + config validation)
npm run docs      # generate Typedoc HTML documentation

Architecture Blueprint

src/
├── index.ts           CLI entry, REPL, command dispatch
├── config/            Zod-schema validated config (+ validate.ts)
├── router/            Model routing, health checks, rate limiter
├── session/           SQLite sessions, project memory, JSONL export
├── agents/            Multi-agent orchestration (planner, coder, et al.)
├── tools/             Logger, REPL, telemetry, deps fallback, spinner
├── indexing/          FTS5 codebase indexing
└── onboarding/        Setup wizard

Contributing

See CONTRIBUTING.md for guidelines, coding standards, and the PR process. Governed by the Code of Conduct.