AIDEN BOOTUP LOGO ``` █████╗ ██╗██████╗ ███████╗███╗ ██╗ ██╔══██╗██║██╔══██╗██╔════╝████╗ ██║ ███████║██║██║ ██║█████╗ ██╔██╗ ██║ ██╔══██║██║██║ ██║██╔══╝ ██║╚██╗██║ ██║ ██║██║██████╔╝███████╗██║ ╚████║ ╚═╝ ╚═╝╚═╝╚═════╝ ╚══════╝╚═╝ ╚═══╝ Autonomous Work Engine — plans, acts, recovers, and proves the result 76 skills · 121 tools · 19 providers · 9 channels · AGPL-3.0 Windows · Linux · WSL · macOS (API Mode) ```
# Aiden **Autonomous Work Engine — plans, acts, recovers, and proves the result** Give Aiden a goal. It can work across your files, terminal, browser, supported applications, APIs, and connected services to get the job done. *76 skills · 121 tools · 19 providers · 9 channels · AGPL-3.0* **Windows · Linux · WSL · macOS API mode**
[![npm version](https://img.shields.io/npm/v/aiden-runtime?color=FF6B35&label=npm&style=for-the-badge)](https://www.npmjs.com/package/aiden-runtime) [![npm downloads](https://img.shields.io/npm/dm/aiden-runtime?color=FF6B35&style=for-the-badge)](https://www.npmjs.com/package/aiden-runtime) [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-FF6B35?style=for-the-badge)](LICENSE) [![GitHub stars](https://img.shields.io/github/stars/taracodlabs/aiden?color=FF6B35&style=for-the-badge)](https://github.com/taracodlabs/aiden/stargazers) [![GitHub forks](https://img.shields.io/github/forks/taracodlabs/aiden?color=FF6B35&style=for-the-badge)](https://github.com/taracodlabs/aiden/network/members) [![GitHub issues](https://img.shields.io/github/issues/taracodlabs/aiden?color=FF6B35&style=for-the-badge)](https://github.com/taracodlabs/aiden/issues)
[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/CU5wshJW4F) [![Website](https://img.shields.io/badge/Website-aiden.taracod.com-FF6B35?style=for-the-badge&logo=safari&logoColor=white)](https://aiden.taracod.com) [![Book: Omega](https://img.shields.io/badge/Book-Omega-FFB088?style=for-the-badge&logo=amazon&logoColor=white)](https://amzn.to/49ceO8l) [![Email](https://img.shields.io/badge/Contact-contact@taracod.com-4ADE80?style=for-the-badge&logo=gmail&logoColor=white)](mailto:contact@taracod.com) [![Sponsor via Razorpay](https://img.shields.io/badge/Sponsor-Razorpay-3395FF?style=for-the-badge&logo=razorpay&logoColor=white)](https://razorpay.me/@whitelotus9625)
Technology, platform, provider, channel, and runtime details
![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript&logoColor=white) ![JavaScript](https://img.shields.io/badge/JavaScript-ES2022-F7DF1E?style=flat-square&logo=javascript&logoColor=black) ![Node.js](https://img.shields.io/badge/Node.js-≥18-339933?style=flat-square&logo=node.js&logoColor=white) ![ESM](https://img.shields.io/badge/Modules-ESM-FFB088?style=flat-square) ![esbuild](https://img.shields.io/badge/Bundler-esbuild-FFCF00?style=flat-square&logo=esbuild&logoColor=black) ![npm](https://img.shields.io/badge/Registry-npm-CB3837?style=flat-square&logo=npm&logoColor=white) ![Windows](https://img.shields.io/badge/Windows-11-0078D6?style=flat-square&logo=windows&logoColor=white) ![Linux](https://img.shields.io/badge/Linux-supported-FCC624?style=flat-square&logo=linux&logoColor=black) ![WSL](https://img.shields.io/badge/WSL-2-4D4D4D?style=flat-square&logo=linux&logoColor=white) ![macOS](https://img.shields.io/badge/macOS-API_mode-000000?style=flat-square&logo=apple&logoColor=white) ![PowerShell](https://img.shields.io/badge/PowerShell-7-5391FE?style=flat-square&logo=powershell&logoColor=white) ![SQLite](https://img.shields.io/badge/SQLite-FTS5-003B57?style=flat-square&logo=sqlite&logoColor=white) ![better-sqlite3](https://img.shields.io/badge/better--sqlite3-11.x-003B57?style=flat-square&logo=sqlite&logoColor=white) ![Playwright](https://img.shields.io/badge/Playwright-browser-45ba4b?style=flat-square&logo=playwright&logoColor=white) ![Chromium](https://img.shields.io/badge/Chromium-headless-4285F4?style=flat-square&logo=googlechrome&logoColor=white) ![Docker](https://img.shields.io/badge/Docker-sandbox-2496ED?style=flat-square&logo=docker&logoColor=white) ![MCP](https://img.shields.io/badge/Model_Context_Protocol-1.0-FF6B35?style=flat-square) ![SSE](https://img.shields.io/badge/SSE-streaming-FF6B35?style=flat-square) ![Daemon mode](https://img.shields.io/badge/Daemon-opt--in-FFB088?style=flat-square) ![Sub-agents](https://img.shields.io/badge/Sub--agents-fanout-FFB088?style=flat-square) ![TCE](https://img.shields.io/badge/TCE-error_recovery-4ADE80?style=flat-square) ![Guardrails](https://img.shields.io/badge/Guardrails-tiered-FBBF24?style=flat-square) ![BYOK](https://img.shields.io/badge/BYOK-pure-FF6B35?style=flat-square) ![Groq](https://img.shields.io/badge/Groq-fast-F55036?style=flat-square) ![Anthropic](https://img.shields.io/badge/Anthropic-Claude-D97757?style=flat-square&logo=anthropic&logoColor=white) ![OpenAI](https://img.shields.io/badge/OpenAI-GPT-412991?style=flat-square&logo=openai&logoColor=white) ![Gemini](https://img.shields.io/badge/Google-Gemini-4285F4?style=flat-square&logo=google&logoColor=white) ![Ollama](https://img.shields.io/badge/Ollama-local-000000?style=flat-square&logo=ollama&logoColor=white) ![+14 more](https://img.shields.io/badge/+14_more-providers-B8A893?style=flat-square) ![Discord channel](https://img.shields.io/badge/Channel-Discord-5865F2?style=flat-square&logo=discord&logoColor=white) ![Slack channel](https://img.shields.io/badge/Channel-Slack-4A154B?style=flat-square&logo=slack&logoColor=white) ![Telegram channel](https://img.shields.io/badge/Channel-Telegram-26A5E4?style=flat-square&logo=telegram&logoColor=white) ![Email channel](https://img.shields.io/badge/Channel-Email-EA4335?style=flat-square&logo=gmail&logoColor=white) ![Webhook channel](https://img.shields.io/badge/Channel-Webhook-FF6B35?style=flat-square) ![+4 more](https://img.shields.io/badge/+4_more-channels-B8A893?style=flat-square) ![Built solo](https://img.shields.io/badge/Built-solo-B8A893?style=flat-square) ![By Taracod](https://img.shields.io/badge/By-Taracod-FF6B35?style=flat-square) ![White Lotus](https://img.shields.io/badge/Brand-White_Lotus-FFB088?style=flat-square) ![v4.15.1](https://img.shields.io/badge/Latest-v4.15.1-4ADE80?style=flat-square)

**[Install](#try-it-in-60-seconds) · [Capabilities](#core-capabilities) · [Models](#switching-models) · [Skills](#skills) · [Commands](#cli-commands) · [Documentation](docs/v4.5/) · [Discord](https://discord.gg/CU5wshJW4F)**

Aiden terminal interface https://github.com/user-attachments/assets/1081e5c5-f1ec-4980-b710-1640981ec58b > **Aiden is an autonomous AI engine for real computer work.** It can plan multi-step jobs, use your files, terminal, browser, supported applications, APIs, and connected services, remember what matters, recover from failures, and check whether the requested result was actually produced. Built solo. Open source. Actively developed.
## Why Aiden is useful Most AI tools stop at advice. Aiden is built to move from a goal to real execution while keeping you in control. ```text Goal → Plan → Tools → Permission → Execution → Recovery → Evidence → Result ``` - **Give it a job, not dozens of tiny prompts.** Aiden can plan and continue through longer, multi-step work. - **Let it use real tools.** It can work with files, shell commands, code, browser workflows, APIs, MCP servers, applications, and channels. - **Stay in control.** Risk-tiered approvals, trust levels, budgets, interruption, and scoped permissions keep consequential actions visible. - **See what happened.** Runs, events, tasks, artifacts, tests, and verification results make the work inspectable. - **Use the models you prefer.** Choose among 19 providers, subscription-backed sign-in where supported, custom endpoints, or Ollama. - **Run it across your setup.** Aiden supports Windows, Linux, WSL, and macOS API mode. ### What you can use it for | Use case | Example | |---|---| | **Codebase work** | Inspect a repository, trace a bug, make focused changes, run tests, and report what changed. | | **Research and reports** | Search, compare sources, collect findings, and save a structured deliverable. | | **Browser workflows** | Navigate supported websites, fill forms, work with tabs and dialogs, and capture outcomes. | | **Background automation** | React to files, schedules, email, and webhooks through the opt-in daemon. | | **Personal operations** | Organize files, inspect system state, run repeatable procedures, and remember useful context. | | **Multi-agent work** | Delegate focused parts of a larger job to isolated sub-agents and combine the results. | ### Good first prompts ```text Inspect this repository, explain how it works, and identify the three highest-risk areas. ``` ```text Find the cause of the failing tests, fix the root problem, rerun the relevant tests, and show me what changed. ``` ```text Research this topic, compare the strongest findings, and save a structured Markdown report. ```
## Try it in 60 seconds ```bash npm install -g aiden-runtime aiden ``` That’s it. Choose a provider, complete the connection check, and give Aiden its first job. **Want Aiden to react to files, schedules, email, or webhooks? Enable 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`.
https://github.com/user-attachments/assets/7a66bc19-8b17-4b01-be85-3aa5945a1b3b
## What's new in v4.15.1 **Provider setup and runtime usage are now more reliable, measurable, and efficient.** This release keeps setup, provider execution, usage reporting, and restart behavior aligned from the first credential prompt through later sessions. - **Reliable provider onboarding.** Managed credentials are persisted and verified before setup completes, and the same configuration is used after restart. - **Live Ollama inventory.** Installed models are discovered from the local runtime, exact tags are accepted, and unavailable recommendations are not presented as installed. - **Clear provider diagnostics.** Throughput limits, context-window limits, and request-size limits are classified separately with appropriate recovery guidance. - **Usage modes and controls.** Economy, Balanced, and Thorough modes work with new usage, estimate, and budget commands. - **Complete attempt accounting.** Primary calls, retries, fallbacks, auxiliary work, subagents, aggregation, compression, cache usage, and reasoning usage are visible without reporting unknown cost as zero. - **Persistent efficiency.** Repeated tool and file context is reduced, while compression and usage state survive restart. See the full [v4.15.1 release notes](https://github.com/taracodlabs/aiden/releases/tag/v4.15.1).
Earlier v4 release highlights — v4.13 through v4.5
## What's new in v4.13 **Aiden can now take a job, verify it, and keep going safely.** - **Durable autonomy.** Every task gets a job-card; Aiden verifies work before claiming success, resumes after restart, avoids duplicate sends/actions, retries recoverable failures, and stops for permissions. - **Evidence-required subagents.** Helper agents must return real proof — a file, test result, id, or similar artifact — and Aiden re-checks that proof before trusting the result. - **Trust dial.** Choose how much Aiden can do: Observer, Assistant, or Partner. Destructive actions and spending still ask, even at the highest setting. - **Glass dashboard + operator TUI.** Watch model, token, budget, elapsed time, and tool steps live. Queue a follow-up, redirect mid-task, or interrupt cleanly while Aiden works. - **One-shot mode + polish.** `aiden -q "..."` for scripting, Discord setup inside the terminal, central cross-platform path handling, and green CI across Windows, macOS, and Linux. ## What's new in v4.12 **Aiden can now connect outward to MCP servers and operate the browser with more state.** - **MCP client.** Connect to external MCP servers over stdio and Streamable HTTP, with OAuth 2.0 discovery, dynamic client registration, PKCE, token refresh, reconnects, circuit breakers, and one-command curated installs. - **Approval-gated MCP tools.** External tools are model-callable, but gated by approval. Results are redacted and fenced as untrusted input. - **Browser depth.** Accessibility-tree snapshots, stable element handles, act-by-reference click/type/fill, stale-element re-resolution, visual screenshot-to-vision support, multi-tab/dialog handling, and local browser attach/launch. - **Safety breadth.** Cross-session search, posture-aware skill/tool narrowing, truncate-then-redact tool-output caps, per-session budget enforcement, honest execution-policy messaging, and exfiltration-aware browser guardrails. - **Process manager + activity.** Tracked spawns, reliable tree-kill, redacted process listing, shutdown reaping, plus `/home` and `/activity` commands. ## What's new in v4.11 **A reliability release for honest output, better control, and stronger setup.** - **Honesty & verification.** Per-turn outcome verifier catches failed tool results and contradictions instead of glossing over them. - **Artifact registry.** `/artifacts` tracks files Aiden creates, with provenance: source tool, originating request, and turn link. - **Streaming & control.** Streaming delta coalescer reduces terminal writes, while `/undo`, `/retry`, `/compress`, and `/usage` give direct operator control. - **Task durability.** Orphan-task boot sweep retires crashed-session tasks as interrupted; `/tasks all` shows tasks across sessions. - **Setup polish.** Wizard back-navigation and config detection fixes prevent working OAuth/env setups from being mistaken as empty. - **Model updates.** DeepSeek V4 Pro and V4 Flash added, model picker table improved, and weak-model UI gating reduces markup leaks. ## What's new in v4.10 Aiden becomes inspectable, durable, and finally streams properly. - **Streaming default restored at the wizard layer.** `display.streaming` now defaults to `true` for fresh installs — restoring what v4.1.4 attempted but couldn't operationally land because the wizard wrote the older default into your `config.yaml`. Existing users with explicit `streaming: false` keep their setting AND see a one-time per-session disclosure suggesting the flip. - **Durable Task object.** Every user prompt creates a persistent task row with status / goal / event back-references. `/tasks [active|completed|cancelled|]` lists; `/adjust cancel` or `/adjust goal ` controls. - **`/trace recent` event inspection.** Every tool call, permission decision, and task lifecycle event lands in a queryable `run_events` ledger. Filter by category / kind / name / tool_call_id; scope to the current run, this session, the last N hours, or all. - **Bug D ghost-text cursor fix.** Ghost suggestions now render on a footer line below the prompt; cursor lands right after your typed input. Third attempt that actually works — prior two (v4.9.2, v4.9.6) shipped inert because they tried to fight `@inquirer/core`'s cursor manager from inside the rendered string. - **Permission picker scope clarity.** `Session (this path)` / `Always (this command)` labels carry a dynamic qualifier showing what the scope actually covers. No more "I picked Session, why am I being asked again?" surprises when the same tool fires with a different primary arg. - **Eval harness v1.** 20 contract tests under `tests/v4/eval/` protect the v4.10 substrate from regression — PTY-driven where possible, mockProvider-backed for streaming guarantees. ## What's new in v4.9.0 Aiden v4.9.0 ships three new feature families: - **Memory** — three-namespace persistent memory (memory/user/project) with CLI + auto-review - **Hooks** — secure subprocess hook system (observe/decide/transform) with full audit trail - **Strategic substrate** — UUIDv7 IDs, W3C trace propagation, durable runs, idempotency, crash recovery Plus theme system, MCP integration (Claude Desktop / Cursor / VS Code), and substantial UI polish. See [CHANGELOG.md](./CHANGELOG.md) for details.
## What's new in v4.8 **Aiden's UI got an identity, and pasting actually works now.** ### v4.8.1 — Paste handling + visual polish - **Robust paste handling.** Stateful parser across stdin chunk boundaries, 800ms watchdog for missing paste-end markers, degraded marker form normalisation, universal CRLF/CR → LF, and timing-based accumulation that catches line-by-line paste delivery. Works across Windows ConPTY, SSH without `-t`, tmux/screen passthrough, and VS Code's integrated terminal. Typed prefix is preserved when paste arrives mid-input. - **Markdown tables render as proper grids.** Proportional column-width distribution with header-floor minimums so short labels never wrap mid-word. Model nudged via prompt to prefer sectioned lists for very wide comparisons. - **Version reporting reads runtime `package.json`.** Boot card and `/version` no longer report stale numbers after `/update install`. - **`/update install` cleanups.** Dropped the Node 20+ deprecation warning. Install progress shown via sliding-shimmer indicator. Install-method detection broadened to Windows user-mode globals. - **Loading indicator + spacing.** Indicator aligned at col 2 matching other surfaces; conditional erase preserves clean 1-blank rhythm between turns. - **Status bar timer glyph (`⌛`).** Visible at all terminal widths (mid + compact tiers previously dropped it). - **Single approval panel** per `file_write` (no duplicate event-row + panel stack). ### v4.8.0 — Events backbone + visual identity - **Watch the agent work.** Seven `ui_*` events (`ui_task_update`, `ui_task_done`, `ui_command_result`, `ui_test_result`, `ui_approval_request`, `ui_toast`, `ui_artifact_created`) let the model emit structured progress signals instead of writing them as prose. The REPL paints them as inline rows separate from the reply text. System prompt nudges the model to fire events during multi-step work. - **Aiden-native visual chrome.** Orange `│` panel bars with asymmetric top-divider chrome (no closing corners). Token-sourced design system (`cli/v4/design/tokens.ts`) — palette, glyphs, spacing in one place. - **Packed status bar.** Cyan model name · amber token ratio · semantic-tiered context bar (`●●●●●●○○○○`) · purple turn counter · teal `⌛` per-turn timer · state dot. Progressive disclosure on narrower terminals. - **Sliding-block loading indicator.** 4-cell `█` segment slides L→R on a muted `─` track at 250ms/cell. - **Onboarding refresh.** 24-bit ANSI AIDEN banner, capability-bullet disclaimer, 10-cell progress bar in the loading sequence, rounded heavy-frame "Built solo" card. - **Markdown polish.** Code blocks get a top-divider with brand-orange language label. Bullet lists use `●`/`○`; task lists use `✔️`/`○`. - **ChatGPT Plus + gpt-5 routing fix.** Auxiliary cheap-LLM calls (`risk_assess`, `compression`, `session_summary`, `skill_describe`) route through Groq + `llama-3.1-8b-instant` by default, falling back to the parent provider only when Groq isn't configured. Fixes the v4.6.x bug where every auxiliary call returned 400 from the Codex backend.
## What's new in v4.6 **Aiden now spawns workers and learns from itself.** - **Sub-agents.** `spawn_sub_agent` runs a focused child with an isolated context + intersected toolset; `subagent_fanout` runs N children in parallel (ensemble or partition) with merge strategies (`all` / `vote` / `pick-best` / `combine`) and provider rotation across configured fallback slots. - **Operator kill-switch.** `/spawn-pause on|off|status` blocks new sub-agent spawning while in-flight children continue. Marker file at `~/.aiden/spawn.paused` so the state survives restart and is shared across REPL, daemon, and MCP runtimes. Optional reason field captured in the typed `SUBAGENT_SPAWN_PAUSED` error envelope. - **Self-improvement loop foundation.** TCE classifications + recoveries persist to two new SQLite tables (`failure_signatures`, `recovery_reports`); `/recovery list|show|clear` surfaces recurring failure patterns across sessions. - **REPL parent-run lineage.** Each REPL turn writes its own `runs` row; sub-agent children link back via `spawned_from_run_id`. `aiden runs list` hides children by default and shows a `(N children, M OK)` badge per parent; `--include-children` flips to flat view. - **PlannerGuard opt-in.** The keyword-based per-turn tool narrower is **OFF by default** in v4.6 (modern models pick well from the full catalog). Enable via `/planner-guard on` or `AIDEN_PLANNER_GUARD=1` for smaller local models. - **v4.6.1 onboarding redesign.** Fresh disclaimer screen, loading sequence, rich provider picker with live `/models` fetch, 3-step connection probe, success screen, and `/walkthrough` guided tour. Phase 2 also fixed an MCP-mode `subagent_fanout` regression that had silently broken in the v4.5 refactor.
## 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 `. - **Execution guardrails + risk tiers.** Filesystem allow/deny lists (defense-in-depth for the `file_*` tools — **not** shell containment; a shell command can still reach the filesystem) + dry-run preflight, plus an optional Docker session backend that *is* real (if still weakly hardened) process containment. Default on; flip live with `/sandbox on|off`, inspect the honest policy with `/sandbox status`. - **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). Full v4.5 internals: [`docs/v4.5/`](docs/v4.5/) (overview, triggers, architecture, daemon on Linux/macOS/Windows, troubleshooting).

## 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), Nous Portal, custom OpenAI-compatible endpoints. OAuth subscription routing for ChatGPT Plus. | | **121 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`. | | **76 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, state-aware browser automation, accessibility-tree snapshots, stable element handles, act-by-reference click/type/fill, and partial mouse/keyboard automation. | | **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.** | | **v4.15 interaction reliability** | Single-owner activity/timer lifecycle, exact FIFO queued input, truthful approval and interruption states, responsive startup chrome, stronger claim verification, and clearer recovery guidance. | | **Plugins** | Two bundled plugins: Chrome DevTools Protocol bridge, ChatGPT Plus OAuth. Permission-state machine (pending-grant / loaded / suspended). | | **MCP** | Model Context Protocol bridge and client — stdio + Streamable HTTP transports, schema discovery, OAuth 2.0 flow, approval-gated external tools, and tool dispatch. | | **Security moat** | Tiered approval engine (`safe` / `caution` / `dangerous`), dangerous-command pattern classifier, outcome verification, artifact provenance, trust dial, memory guard, planner-guard tool narrowing, SSRF-safe URL fetcher, secret/PII pre-write scanner, exfiltration-aware browser guardrails, and skill-teacher. |
## Architecture Aiden is a cross-platform autonomous runtime: 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. v4.12 added outward MCP client support and deeper browser state; v4.13 added job-cards, restart-safe task continuation, evidence-required subagents, and a trust dial. v4.15 tightened the operator surface with a single-owner terminal lifecycle, exact FIFO queued input, truthful approval and interruption states, responsive startup layouts, and stronger claim/evidence verification. 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).
https://github.com/user-attachments/assets/323c9aa7-959a-425a-a5b3-4bae2b1a14bc ## Install, update, and 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: ```text /update install ``` (Aiden also prompts you on boot when a newer version is on npm — see `/update auto off` to silence.) ### Uninstall ```bash npm uninstall -g aiden-runtime ``` To also wipe your local Aiden home (config, sessions, memory, skills): ```bash # Linux / macOS rm -rf ~/.aiden # Windows (PowerShell) Remove-Item -Recurse -Force $env:LOCALAPPDATA\aiden ```
Aiden setup and operator interface https://github.com/user-attachments/assets/398e1d48-cc5a-4fb5-a195-05dbef824198 ## Recommended terminal setup For best visual rendering, Aiden looks crispest with: - **Font:** Cascadia Code, JetBrains Mono, or Fira Code at 13–14pt - **Terminal:** Windows Terminal, iTerm2, or a modern emulator with truecolor support - **Color depth:** truecolor (24-bit) — most modern terminals support this Aiden works on any terminal but glyphs and color depth may degrade gracefully on older / minimal setups. ## Setup wizard The first time you run `aiden`, you'll see: 1. **Disclaimer screen** — honest about what Aiden can touch (files, browser, shell) 2. **Loading sequence** — system check, skills load, tools register, memory init 3. **Provider picker** — pick from 19 providers, no defaults — explicit choice 4. **Live model fetch** — Aiden hits the provider's `/models` API for the current catalog 5. **3-step probe** — key works → model accessible → tool calls supported 6. **Success screen** — three example prompts to get started 7. **REPL handoff** — first-run hint banner: `Tip: try /walkthrough` To re-run the wizard later: ```bash aiden setup ``` To diagnose without re-running: ```bash aiden doctor ```
## Switching models Inside the REPL: ```text /model ``` Picks a provider (with `✓ authed` badges next to ones you've configured), fetches the live model list, and saves your choice to `config.yaml`. Persists across sessions. To set the default at the env level: ```bash export AIDEN_DEFAULT_PROVIDER=groq export AIDEN_DEFAULT_MODEL=llama-3.3-70b-versatile ``` ### Recommended models | Use case | Best models | |---|---| | **Best overall / quality** | GPT-5.5 via ChatGPT OAuth, GPT-5, Claude Sonnet 4.6 / Opus, Gemini 2.5 Pro | | **ChatGPT OAuth / no API key** | GPT-5.5, GPT-5.4, GPT-5.3 Instant, GPT-5, and other available ChatGPT models through `chatgpt-plus` | | **Speed + free tier** | Groq Llama 3.3 70B, Cerebras Llama 3.3 70B | | **Fully local** | Ollama with Qwen 2.5 32B, Llama 3.3 70B, or DeepSeek R1 | | **Open weights via subscription** | Nous Portal (Hermes-3-405B) | | **Long context** | Gemini 2.5 Pro (2M tokens) | > 💡 **Quality scales with model capability.** Aiden's output quality depends heavily on the model you pick. For real work, prefer the highest-capability model your budget allows — GPT-5.5 via ChatGPT OAuth, GPT-5, Claude Sonnet 4.6, Opus, or Gemini 2.5 Pro. Smaller models work for simple tasks, but agentic loops benefit from stronger reasoning. > 💡 **ChatGPT Plus subscribers**: use the OAuth flow instead of an API key. Pick `chatgpt-plus` as your provider during `/model` setup, then sign in via browser. Aiden can route to GPT-5.5, GPT-5.4, GPT-5.3 Instant, GPT-5, and other GPT models available on your plan. No separate API costs — uses your existing subscription's model allowances. **Anthropic users**: set `ANTHROPIC_API_KEY` and pick `anthropic`.
## Skills Aiden ships with 76 bundled skills and supports installing more from the community registry. ### What are skills? Skills are composable workflows. Each skill has a `SKILL.md` prompt, optional helper scripts, and declared tool requirements. Examples: GitHub PR/issue automation, NSE/Upstox/Zerodha trading flows, Censys/Shodan lookups, Windows Defender management. ### Managing skills | Action | Command | |---|---| | List installed skills | `/skills` | | Browse the community registry | Visit [skills.taracod.com](https://skills.taracod.com) | | Install a skill from registry | `/skills install ` | | Remove a skill | `/skills remove ` | | Reload skills (after edits) | `/skills reload` | ### Contributing skills Skills live in [`skills/`](skills/) under Apache-2.0. PRs welcome. Each skill needs: - A `SKILL.md` describing what it does and when to use it - Optional `tools.json` declaring required tools - Optional helper scripts in `lib/`
## 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 (`/`) | | `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 | | `AIDEN_PLANNER_GUARD` | `0` | Set to `1` to enable keyword-based tool narrowing (helps smaller local models) | Most flags are also flippable live via slash commands.
## CLI commands | Command | What it does | |---|---| | `aiden` | Start the REPL (runs setup wizard on first launch) | | `aiden -q "..."` | Run a one-shot prompt for scripting / automation | | `aiden setup` | Re-run the onboarding wizard | | `aiden doctor` | Diagnose providers, auth, config, and environment | | `aiden --version` | Print the installed version | | `aiden --help` | Show the full CLI manual | | `aiden update` | Check for and install updates | | `aiden daemon start` | Run the daemon in foreground | | `aiden daemon install` | Install daemon as system service (systemd / launchd / Task Scheduler) | | `aiden daemon status` | Show daemon health, recent triggers, run history | | `aiden trigger add file --path

` | Add a file-watcher trigger | | `aiden trigger add webhook --label ` | Add an HTTP webhook trigger | | `aiden trigger add cron --schedule ""` | Add a scheduled trigger | | `aiden trigger list` | List all configured triggers | | `aiden runs list` | List recent agent runs (interactive + daemon) | | `aiden runs show ` | Inspect a specific run's tool chain | | `aiden runs stats` | Aggregate stats across runs |
## In-chat slash commands Type `/help` inside Aiden for the full list grouped by category. ### Configuration `/model` · `/personality` · `/skin` · `/streaming` · `/reasoning` · `/verbose` · `/debug-prompt` · `/identity` ### Session `/clear` · `/compress` · `/save` · `/title` · `/usage` · `/undo` · `/retry` ### System `/sandbox` · `/tce` · `/browser-depth` · `/daemon` · `/suggestions` · `/update` · `/skills` · `/tools` · `/plugins` · `/cron` · `/runs` · `/trigger` · `/tasks` · `/adjust` · `/trace` · `/artifacts` · `/home` · `/activity` · `/doctor` · `/status` · `/show` · `/history` ### Sub-agents (v4.6) `/spawn-pause on|off|status` · `/recovery list|show|clear` · `/planner-guard on|off|status` ### Walkthrough & onboarding (v4.6.1) `/walkthrough` — 60-second guided tour of what Aiden can do ### Auth `/auth login` · `/auth status` · `/auth refresh` ### MCP `/reload-mcp` · `/setup`
## Daemon mode (opt-in) ### Linux ```bash export AIDEN_DAEMON=1 aiden daemon install loginctl enable-linger $USER # keep running between sessions ``` ### macOS ```bash export AIDEN_DAEMON=1 aiden daemon install # installs launchd plist ``` ### Windows See [`docs/v4.5/daemon-windows.md`](docs/v4.5/daemon-windows.md). Recommended: foreground (`aiden daemon start`) or `pm2` for background.
## 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 - **`npm install` permission errors on Windows** — install into a real folder (not a drive root like `S:\`) https://github.com/user-attachments/assets/3acc997f-1d71-45d1-9955-11b67abd0c50 https://github.com/user-attachments/assets/9e734168-cf76-4cc0-975a-379e5402ee90 https://github.com/user-attachments/assets/5e7011a5-630d-43bd-8ed3-67084c7645db
## The book 📖 **Omega** — A novel about code, solitude, and what builds back. The story behind Aiden and what it means to build alone. [![Get Omega on Amazon](https://img.shields.io/badge/Get_Omega-Amazon-FF9900?style=for-the-badge&logo=amazon&logoColor=white)](https://amzn.to/49ceO8l)
## Sponsor Aiden is free and open source. If it saves you time or you want it to keep getting better, sponsorship helps cover server costs, API testing, and the time to ship features instead of taking client work. [![Sponsor via Razorpay](https://img.shields.io/badge/Sponsor-Razorpay-3395FF?style=for-the-badge&logo=razorpay&logoColor=white)](https://razorpay.me/@whitelotus9625) Even a one-time tip or a star on the repo is appreciated.
## Acknowledgements Built solo by **Shiva Deore** at **Taracod**. 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.
## Contributing Aiden is built solo right now, but contributions are welcome — bug reports, skill submissions, provider adapters, documentation fixes. Before opening a PR: 1. Fork the repo 2. `npm install` 3. Make your changes on a feature branch 4. `npm run build` — confirm it compiles 5. Test with `aiden` locally 6. Open a PR with a clear description of what changed and why Keep PRs focused. One feature or fix per PR. Be honest in the description about what works and what doesn't.
## License - **Core runtime**: [AGPL-3.0](LICENSE). You can self-host, modify, and distribute Aiden as long as your modifications stay under AGPL. - **Bundled skills**: Apache-2.0. Use them however you want. - **Commercial licensing** for closed-source derivatives: contact [hello@taracod.com](mailto:hello@taracod.com). The future `skills.taracod.com` marketplace will ship community skills under the same permissive terms.
## Links | Where | What | |---|---| | 🌐 **Website** | [aiden.taracod.com](https://aiden.taracod.com) | | 💬 **Discord** | [discord.gg/CU5wshJW4F](https://discord.gg/CU5wshJW4F) | | 📦 **npm** | [aiden-runtime](https://www.npmjs.com/package/aiden-runtime) | | 🐙 **Source** | [github.com/taracodlabs/aiden](https://github.com/taracodlabs/aiden) | | 📁 **Standalone releases** | [github.com/taracodlabs/aiden-releases](https://github.com/taracodlabs/aiden-releases) | | 🧾 **Release notes** | [v4.15.1](https://github.com/taracodlabs/aiden/releases/tag/v4.15.1) · [v4.15.0](https://github.com/taracodlabs/aiden/releases/tag/v4.15.0) · [v4.13.0](https://github.com/taracodlabs/aiden/releases/tag/v4.13.0) · [v4.12.0](https://github.com/taracodlabs/aiden/releases/tag/v4.12.0) · [v4.11.0](https://github.com/taracodlabs/aiden/releases/tag/v4.11.0) | | 📖 **Book — Omega** | [Amazon](https://amzn.to/49ceO8l) | | 📚 **Docs** | [`docs/v4.5/`](docs/v4.5/) (in this repo) | | 💖 **Sponsor (Razorpay)** | [razorpay.me/@whitelotus9625](https://razorpay.me/@whitelotus9625) | | ✉️ **Contact** | [contact@taracod.com](mailto:contact@taracod.com) |
## Disclaimer Aiden can read and write files, run shell commands, access the web, operate supported applications, and connect to external services. It is autonomous within the limits you set. Review permissions carefully, keep backups, use limited credentials, and test important workflows in a safe environment. Aiden is actively developed, and some capabilities remain experimental or platform-dependent. Report reproducible problems so they can be fixed. **Built solo by Shiva Deore at Taracod. Started as a hobby project. Improving with every release.** ### Welcome - **Contributors** — bug reports, skill submissions, provider adapters, and documentation PRs are all welcome. See [Contributing](#contributing) above for the workflow. - **Sponsors / investors** — Aiden is built by one person funding it from client work. If you'd like to help Aiden grow faster, reach out at [contact@taracod.com](mailto:contact@taracod.com) or sponsor via [Razorpay](https://razorpay.me/@whitelotus9625). - **Beta testers** — try it on your workflow, file issues, share what works and what doesn't. Honest feedback shapes the roadmap. ---

**By Taracod · White Lotus**
---

Give Aiden a job. Watch it work. See what actually happened.