aiden-runtime 4.1.4 → 4.5.0

package/README.md

@@ -1,847 +1,250 @@
-<img width="1672" height="941" alt="AIDEN BOOTUP LOGO" src="https://github.com/user-attachments/assets/c0809009-73e2-4d58-9292-12fbd0324952" />
-
-
-
-
-```
-█████╗  ██╗██████╗ ███████╗███╗   ██╗
-██╔══██╗██║██╔══██╗██╔════╝████╗  ██║
-███████║██║██║  ██║█████╗  ██╔██╗ ██║
-██╔══██║██║██║  ██║██╔══╝  ██║╚██╗██║
-██║  ██║██║██████╔╝███████╗██║ ╚████║
-╚═╝  ╚═╝╚═╝╚═════╝ ╚══════╝╚═╝  ╚═══╝
-
-Autonomous AI Engine
-
-74 skills · 53 tools · 19 providers · 9 channels · AGPL-3.0
-
-Windows · Linux · WSL · macOS (API Mode)
-
-Local-first · Self-healing routing · Browser & terminal control · Persistent memory
-```
-
-<p align="center">
-  <a href="https://github.com/taracodlabs/aiden/releases/latest"><img src="https://img.shields.io/github/v/release/taracodlabs/aiden?color=f97316&label=version&style=for-the-badge" alt="Latest version" /></a>
-  <a href="https://github.com/taracodlabs/aiden/releases"><img src="https://img.shields.io/github/downloads/taracodlabs/aiden/total?color=f97316&label=downloads&style=for-the-badge" alt="Downloads" /></a>
-  <a href="https://discord.gg/gMZ3hUnQTm"><img src="https://img.shields.io/badge/chat-discord-7289da?logo=discord&logoColor=white&style=for-the-badge" alt="Discord" /></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-orange?style=for-the-badge" alt="License: AGPL-3.0" /></a>
-  <a href="https://github.com/taracodlabs/aiden/stargazers"><img src="https://img.shields.io/github/stars/taracodlabs/aiden?style=for-the-badge&color=f9d71c" alt="Stars" /></a>
-  <a href="https://www.npmjs.com/package/aiden-runtime"><img src="https://img.shields.io/npm/v/aiden-runtime?color=f97316&label=npm&style=for-the-badge" alt="npm" /></a>
-  <a href="https://amzn.to/4tpiXwM"><img src="https://img.shields.io/badge/book-Omega-ff9900?logo=amazon&logoColor=white&style=for-the-badge" alt="Book: Omega" /></a>
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/TypeScript-5.9-3178c6?logo=typescript&logoColor=white&style=for-the-badge" alt="TypeScript 5.9" />
-  <img src="https://img.shields.io/badge/Node.js-18+-43853d?logo=node.js&logoColor=white&style=for-the-badge" alt="Node.js 18+" />
-  <img src="https://img.shields.io/badge/JavaScript-ES2022-f7df1e?logo=javascript&logoColor=black&style=for-the-badge" alt="JavaScript ES2022" />
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/Electron-41-47848f?logo=electron&logoColor=white&style=for-the-badge" alt="Electron 41" />
-  <img src="https://img.shields.io/badge/Next.js-app%20router-000000?logo=next.js&logoColor=white&style=for-the-badge" alt="Next.js" />
-  <img src="https://img.shields.io/badge/React-18-61dafb?logo=react&logoColor=black&style=for-the-badge" alt="React 18" />
-  <img src="https://img.shields.io/badge/Tailwind%20CSS-06b6d4?logo=tailwind-css&logoColor=white&style=for-the-badge" alt="Tailwind CSS" />
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/Anthropic-API-e8a061?logo=anthropic&logoColor=white&style=for-the-badge" alt="Anthropic" />
-  <img src="https://img.shields.io/badge/OpenAI-SDK-412991?logo=openai&logoColor=white&style=for-the-badge" alt="OpenAI" />
-  <img src="https://img.shields.io/badge/Ollama-local-000000?logo=ollama&logoColor=white&style=for-the-badge" alt="Ollama" />
-  <img src="https://img.shields.io/badge/MCP-1.27-7c3aed?style=for-the-badge" alt="Model Context Protocol" />
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/Playwright-1.58-2ea44f?logo=playwright&logoColor=white&style=for-the-badge" alt="Playwright" />
-  <img src="https://img.shields.io/badge/CDP-Chrome-4285f4?logo=googlechrome&logoColor=white&style=for-the-badge" alt="Chrome DevTools Protocol" />
-  <img src="https://img.shields.io/badge/Puppeteer-40b5a4?logo=puppeteer&logoColor=white&style=for-the-badge" alt="Puppeteer" />
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/SQLite-003b57?logo=sqlite&logoColor=white&style=for-the-badge" alt="SQLite" />
-  <img src="https://img.shields.io/badge/better--sqlite3-12-003b57?style=for-the-badge" alt="better-sqlite3" />
-  <img src="https://img.shields.io/badge/sql.js-WASM-003b57?style=for-the-badge" alt="sql.js" />
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/Vitest-4-6e9f18?logo=vitest&logoColor=white&style=for-the-badge" alt="Vitest 4" />
-  <img src="https://img.shields.io/badge/esbuild-bundler-ffcf00?logo=esbuild&logoColor=black&style=for-the-badge" alt="esbuild" />
-  <img src="https://img.shields.io/badge/install-npm%20global-cb3837?logo=npm&logoColor=white&style=for-the-badge" alt="npm install -g aiden-runtime" />
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/Discord.js-bot-5865f2?logo=discord&logoColor=white&style=for-the-badge" alt="Discord.js" />
-  <img src="https://img.shields.io/badge/Slack-SDK-4a154b?logo=slack&logoColor=white&style=for-the-badge" alt="Slack SDK" />
-  <img src="https://img.shields.io/badge/Twilio-SMS-f22f46?logo=twilio&logoColor=white&style=for-the-badge" alt="Twilio" />
-  <img src="https://img.shields.io/badge/IMAP%20%2F%20SMTP-email-0078d4?logo=maildotru&logoColor=white&style=for-the-badge" alt="IMAP / SMTP" />
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/Croner-cron-f97316?style=for-the-badge" alt="Croner" />
-  <img src="https://img.shields.io/badge/figlet-ASCII-808080?style=for-the-badge" alt="figlet" />
-  <img src="https://img.shields.io/badge/chalk-color-ff8c00?style=for-the-badge" alt="chalk" />
-  <img src="https://img.shields.io/badge/ora-spinner-00bcd4?style=for-the-badge" alt="ora" />
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/Cloudflare-Workers-f38020?logo=cloudflare&logoColor=white&style=for-the-badge" alt="Cloudflare Workers" />
-  <img src="https://img.shields.io/badge/GitHub-Actions-2088ff?logo=githubactions&logoColor=white&style=for-the-badge" alt="GitHub Actions" />
-  <img src="https://img.shields.io/badge/npm-registry-cb3837?logo=npm&logoColor=white&style=for-the-badge" alt="npm" />
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/Windows-10%2F11-0078d4?logo=windows&logoColor=white&style=for-the-badge" alt="Windows 10/11" />
-  <img src="https://img.shields.io/badge/Linux-AppImage%20%2F%20deb-fcc624?logo=linux&logoColor=black&style=for-the-badge" alt="Linux" />
-  <img src="https://img.shields.io/badge/macOS-API%20mode-000000?logo=apple&logoColor=white&style=for-the-badge" alt="macOS" />
-  <img src="https://img.shields.io/badge/WSL-2-4a90d9?logo=ubuntu&logoColor=white&style=for-the-badge" alt="WSL 2" />
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/providers-19-f97316?style=for-the-badge" alt="19 providers" />
-  <img src="https://img.shields.io/badge/skills-74-43853d?style=for-the-badge" alt="74 skills" />
-  <img src="https://img.shields.io/badge/tools-53-blueviolet?style=for-the-badge" alt="53 tools" />
-  <img src="https://img.shields.io/badge/channels-9-5865f2?style=for-the-badge" alt="9 channels" />
-  <img src="https://img.shields.io/badge/offline-Ollama-22c55e?style=for-the-badge" alt="offline" />
-  <img src="https://img.shields.io/badge/OAuth-Claude%20Pro%20%2B%20ChatGPT%20Plus-9333ea?style=for-the-badge" alt="OAuth subscriptions" />
-  <img src="https://img.shields.io/badge/local--first-yes-00aaaa?style=for-the-badge" alt="local-first" />
-</p>
-
-<p align="center">
-  <a href="https://aiden.taracod.com"><b>Website</b></a> &nbsp;·&nbsp;
-  <a href="https://aiden.taracod.com/contact"><b>Contact</b></a> &nbsp;·&nbsp;
-  <a href="https://discord.gg/gMZ3hUnQTm"><b>Discord</b></a> &nbsp;·&nbsp;
-  <a href="https://github.com/taracodlabs/aiden/releases/latest"><b>Download</b></a> &nbsp;·&nbsp;
-  <a href="https://amzn.to/4tpiXwM"><b>Book</b></a>
-</p>
-
----
-
-> **v4.1 — Multi-channel autonomous AI engine**
-> Telegram + MCP server + subagent fanout + voice CLI + skill mining. Hardened cron, structured markdown, cross-platform CI. See [changelog](#changelog) below.
-
----
-
-## Support Aiden
-
-Solo-built, AGPL-3.0. If Aiden saves you time, consider sponsoring development.
-
-[Sponsor →](https://razorpay.me/@whitelotus9625)
-
-Funds go to ongoing development, infrastructure costs, and contributor bounties.
-
----
-
-## Why Aiden
-
-Most AI agents answer questions. Aiden runs work end-to-end on your machine.
-
-- **Runs on your machine** — local-first, no telemetry, no cloud account required
-- **Controls your desktop** — vision loop, browser, terminal, files. Not a chatbot wrapped in a sandbox.
-- **Automates any browser** — 10 Playwright-driven tools (navigate, click, type, fill, scroll, extract, screenshot, get-url, close, captcha-check)
-- **Self-healing provider routing** — 6-slot fallback chain (`together → groq × 4`) advances slots in under a second on rate-limit
-- **OAuth subscription routing** — sign in with Claude Pro or ChatGPT Plus; queries route to your subscription quota, not pay-as-you-go
-- **Persistent memory** — `USER.md`, `SOUL.md`, `MEMORY.md` (durable facts + recent-session distillations), plus semantic recall over past sessions via the `recall_session` tool. Memory promotes itself: each session ends with a structured distillation, and durable facts graduate to a protected section that survives compression.
-- **Lives where you do** — identity files re-read every turn; edit `USER.md` mid-conversation and the change lands within one reply
-- **One command to start** — `npx aiden-runtime` installs, configures, and runs everything
-- **Honest failures** — every tool error names the tool, provider, retry count, fallback chain, error, and next step. No silent swallowing.
-- **Plugin extension** — drop a plugin into `<aiden-home>/plugins/` and call `ctx.commandRegistry.register()` to add slash commands without touching core
-- **Open source** — AGPL-3.0 core, Apache-2.0 skills. Read every line, modify anything, contribute back.
-
-Aiden is a local-first AI operating system. It runs entirely on your machine — no cloud account required, no telemetry, no data leaving your hardware unless you configure a cloud provider. It installs as a global npm package (`aiden-runtime`, ~16 MB) on Windows, Linux, WSL, and macOS — Node.js 18+ is the only prerequisite. Features: 74 bundled skills, 53 built-in tools across 11 categories, multi-layer memory architecture, self-healing provider routing across 19 providers, the ability to control your screen, browse the web, run code, send emails and messages, manage files, and hold a full conversation — offline via Ollama.
-
----
-
-## Disclaimer
-
-**Aiden is a hobby project** built solo by one person. It is provided **"as-is" without warranty of any kind**, express or implied.
-
-⚠️ **Important risks to understand before installing:**
-
-- **Aiden controls your computer.** It can run shell commands, edit or delete files, automate your browser, capture screenshots, and send messages on your behalf. Always review what it's doing, especially when running in `/yolo` (no-approval) mode.
-- **Use API keys responsibly.** You provide your own provider keys. You pay for any usage on those keys. Aiden has built-in budget caps but you should set spending limits with your provider too.
-- **Back up important data.** Aiden can patch and delete files. Always work in version-controlled directories or with backups.
-- **Skills and plugins may send data externally.** Built-in capabilities are local-first, but third-party skills you install may make external API calls. Review skill source before use.
-- **OAuth providers may change behavior.** Claude Pro and ChatGPT Plus subscription routing depends on provider-side gates. If your subscription is restricted by Anthropic/OpenAI, fall back to direct API keys.
-- **Not for production-critical work without review.** Aiden is designed for personal use and exploration. For business-critical workflows, use approval mode (default) and review every action.
-
-By installing Aiden you accept these risks. The author and contributors accept no liability for data loss, financial loss, account suspensions, or any other damages arising from use of this software.
-
-For commercial deployments with support and indemnification, see [aiden.taracod.com/contact?type=enterprise](https://aiden.taracod.com/contact?type=enterprise).
-
----
-
-## Platform support
-
-All platforms use the same npm-based install path. Node.js 18+ is the only prerequisite.
-
-| Platform | Install | Skills available |
-|---|---|---|
-| **Windows 10/11** | ✅ `npm install -g aiden-runtime` | All 74 (including Windows-only skills) |
-| **Linux** | ✅ `npm install -g aiden-runtime` | ~68 (Windows-only skills auto-skipped) |
-| **WSL 2** | ✅ `npm install -g aiden-runtime` | ~68 (Windows-only skills auto-skipped) |
-| **macOS** | ✅ `npm install -g aiden-runtime` | ~68 (Windows-only skills auto-skipped) |
-
-Windows-only skills (clipboard history, Defender, OneNote, Outlook COM, registry, Task Scheduler, etc.) are tagged `platform: windows` and silently skipped on other platforms at load time.
-
----
-
-## Get an API key
-
-Aiden needs at least one AI provider configured. You can use the setup wizard (`aiden setup`) to walk through this, or manually set keys in `.env`.
-
-**Free providers (recommended for getting started):**
-
-| Provider | Where to get a key | Free tier |
-|---|---|---|
-| **Groq** | [console.groq.com/keys](https://console.groq.com/keys) | Yes — fast Llama 3 / Qwen |
-| **Gemini** | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | Yes — generous free tier |
-| **OpenRouter** | [openrouter.ai/keys](https://openrouter.ai/keys) | Free credits + paid tier |
-| **NVIDIA NIM** | [build.nvidia.com](https://build.nvidia.com) | Free playground tier |
-
-**Paid providers:**
-
-| Provider | Where to get a key | Notes |
-|---|---|---|
-| **Anthropic** | [console.anthropic.com](https://console.anthropic.com) | Best Claude models |
-| **OpenAI** | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) | GPT-4, GPT-5 |
-| **Together AI** | [api.together.xyz/settings/api-keys](https://api.together.xyz/settings/api-keys) | Default in Aiden |
-
-**Subscription routing (use your existing subscription):**
-
-- **Claude Pro / Max** — sign in with `/auth login claude-pro` inside Aiden. Routes to your subscription quota instead of pay-as-you-go.
-- **ChatGPT Plus** — sign in with `/auth login chatgpt-plus`. Routes to Codex backend.
-
-**Fully offline (no API key needed):**
-
-- **Ollama** — install from [ollama.ai](https://ollama.ai), then `ollama pull qwen2.5:7b`. Aiden auto-detects and uses it as fallback.
-
----
-
-## Quick Start
-
-### Fastest — `npx` (no install needed)
-
-```bash
-npx aiden-runtime
-```
-
-That's it. Node.js 18+ is the only prerequisite. On first run it asks which AI provider you want (Groq is free), validates your key, saves config to `~/.aiden/`, and starts the chat REPL. Subsequent runs skip the wizard and go straight to the assistant.
-
-Or install globally for the `aiden` command:
-
-```bash
-npm install -g aiden-runtime
-aiden
-```
-
-### Prerequisites (all platforms)
-- Node.js 18+
-- Git (only for the manual install path below)
-- Ollama (optional, for offline mode): [ollama.ai](https://ollama.ai)
-
-### Windows — one-line install
-
-```powershell
-irm aiden.taracod.com/install.ps1 | iex
-```
-
-The installer verifies Node.js 18+ then runs `npm install -g aiden-runtime`. Same package as `npx aiden-runtime` above; just adds the `aiden` command to your PATH so you can launch from any terminal.
-
-### Linux / WSL / macOS — one-line install
-
-```bash
-curl -fsSL aiden.taracod.com/install.sh | bash
-```
-
-### Manual install (all platforms)
-
-```bash
-git clone https://github.com/taracodlabs/aiden.git
-cd aiden
-npm install
-cp .env.example .env
-# Edit .env — add at minimum one API key (Groq is free: console.groq.com)
-```
-
-### Run (manual install)
-
-```bash
-# Build, then start
-npm run build
-aiden                  # CLI
-
-# Or run the API server explicitly:
-npm start              # API server on port 4200
-```
-
-### After pulling updates (manual install)
-
-```bash
-git pull
-npm run build
-aiden
-```
-
-### Uninstall
-
-**Windows**
-Open *Settings → Apps* (or *Control Panel → Programs*) and uninstall **Aiden**.
-To also remove user data:
-```powershell
-Remove-Item -Recurse -Force "$env:APPDATA\aiden"
-Remove-Item -Recurse -Force "$env:LOCALAPPDATA\aiden"
-```
-
-**Linux / macOS / WSL**
-```bash
-curl -fsSL aiden.taracod.com/uninstall.sh | bash
-```
-Or manually:
-```bash
-rm -rf ~/.local/share/aiden ~/.config/aiden
-npm uninstall -g aiden-runtime
-```
-
-### Minimum .env to get started
-
-```
-GROQ_API_KEY=your_key_here   # free at console.groq.com/keys
-```
-
-Set `AIDEN_HEADLESS=true` to suppress the Electron GUI when running the packaged app.
-
----
-
-## Known limitations
-
-We're shipping honest. Things that work, things that don't:
-
-**Tested and working:**
-
-- Windows 10/11 native (primary platform, full QA)
-- Linux via WSL2 (cross-platform paths verified)
-- Together AI (default provider, fast)
-- Groq 4-slot fallback chain
-- ChatGPT Plus OAuth (verified end-to-end with Codex backend)
-- Claude Pro OAuth (verified — subscription routing, sanitised identity)
-
-**Untested at launch:**
-
-- macOS native — best-effort, may need user reports
-- Linux distributions beyond Ubuntu/Debian (Snap/Flatpak Chrome detection)
-- Hugging Face / Vercel AI Gateway providers — registered but unverified
-
-**Not in v4.0:**
-
-- OCR — not bundled (vision-loop screen capture works, but no Tesseract)
-- Full agentskills.io ecosystem install — held pending license review
-- Docker sandbox backend — dropped in v4 rewrite
-
-**Landed in v4.1:**
-
-- Telegram channel adapter (DM polling + per-chat memory) — see [docs/channels/telegram.md](docs/channels/telegram.md)
-- DeepSeek V4 Pro provider with reasoning-token streaming and per-model defaults
-- `/update` slash command + `aiden_self_update` tool — registry probe, in-process installer, platform-specific permission-denied remediations
-- Structured session distillation — each session ends with a JSON summary that promotes durable facts into a protected `MEMORY.md` section
-- `recall_session` tool — semantic search over past distilled sessions
-- Eval harness — 18 honesty scenarios (10 easy + 8 hard) with `npm run eval -- --suite honesty`
-- Subsystem health registry surfacing component status in `/doctor`
-
-**Beta features:**
-
-- OAuth providers — provider-side gates may apply, use API keys as fallback
-- Auto-update — notifies on outdated version, doesn't auto-install
-
-Found a bug? Report at https://github.com/taracodlabs/Aiden-v4/issues with output of `aiden doctor` for fast triage.
-
----
-
-## Getting Started
-
-Once Aiden is running, type these in the chat prompt:
-
-| First thing to do | What to type |
-|---|---|
-| See all available commands | `/help` |
-| Switch providers / models | `/model` |
-| List configured providers | `/providers` |
-| Browse available skills | `/skills` |
-| Run health checks | `/doctor` (or `aiden doctor` from shell) |
-| Schedule a recurring task | `/cron add "0 9 * * 1-5" 'morning briefing'` |
-| Sign in with Claude Pro | `/auth login claude-pro` |
-| Sign in with ChatGPT Plus | `/auth login chatgpt-plus` |
-
-**Ask anything in plain English** — no special syntax needed for regular tasks:
-
-```
-summarize the PDF on my desktop
-open chrome and search for latest AI news
-take a screenshot and describe what you see
-remind me to deploy at 5pm
-play me a popular hindi song
-what files did I download today
-```
-
-Type `/` to browse all 33 commands with instant search. Skills register their own dynamic slash commands at load time.
-
----
-
-## Troubleshooting
-
-**"Cannot find module" or TypeScript errors**
-```bash
-npm run build   # always rebuild after git pull
-```
-
-**"npm run serve" not found**
-There is no `serve` script. Use `npm start` instead.
-
-**Server not responding**
-```bash
-# Check if API server is running on port 4200
-netstat -ano | findstr :4200   # Windows
-lsof -i :4200                  # Linux/macOS
-```
-
-**Ollama not connecting**
-```bash
-ollama serve             # make sure Ollama is running
-ollama pull qwen2.5:7b   # pull your chosen model
-```
-
-**Changing Ollama model or inference settings** (no recompile needed — edit `.env`):
-```
-OLLAMA_MODEL=qwen2.5:7b
-OLLAMA_TEMPERATURE=0.3
-OLLAMA_CONTEXT_LENGTH=4096
-OLLAMA_NUM_GPU=99
-```
-
-**Use with any OpenAI client (Open WebUI, Chatbox, Cursor, …)**
-```
-Base URL:  http://localhost:4200
-API Key:   none required (or set AIDEN_API_KEY=… for Bearer auth)
-Model:     aiden-3.13   (alias preserved for client compatibility)
-```
-
----
-
-## Screenshots
-
-### Terminal (TUI)
-
-![TUI](docs/images/tui.png)
-
-Boot card with environment + capabilities. Status pills (core / mode / model / memory). Per-turn rule separator. Random spinner phrases. Provider/context/elapsed footer. Runs in any terminal.
-
-### Desktop app
-
-![Desktop](docs/images/dashboard.png)
-
-Full chat interface with live activity panel. Local-first, connects to Ollama or any of 19 cloud providers via your own API key.
-
-### Memory graph
-
-![Memory graph](docs/images/memory-graph.png)
-
-Multi-layer memory visualised — every conversation, task, and learned pattern becomes a node in the local knowledge graph. Persisted to disk, searchable.
-
----
-
-## Features
-
-| Category | What Aiden does |
-|---|---|
-| **Inference & providers** | 19 providers including Anthropic, OpenAI, Groq (4-slot fallback), Together, Gemini, NVIDIA NIM, OpenRouter, **DeepSeek V4 Pro** (reasoning-token streaming), Mistral, Z.ai, Kimi, MiniMax, Hugging Face, custom OpenAI-compatible endpoints, and **Ollama** for fully offline. OAuth subscription routing for Claude Pro and ChatGPT Plus. |
-| **53 built-in tools** | Web search & fetch, deep research, YouTube search, Playwright browser automation (10 tools), file ops (read, list, write, patch, delete, move, copy), process control (spawn, kill, list, log-read, wait), shell exec, code execution, system info, screenshot, clipboard, app launch/close, media keys, MCP bridge, memory add/replace/remove, session list/search/summary/recall, skill view/list/manage, and `aiden_self_update`. |
-| **74 bundled skills** | Composable workflows each with a `SKILL.md` prompt, optional helper scripts, and tool requirements. Includes: GitHub PR/issue workflows, NSE / Upstox / Zerodha trading, Censys / Shodan / VirusTotal lookups, Windows Defender / Task Scheduler, Docker management, YouTube content tools, ASCII art, and more. |
-| **Self-promoting memory** | `USER.md` + `SOUL.md` identity, plus a `MEMORY.md` split between durable facts (compression-protected) and recent-session distillations. Each session ends with a structured JSON summary that graduates durable facts into the protected section. Semantic recall over past sessions via the `recall_session` tool. Dirty-bit invalidation rebuilds the prompt when files change mid-session. |
-| **Voice** | Edge TTS / Windows SAPI text-to-speech, speech-to-text helpers. |
-| **Channel adapters** | Discord, Slack, Telegram, WhatsApp, Email (IMAP+SMTP), Webhook, Twilio SMS, iMessage (macOS), Signal — any channel triggers the same agent loop. |
-| **Computer use** | Screenshot capture, screen-state vision loop, browser automation. Mouse/keyboard automation partial. |
-| **Cron scheduler** | Persistent recurring tasks via the `croner` engine. Atomic state writes, output capture, 5/6-field cron + `@daily`/`@hourly` shortcodes. |
-| **Plugins** | Three bundled plugins: Chrome DevTools Protocol bridge, Claude Pro OAuth, ChatGPT Plus OAuth. Plugin system with permission-state machine (pending-grant / loaded / suspended). |
-| **MCP** | Model Context Protocol bridge — stdio + HTTP transports, schema discovery, tool dispatch. |
-| **Security moat** | 10-module safety layer: tiered approval engine (safe / caution / dangerous), dangerous-command pattern classifier, honesty enforcement (post-loop scan rewrites false claims), memory guard, planner-guard tool narrowing, SSRF-safe URL fetcher, secret/PII pre-write scanner, skill-teacher (auto-create skills from successful flows), pro-license gate, provider-chain glue. |
-
----
-
-## What Aiden is
-
-Aiden runs locally on your machine. It controls your desktop, browser, and terminal through natural conversation. It learns from your work and remembers what matters across sessions.
-
-- **Local-first** — your conversations and data stay on your machine. No cloud account required.
-- **Real desktop control** — vision, browser, terminal, files. Not a chatbot wrapped in a sandbox.
-- **Persistent memory** — Aiden remembers facts, preferences, and lessons from prior sessions. The longer you use it, the better it knows your work.
-- **Honest by design** — when a tool fails, Aiden surfaces the failure rather than fabricating success.
-- **Open source** — AGPL-3.0. Read every line, modify anything, contribute back.
-
----
-
-## Architecture
-
-```
-User input (any channel)
-        │
-        ▼
-  ┌───────────────────────────┐
-  │  AidenAgent — single loop │  ← per turn: build prompt → ask provider →
-  │  core/v4/aidenAgent.ts    │     dispatch tools → loop until stop
-  └────┬───────────┬──────────┘
-       │           │
-       │           ▼
-       │     ┌──────────────────┐
-       │     │  Tool dispatcher │──▶ 53 built-in tools
-       │     └──────────────────┘    + skill-driven dynamic tools
-       │
-       ▼
-  ┌─────────────────────────────────────┐
-  │  Memory                             │
-  │  USER.md · SOUL.md · MEMORY.md      │
-  │  (durable facts · recent sessions)  │
-  │  semantic recall (recall_session)   │
-  │  end-of-session distillation        │
-  └─────────────────────────────────────┘
-       │
-       ▼
-  ┌──────────────────────────────────┐
-  │  Provider router + fallback      │  ← 19 providers, 6-slot self-healing
-  │  providers/v4/runtimeResolver.ts │     chain (together → groq × 4)
-  └──────────────────────────────────┘
-       │
-       ▼
-   Response (streamed back to originating channel)
-```
-
-See [ARCHITECTURE.md](ARCHITECTURE.md) for a full layer-by-layer breakdown, prompt-slot composition, and the skill system design.
-
----
-
-## Configuration
-
-Copy `.env.example` to `.env` in the Aiden data directory.
-
-```bash
-cp .env.example .env
-```
-
-Key environment variables:
-
-| Variable | Default | Notes |
-|---|---|---|
-| `OLLAMA_HOST` | `http://127.0.0.1:11434` | Override if Ollama runs on a different host/port |
-| `OLLAMA_MODEL` | `qwen2.5:7b` | Default chat model for offline mode |
-| `ANTHROPIC_API_KEY` | — | Optional cloud provider |
-| `OPENAI_API_KEY` | — | Optional cloud provider |
-| `GROQ_API_KEY` | — | Free tier: fast Llama 3 / Qwen inference |
-| `TOGETHER_API_KEY` | — | Default cloud provider |
-| `AIDEN_HEADLESS` | `false` | `true` suppresses the Electron GUI |
-| `AIDEN_BROWSER_HEADLESS` | `false` | `true` runs Playwright headless |
-| `AIDEN_UI_ICONS` | `0` | `1` enables emoji tool-row icons |
-| `AIDEN_UI_TIMESTAMPS` | `0` | `1` prepends HH:MM:SS to chat lines |
-| `AIDEN_API_KEY` | — | Set to require Bearer auth on the OpenAI-compatible API |
-
-See `.env.example` for the full list covering voice, messaging integrations, search, computer use, and more.
-
----
-
-## Use with any OpenAI client
-
-Aiden exposes an OpenAI-compatible API at `localhost:4200`. Point any OpenAI client at Aiden to get the full agent loop instead of raw LLM inference:
-
-| Setting | Value |
-|---|---|
-| **Base URL** | `http://localhost:4200` |
-| **API Key** | *(none required locally)* |
-| **Model** | `aiden-3.13` *(alias preserved for client compatibility)* |
-
-Works with: **Open WebUI** · **LibreChat** · **Chatbox** · **Continue.dev** · **Cursor** · **TypingMind** · any app using the OpenAI SDK.
-
-```python
-# Python example — zero config
-from openai import OpenAI
-client = OpenAI(base_url="http://localhost:4200", api_key="none")
-response = client.chat.completions.create(
-    model="aiden-3.13",
-    messages=[{"role": "user", "content": "search news about AI agents"}]
-)
-print(response.choices[0].message.content)
-```
-
-Optional: set `AIDEN_API_KEY=your-secret` in `.env` to require Bearer-token authentication.
-
----
-
-## Commands
-
-### Start Aiden
-| Command | Description |
-|---|---|
-| `npx aiden-runtime` | Install, configure, and start (recommended) |
-| `aiden` | Start the chat REPL |
-| `aiden doctor` | Run diagnostic health checks |
-| `aiden setup` | Re-run the setup wizard |
-| `npm start` | Start the API server (port 4200) |
-| `npm run build` | Rebuild after source changes |
-
-### In-chat slash commands (33 total)
-
-**Session**
-| Command | Description |
-|---|---|
-| `/clear` | Clear the current conversation |
-| `/compress` | Compress the conversation to free context |
-| `/save` | Save the current session |
-| `/title` | Set a title for the session |
-| `/history` | Browse past sessions |
-| `/show` | Show session metadata |
-| `/status` | Show current session status |
-
-**Configuration**
-| Command | Description |
-|---|---|
-| `/model` | Two-step provider/model picker |
-| `/providers` | List configured providers + status |
-| `/personality` | Switch personality overlay |
-| `/skin` | Switch terminal colour skin |
-| `/streaming on\|off` | Toggle streamed responses |
-| `/reasoning` | Show reasoning toggle for capable models |
-| `/verbose compact\|normal\|verbose` | Verbosity level |
-| `/debug-prompt` | Print the system prompt for inspection |
-
-**Identity**
-| Command | Description |
-|---|---|
-| `/identity` | Print SOUL.md / USER.md identity blocks |
-
-**System**
-| Command | Description |
-|---|---|
-| `/doctor` | Run health checks |
-| `/license` | Show / set Pro license |
-| `/plugins` | List, grant, suspend plugins |
-| `/reload-mcp` | Reconnect MCP servers |
-| `/reload-soul` | Reload SOUL.md / USER.md mid-session |
-| `/tools` | List registered tools |
-| `/skills` | List, view, install skills |
-| `/usage` | Token usage + cost summary |
-| `/yolo` | No-approval mode (use carefully) |
-| `/cron` | Schedule recurring tasks |
-| `/update` | Check for / install the latest `aiden-runtime` (`install` subcommand applies) |
-| `/setup` | Re-run the setup wizard from the REPL |
-| `/channel` | List / manage channel adapters (Discord, Slack, Telegram, …) |
-| `/voice` | Toggle voice output (Edge TTS / Windows SAPI) |
-| `/quit` | Exit the REPL |
-
-**Authentication**
-| Command | Description |
-|---|---|
-| `/auth login claude-pro` | Sign in with Claude Pro / Max subscription |
-| `/auth login chatgpt-plus` | Sign in with ChatGPT Plus subscription |
-| `/auth status` | Show current auth state |
-| `/auth logout` | Sign out of OAuth providers |
-
-**Help**
-| Command | Description |
-|---|---|
-| `/help` | List all commands grouped by section |
-
-Skills can register their own dynamic slash commands at load time.
-
----
-
-## CLI vs Dashboard quick reference
-
-Both the terminal CLI and the browser dashboard (`localhost:4200/ui`) expose the full feature set. Use whichever fits your workflow.
-
-| Feature | Terminal CLI | Browser (`localhost:4200/ui`) |
-|---|---|---|
-| Chat | ✅ inline prompt | ✅ chat panel |
-| Streaming responses | ✅ token-by-token | ✅ live SSE |
-| Markdown rendering | ✅ | ✅ |
-| Slash commands | ✅ all 33 | ✅ same commands |
-| `/` command dropdown | ✅ instant, 33 commands | ✅ |
-| Provider panel | `/providers` | ✅ Providers tab |
-| Memory panel | `/identity` + tool calls | ✅ Memory tab |
-| Skills panel | `/skills` | ✅ Skills tab |
-| Plugin hooks | ✅ | ✅ |
-| MCP server mode | `aiden mcp` | — |
-| OpenAI-compatible API | — | ✅ `localhost:4200/v1` |
-
----
-
-## Tech stack
-
-- **TypeScript 5.9** — strict mode, full typing across core, providers, CLI, API.
-- **Node.js 18+** — runtime; `node-fetch` not needed (built-in `fetch`).
-- **Electron 41** — optional desktop wrapper; primary install is npm-based.
-- **Next.js (app router)** — `dashboard-next/` for the browser UI.
-- **React 18** — dashboard component model.
-- **Playwright 1.58** — browser automation backbone.
-- **Ollama** — fully offline LLM via local Ollama daemon.
-- **Model Context Protocol 1.27** — `@modelcontextprotocol/sdk` for tool / server dispatch.
-- **better-sqlite3** + **sql.js** — local persistence.
-- **croner** — cron scheduler.
-- **discord.js**, **@slack/web-api**, **whatsapp-web.js**, **twilio**, **nodemailer**, **imap-simple** — channel adapters.
-- **Vitest 4** — test runner; ~1,983 unit + integration tests.
-- **esbuild** — bundler for the npm package; **electron-builder** — optional desktop wrapper.
-- **Cloudflare Workers** — landing page + license server + install-script proxy.
-
----
-
-## Contributing
-
-Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
-
-**Quickstart:**
-
-```bash
-git clone https://github.com/taracodlabs/aiden.git
-cd aiden
-npm install
-cp .env.example .env   # add at minimum one API key (Groq is free: console.groq.com/keys)
-npm run build
-aiden                  # CLI
-```
-
-- Bug fixes and new skills are the easiest entry points.
-- All contributors sign the [CLA](.github/CLA.md) once via PR comment.
-- Follow [Conventional Commits](https://www.conventionalcommits.org/).
-- Run `npm run typecheck` and `npm test` before opening a PR.
-
-### Evals — measuring behavior at scale
-
-Aiden ships an opt-in eval harness that runs scenario-based behavior checks
-against a real provider. Distinct from `npm test` (unit / integration) — evals
-are scenario-driven, make live LLM calls, and are *measurement* rather than
-release gates.
-
-```bash
-npm run eval                                  # default suite (honesty), default provider
-npm run eval:honesty                          # explicit suite
-npm run eval -- --scenario honesty/no-fabricated-file-contents
-npm run eval -- --provider groq --model llama-3.3-70b-versatile
-npm run eval -- --strict                      # exit 1 on any failure (for CI)
-```
-
-Results land in `evals/results/<timestamp>.json` (gitignored — local history).
-Eval failures are signal, not gates: the runner exits 0 unless `--strict`.
-
-Default provider: `chatgpt-plus / gpt-5.5`. Falls back to the test-provider
-chain (Groq / Together via env-var keys) when ChatGPT Plus isn't authed.
-
-Available suites: `honesty` (18 scenarios — 10 easy + 8 hard — covering
-fabricated content, fake "I found" claims, claimed actions without tool calls,
-unverified completions, write/read mismatches, and post-cutoff version claims).
-
----
-
-## Community
-
-| | |
-|---|---|
-| **Discord** | [discord.gg/gMZ3hUnQTm](https://discord.gg/gMZ3hUnQTm) — chat, support, share what you build |
-| **Skills registry** | [agentskills.io](https://agentskills.io) — agentskills.io-compatible format |
-| **Bug reports & features** | [github.com/taracodlabs/aiden/issues](https://github.com/taracodlabs/aiden/issues) |
-| **Star the repo** | [github.com/taracodlabs/aiden](https://github.com/taracodlabs/aiden) ⭐ |
-| **npm** | [`npm install -g aiden-runtime`](https://www.npmjs.com/package/aiden-runtime) |
-| **Sponsor** | [github.com/sponsors/taracodlabs](https://github.com/sponsors/taracodlabs) |
-
----
-
-## Documentation
-
-| Document | Description |
-|---|---|
-| [ARCHITECTURE.md](ARCHITECTURE.md) | Layer-by-layer breakdown, data flow diagrams, skill system design |
-| [AGENTS.md](AGENTS.md) | Agent-loop contract — public API, honesty moat, memory layers |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute — skills, tools, providers, docs |
-| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community standards |
-| [CHANGELOG.md](CHANGELOG.md) | Full release history |
-| [.env.example](.env.example) | All ~90 environment variables with descriptions |
-| [workspace-templates/](workspace-templates/) | Starter workspace configs and example plugins |
-| **Download installer** | [github.com/taracodlabs/aiden-releases/releases/latest](https://github.com/taracodlabs/aiden-releases/releases/latest) |
-| **Releases & changelog** | [github.com/taracodlabs/aiden-releases](https://github.com/taracodlabs/aiden-releases) |
-| **License** | AGPL-3.0 core · Apache-2.0 skills |
-
----
-
-## Migration from v3.x
-
-> v4.0.0 is a clean rewrite. Existing v3 installs need a migration step:
-
-- **npm package renamed** — `aiden-os` → `aiden-runtime`. Run `npm uninstall -g aiden-os && npm install -g aiden-runtime`.
-- **Slash commands consolidated** — v3's `/switch`, `/budget`, `/memory`, `/profile`, `/permissions`, `/sandbox`, `/retry`, `/failed`, `/publish` are gone. Use `/model`, `/usage`, `/identity`, `/yolo` for equivalent functionality. See `/help` for the v4 list.
-- **Docker sandbox dropped** — `AIDEN_SANDBOX_MODE` no longer applies. Tools run on the host. The `tirithScanner` secret/PII guard, `ssrfProtection`, and tiered approval engine remain as the safety layer.
-- **Skill registry install changed** — auto-fetch from external repos held pending license review. Skills install via `/skills install <local-path-or-url>` only at v4.0.
-- **Config compatible** — most environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GROQ_API_KEY`, etc.) are recognised as-is. Copy your existing `.env` and Aiden picks them up.
-
----
-
-## More from the author
-
-If you want a deeper read on the philosophy behind Aiden — autonomy, local-first AI, why solo developers should build their own tools — Shiva's book is on Amazon:
-
-[**Build your own thing — solo-dev playbook**](https://amzn.to/4tkLnrE)
-
-Buying the book directly funds Aiden's development.
-
----
-
-## Sponsors
-
-Aiden is built and maintained by one person. If it saves you time, consider sponsoring:
-
-[![Sponsor on GitHub](https://img.shields.io/badge/sponsor-❤-pink?style=for-the-badge)](https://github.com/sponsors/shivadeore111-design)
-[![Donate via Razorpay](https://img.shields.io/badge/donate-Razorpay-blue?style=for-the-badge)](https://razorpay.me/@whitelotus9625)
-
----
-
-## Changelog
-
-See [CHANGELOG.md](CHANGELOG.md) for the full history.
-
-**v4.1.2 highlights:**
-
-- 🧠 **Self-promoting memory** — sessions end with a structured JSON distillation; durable facts graduate into a compression-protected `MEMORY.md` section that survives `/compress`. Recent-session distillations are kept separately for `recall_session` semantic search.
-- 🔍 **`recall_session` tool** — query past sessions in natural language; returns ranked distillations with date + summary + relevant facts.
-- 🛰 **DeepSeek V4 Pro provider** — reasoning-token streaming, per-model defaults (`MODEL_DEFAULTS`), probe filtering for codex-only slugs.
-- ⬆ **`/update` slash command + `aiden_self_update` tool** — npm-registry probe with 6h boot cache, in-process `executeInstall` shared between both surfaces, platform-specific permission-denied remediations (Windows admin / sudo / user-local prefix). No silent self-escalation, no false claims of in-place upgrade.
-- 🧪 **Eval harness** — 18 honesty scenarios (10 easy + 8 hard); `npm run eval -- --suite honesty`, results land in `evals/results/<timestamp>.json`.
-- 🩺 **Subsystem health registry** — `/doctor` surfaces component status with a uniform OK / WARN / FAIL contract.
-- 🔒 **Memory-guard hardening** — section-aware `## Durable facts` protection, word-boundary regex anchors, entry-delimited storage, case-insensitive dedup with separator tolerance.
-- ✅ **~1,983 tests passing** — regression guards for every smoke-test bug found in earlier slices.
-
-**v4.0.0 highlights:**
-
-- 🧠 **Clean-room core rewrite** — every adapter, every prompt slot, every loop. 7 dual-attribution files rewritten under full Aiden copyright.
-- 🔌 **19 providers** including OAuth subscription routing for Claude Pro and ChatGPT Plus (subscription quota, not pay-as-you-go).
-- ⚡ **Single-loop agent** — sequential tool dispatch, 90-turn cap with budget warnings at 70 % / 90 %.
-- 🛡 **6-slot self-healing fallback** — together → groq × 4 → cooldown + least-used selection.
-- 🎨 **Neofetch-style boot card** — banner + status pills + Environment / Capabilities + parchment credits + bottom hint.
-- 🕒 **Cron scheduler** — `/cron add|list|pause|resume|delete|run` with atomic state writes and output capture.
-- 🧰 **42 built-in tools across 11 categories** — web, files, browser (10), sessions, skills, memory, process, system, terminal, code, MCP.
-- 🤖 **Inline JSON tool-call recovery** — Llama / Qwen / NVIDIA-Llama emit raw JSON in answer text? It's detected, validated against the request's tool list, and dispatched as a proper tool call. Code-fenced examples are left alone.
-- 🎙 **Spinner has personality** — 20-phrase pool (Thinking · Brewing · Cogitating · Brain yakka · …) sampled per turn.
-- 🪶 **Env-gated polish** — `AIDEN_UI_ICONS=1` for tool-row emoji, `AIDEN_UI_TIMESTAMPS=1` for HH:MM:SS line prefix.
-- 🧹 **Honest failure surface** — every tool failure names the tool, provider, retry count, fallback chain, error, and next step.
-
----
-
-## License
-
-| Component | License |
-|---|---|
-| Core (`cli/`, `api/`, `core/`, `providers/`, `dashboard-next/`) | [AGPL-3.0-only](LICENSE) |
-| Skills (`skills/`) | [Apache-2.0](LICENSE-SKILLS.md) |
-
-### Commercial use
-
-Aiden's core is **AGPL-3.0**. You can self-host, modify, and study it freely. Embedding it in a closed-source commercial product or offering it as a hosted service requires either releasing your modifications under AGPL-3.0 or purchasing a commercial license.
-
-Skills in `skills/` are **Apache-2.0** and can be used in commercial products without copyleft obligations.
-
-For commercial licensing and enterprise deployments: **[aiden.taracod.com/contact?type=enterprise](https://aiden.taracod.com/contact?type=enterprise)**
-
----
-
-Built by [Taracod](https://taracod.com) · Built by Shiva Deore · AGPL-3.0
+<img width="1672" height="941" alt="AIDEN BOOTUP LOGO" src="https://github.com/user-attachments/assets/c0809009-73e2-4d58-9292-12fbd0324952" />
+
+```
+█████╗  ██╗██████╗ ███████╗███╗   ██╗
+██╔══██╗██║██╔══██╗██╔════╝████╗  ██║
+███████║██║██║  ██║█████╗  ██╔██╗ ██║
+██╔══██║██║██║  ██║██╔══╝  ██║╚██╗██║
+██║  ██║██║██████╔╝███████╗██║ ╚████║
+╚═╝  ╚═╝╚═╝╚═════╝ ╚══════╝╚═╝  ╚═══╝
+
+Autonomous AI Engine — local-first, Windows-native, yours to own
+
+74 skills · 59 tools · 19 providers · 9 channels · AGPL-3.0
+
+Windows · Linux · WSL · macOS (API Mode)
+```
+
+<p align="center">
+  <a href="https://github.com/taracodlabs/aiden/releases/latest"><img src="https://img.shields.io/badge/version-v4.5.0-f97316?style=for-the-badge" alt="v4.5.0" /></a>
+  <a href="https://www.npmjs.com/package/aiden-runtime"><img src="https://img.shields.io/npm/v/aiden-runtime?color=f97316&label=npm&style=for-the-badge" alt="npm" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-orange?style=for-the-badge" alt="License: AGPL-3.0" /></a>
+  <a href="https://discord.gg/gMZ3hUnQTm"><img src="https://img.shields.io/badge/chat-discord-7289da?logo=discord&logoColor=white&style=for-the-badge" alt="Discord" /></a>
+  <a href="https://github.com/taracodlabs/aiden/stargazers"><img src="https://img.shields.io/github/stars/taracodlabs/aiden?style=for-the-badge&color=f9d71c" alt="Stars" /></a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/TypeScript-5.9-3178c6?logo=typescript&logoColor=white&style=for-the-badge" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/Node.js-18+-43853d?logo=node.js&logoColor=white&style=for-the-badge" alt="Node.js 18+" />
+  <img src="https://img.shields.io/badge/SQLite-003b57?logo=sqlite&logoColor=white&style=for-the-badge" alt="SQLite" />
+  <img src="https://img.shields.io/badge/Playwright-1.58-2ea44f?logo=playwright&logoColor=white&style=for-the-badge" alt="Playwright" />
+  <img src="https://img.shields.io/badge/MCP-1.27-7c3aed?style=for-the-badge" alt="Model Context Protocol" />
+</p>
+
+---
+
+## What's new in v4.5
+
+Aiden now wakes up by itself.
+
+- **Persistent daemon mode (opt-in).** `AIDEN_DAEMON=1` boots a background service with a SQLite-backed trigger bus. File watchers, webhook endpoints, IMAP polling, and cron schedules all feed the same durable queue.
+- **Autonomous trigger dispatch.** When a trigger fires, a real AidenAgent turn runs end-to-end — same tools, same sandbox, same recovery pipeline as your interactive REPL. Surface the chain with `aiden runs show <id>`.
+- **Execution sandbox with risk tiers.** Filesystem allowlist + Docker session backend + dry-run preflight. Default on; flip live with `/sandbox on|off`.
+- **State-aware browser depth.** URL + DOM + iframe-tree capture before/after every browser tool call. Stale-ref auto-retry. Surfaces login / 2FA / captcha / consent blockers as structured cards.
+- **Continuous error recovery (TCE).** 16 failure categories classified per tool call. Smart retry with cooldown. Dead-letter for permanent failures. Recovery report enriches the REPL's capability card.
+- **Live-flip slash commands.** `/sandbox`, `/tce`, `/browser-depth`, `/daemon status`, `/suggestions`, `/update` — toggle every subsystem without restart. Choices persist to `config.yaml`.
+- **Update notification + `/update` CLI.** Boot prompt when a newer version is on npm. Skip-this-version persistence. Install-method detection (npm-global / npx / standalone). Q-U6: spawn directly when supported, print command when not.
+
+Full v4.5 internals: `docs/v4.5/` (overview, triggers, architecture, daemon on Linux/macOS/Windows, troubleshooting).
+
+---
+
+## Try it in 60 seconds
+
+```bash
+npm install -g aiden-runtime
+aiden
+```
+
+That's it. Pick a provider (Groq is free + fastest), paste your key, and start chatting.
+
+Want autonomous triggers?
+
+```bash
+export AIDEN_DAEMON=1          # PowerShell: $env:AIDEN_DAEMON = "1"
+aiden trigger add file --path ~/Documents/inbox --label "watch-inbox" --include "*.txt"
+aiden                          # boots the REPL + dispatcher
+```
+
+Drop a file in `~/Documents/inbox/anything.txt` and Aiden acts on it. The agent turn is visible via `aiden runs list`.
+
+---
+
+## Core capabilities
+
+| Category | What Aiden does |
+|---|---|
+| **Inference & providers** | 19 providers: Anthropic, OpenAI, Groq, Gemini, OpenRouter, Together, NVIDIA NIM, DeepSeek, Mistral, Z.ai, Kimi, MiniMax, Hugging Face, Ollama (fully offline), custom OpenAI-compatible endpoints. OAuth subscription routing for Claude Pro and ChatGPT Plus. |
+| **59 built-in tools** | Web search & fetch, deep research, YouTube search, Playwright browser automation (10 tools), file ops, process control, shell exec, code execution, system info, screenshot, clipboard, app launch, media keys, MCP bridge, memory ops, session list/search/summary/recall, skill view/list/manage, `aiden_self_update`. |
+| **74 bundled skills** | Composable workflows each with a `SKILL.md` prompt, optional helper scripts, and tool requirements. GitHub PR/issue workflows, NSE / Upstox / Zerodha trading, Censys / Shodan / VirusTotal lookups, Windows Defender / Task Scheduler, Docker management, YouTube content tools, and more. |
+| **Self-promoting memory** | `USER.md` + `SOUL.md` identity, plus `MEMORY.md` split between durable facts (compression-protected) and recent-session distillations. Each session ends with a structured summary that graduates durable facts into the protected section. Semantic recall over past sessions via `recall_session`. |
+| **Voice** | Edge TTS / Windows SAPI text-to-speech, speech-to-text helpers. |
+| **Channel adapters** | Discord, Slack, Telegram, WhatsApp, Email (IMAP+SMTP), Webhook, Twilio SMS, iMessage (macOS), Signal — any channel triggers the same agent loop. |
+| **Computer use** | Screenshot capture, screen-state vision loop, browser automation. Mouse/keyboard automation partial. |
+| **v4.5 daemon mode (opt-in)** | File watcher / webhook / email IMAP / scheduled triggers route through a durable trigger bus consumed by the Phase 5a dispatcher. Triggers fire → real agent runs → tool calls execute → `run_events` captures the chain. Off by default. |
+| **Plugins** | Three bundled plugins: Chrome DevTools Protocol bridge, Claude Pro OAuth, ChatGPT Plus OAuth. Permission-state machine (pending-grant / loaded / suspended). |
+| **MCP** | Model Context Protocol bridge — stdio + HTTP transports, schema discovery, tool dispatch. |
+| **Security moat** | Tiered approval engine (safe / caution / dangerous), dangerous-command pattern classifier, honesty enforcement (post-loop scan rewrites false claims), memory guard, planner-guard tool narrowing, SSRF-safe URL fetcher, secret/PII pre-write scanner, skill-teacher (auto-create skills from successful flows). |
+
+---
+
+## Architecture (one paragraph)
+
+Aiden is a local-first agent loop: provider adapters feed a 90-turn ceiling, every tool call passes through verification + failure classification + recovery, and tool results stream back as structured envelopes the model can reason over. v4.5 added a SQLite daemon foundation alongside the REPL — file watchers and webhook endpoints write to a durable trigger bus, a single-worker dispatcher claims events, and each trigger fires a fresh agent turn keyed by a stable session id. Sandboxed execution (filesystem allow/deny + Docker session backend), state-aware browser observation, and continuous error recovery apply to daemon-fired turns identically to REPL turns. Detailed diagrams + module map in [`docs/v4.5/architecture.md`](./docs/v4.5/architecture.md).
+
+---
+
+## Install + first run
+
+### Linux / WSL / macOS (one-line)
+
+```bash
+npm install -g aiden-runtime
+aiden            # interactive setup wizard fires on first run
+```
+
+### Windows (one-line)
+
+```powershell
+npm install -g aiden-runtime
+aiden
+```
+
+If you hit native-build errors on Windows, install the [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) prerequisite first.
+
+### Try without installing
+
+```bash
+npx aiden-runtime
+```
+
+### After pulling updates
+
+```bash
+npm install -g aiden-runtime@latest
+```
+
+Or, from inside a running session, the slash command:
+
+```
+/update install
+```
+
+(Aiden also prompts you on boot when a newer version is on npm — see `/update auto off` to silence.)
+
+### Daemon mode (opt-in)
+
+**Linux:** install a systemd `--user` unit.
+
+```bash
+export AIDEN_DAEMON=1
+aiden daemon install
+loginctl enable-linger $USER     # keep running between sessions
+```
+
+**macOS:** install a launchd plist.
+
+```bash
+export AIDEN_DAEMON=1
+aiden daemon install
+```
+
+**Windows:** see [`docs/v4.5/daemon-windows.md`](./docs/v4.5/daemon-windows.md). Recommended: foreground (`aiden daemon start`) or `pm2` for background.
+
+---
+
+## Configuration
+
+Aiden reads `~/.aiden/config.yaml` (Linux/macOS) or `%LOCALAPPDATA%\aiden\config.yaml` (Windows). The setup wizard writes a starter config on first boot; subsequent edits are diff-merged.
+
+### Common env vars
+
+| Variable | Default | Effect |
+|---|---|---|
+| `AIDEN_DAEMON` | `0` | Set to `1` to boot the daemon foundation alongside the REPL |
+| `AIDEN_DAEMON_PORT` | `4200` | Daemon HTTP listener port |
+| `AIDEN_DAEMON_BIND` | `127.0.0.1` | Loopback-only by default; non-loopback requires `AIDEN_API_KEY` |
+| `AIDEN_DAEMON_DAILY_BUDGET` | unset | Hard daily token cap across daemon turns; resets midnight UTC |
+| `AIDEN_DAEMON_MODEL` | unset | Override model for daemon turns (`<provider>/<model>`) |
+| `AIDEN_SANDBOX` | `1` | `0` to disable filesystem allowlist + Docker session backend |
+| `AIDEN_TCE` | `1` | `0` to disable continuous error recovery |
+| `AIDEN_BROWSER_DEPTH` | `1` | `0` to disable state-aware browser observation |
+| `AIDEN_API_KEY` | unset | Required for non-loopback daemon bind |
+| `AIDEN_NO_UPDATE_CHECK` | `0` | Set to `1` to silence the boot-time update probe |
+
+Most flags are also flippable live via slash commands:
+
+| Slash command | Effect |
+|---|---|
+| `/sandbox on\|off\|status` | Filesystem + execution sandbox |
+| `/tce on\|off\|status` | Continuous error recovery |
+| `/browser-depth on\|off\|status` | State-aware browser observer |
+| `/suggestions on\|off\|status` | Contextual capability hints |
+| `/daemon status` | Read-only daemon snapshot (port, triggers, recent runs, daily budget) |
+| `/update check\|install\|skip <v>\|auto on\|off` | Update probe + install |
+| `/cron add\|list\|show\|run\|remove` | Scheduled jobs |
+| `/runs list\|show <id>\|interrupt\|stats` | Daemon run history |
+
+Full reference: [`docs/v4.5/`](./docs/v4.5/).
+
+---
+
+## In-chat slash commands (38 total)
+
+Type `/help` inside Aiden for the full list grouped by category. Highlights:
+
+- **Configuration** — `/model`, `/personality`, `/skin`, `/streaming`, `/reasoning`, `/verbose`, `/debug-prompt`, `/identity`
+- **Session** — `/clear`, `/compress`, `/save`, `/title`, `/usage`
+- **System** — `/sandbox`, `/tce`, `/browser-depth`, `/daemon`, `/suggestions`, `/update`, `/skills`, `/tools`, `/plugins`, `/cron`, `/runs`, `/trigger`, `/doctor`, `/status`, `/show`, `/history`
+- **Auth** — `/auth login`, `/auth status`, `/auth refresh`
+- **MCP** — `/reload-mcp`, `/setup`
+
+---
+
+## Troubleshooting
+
+Common issues live in [`docs/v4.5/troubleshooting.md`](./docs/v4.5/troubleshooting.md). Quick reference:
+
+- **"daemon already running"** — stale `~/.aiden/daemon/runtime.lock`; remove it
+- **Webhook 401 despite valid HMAC** — check format (`github` / `gitlab` / `generic`)
+- **IMAP auth failure** — Gmail / Outlook require app passwords, not account passwords
+- **High RSS / slow drain** — run the 72-hour soak (`tests/v4/daemon/soak/README.md`)
+- **Boot stuck on wizard** — non-TTY stdin (CI / piped); set provider env var or use `--no-ui`
+- **`/help` doesn't list a command** — that command likely needs an active session field; run from a real REPL
+
+---
+
+## Acknowledgements
+
+Built solo by **Shiva Deore** at [Taracod](https://taracod.com).
+
+Aiden builds on the open-source giants: TypeScript, Node, SQLite, better-sqlite3, Playwright, Chromium, chokidar, croner, inquirer, marked, kleur, the Model Context Protocol, and every provider SDK. Thank you.
+
+If you use Aiden in production, on a side project, or just to learn — a star on the repo is appreciated. Bug reports and feature ideas go on the [GitHub issue tracker](https://github.com/taracodlabs/aiden/issues).
+
+---
+
+## License
+
+- **Core runtime**: [AGPL-3.0](./LICENSE).
+- **Bundled skills**: [Apache-2.0](./skills/LICENSE). The future `skills.taracod.com` marketplace will ship community skills under the same permissive terms.
+
+AGPL-3.0 means: you can self-host, modify, and distribute Aiden as long as your modifications stay under AGPL. Commercial licensing for closed-source derivatives: contact <hello@taracod.com>.
+
+---
+
+## Links
+
+- Website: [aiden.taracod.com](https://aiden.taracod.com)
+- Docs: [`docs/v4.5/`](./docs/v4.5/) (in this repo)
+- Discord: [discord.gg/gMZ3hUnQTm](https://discord.gg/gMZ3hUnQTm)
+- Source: [github.com/taracodlabs/aiden](https://github.com/taracodlabs/aiden)
+- Standalone releases: [github.com/taracodlabs/aiden-releases](https://github.com/taracodlabs/aiden-releases)
+- npm: [aiden-runtime](https://www.npmjs.com/package/aiden-runtime)
+- Author's book: [_Omega_](https://amzn.to/4tpiXwM)
+
+---
+
+<p align="center">
+  <em>Local-first. Windows-native. Yours to own.</em>
+</p>