AIDEN BOOTUP LOGO ```text █████╗ ██╗██████╗ ███████╗███╗ ██╗ ██╔══██╗██║██╔══██╗██╔════╝████╗ ██║ ███████║██║██║ ██║█████╗ ██╔██╗ ██║ ██╔══██║██║██║ ██║██╔══╝ ██║╚██╗██║ ██║ ██║██║██████╔╝███████╗██║ ╚████║ ╚═╝ ╚═╝╚═╝╚═════╝ ╚══════╝╚═╝ ╚═══╝ Autonomous Work Engine — plans, acts, recovers, and proves the result Bundled Skills · durable tools · multiple providers · connected 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, repositories, and connected services to get the job done. *Bundled Skills · durable tools · multiple providers · connected 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-20_or_22-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) ![Multiple providers](https://img.shields.io/badge/Multiple-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) ![More channels](https://img.shields.io/badge/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) ![Taracod](https://img.shields.io/badge/Brand-Taracod-FFB088?style=flat-square) ![Stable](https://img.shields.io/badge/Stable-v4.21.2-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, repositories, and connected services, remember what matters, recover from failures, and verify whether the requested result was actually produced. Built solo. Open source. Actively developed.
## Aiden Web preview One workspace for work, connections, memory, automations, and artifacts. ![Aiden Web Home in an isolated demo profile](docs/media/workbench-2026-09/02-home.png) **[Browse all 34 screenshots](docs/workbench-ui-gallery.md)** · **[Interactive screenshot tour](docs/media/workbench-2026-09/tour.html)** The tour opens locally in a browser after downloading or cloning this repository; GitHub shows its HTML source. It includes manual navigation and an optional guided slideshow.
Preview Apps and the visual workflow builder ![GitHub and Gmail setup in Aiden Apps](docs/media/workbench-2026-09/05-apps.png) ![An unsaved starting template in the Aiden visual workflow builder](docs/media/workbench-2026-09/31-workflow-builder.png)
See the rest of the Workbench
Aiden onboarding and model connection choices
Onboarding		 Aiden Work view for jobs and attempts
Work and Jobs		 Aiden model and provider setup with GPT-6 Astra
Models and providers
Aiden Brain memory graph
Brain and memory		 Aiden Automations view
Automations		 Aiden MCP and external agents settings
MCP and external agents
These captures cover the main product surfaces without implying that a provider, account, MCP server, or workflow is already connected. For every page and its intentional setup/empty states, use the [full screenshot gallery](docs/workbench-ui-gallery.md).
*Development preview captured on 13 September 2026. These are actual UI captures from a separate, unconfigured profile—not simulated task results or proof of a published release. Account connections, paid checkout, and task execution are not demonstrated. See the gallery for coverage and limitations.* ## 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 → Job → Plan & Claims → Attempt → Effect → Approval → Execution → Evidence → Verification → Verdict → Proof ``` Aiden does not treat a successful command or a model saying “done” as proof. Jobs, Attempts, Effects, approvals, Evidence, Verification, Verdicts, and Proof are tracked separately so interrupted, stale, conflicting, or externally uncertain work can be recovered and reconciled honestly. - **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, repositories, and channels. - **Stay in control.** Risk-tiered approvals, trust levels, budgets, interruption, scoped permissions, leases, and generation fencing keep consequential actions visible. - **See what happened.** Jobs, Attempts, Effects, Evidence, tests, artifacts, diagnostics, Verification, Verdicts, and Proof make the work inspectable. - **Use the models you prefer.** Choose among multiple 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 Mode** | Snapshot a repository, understand its structure, preserve existing user work, make conflict-safe changes, run structured tests and builds, perform Git operations, and verify the final state with durable Evidence. | | **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, identify the three highest-risk areas, and support the findings with repository Evidence. ``` ```text Find the cause of the failing tests, fix the root problem, rerun the relevant tests, and show me exactly what changed. ``` ```text Research this topic, compare the strongest findings, and save a structured Markdown report. ```
## Try it in 60 seconds > [!IMPORTANT] > **Release channels** > > - **Stable:** `v4.21.2` through npm `latest` > - **Release notes:** [v4.21.2](RELEASE-NOTES-v4.21.2.md) > - **Archived RC:** [`v4.19.0-rc.1`](https://github.com/taracodlabs/aiden/releases/tag/v4.19.0-rc.1) ### Stable — v4.21.2 ```bash npm install -g aiden-runtime aiden ``` Open the browser Workbench instead: ```bash aiden web ``` That’s it. The first launch opens Aiden’s current setup flow, checks the selected connection, and then hands control to the Operator TUI. Stable channel: ```text npm latest → 4.21.2 ``` Without permanent installation: ```bash npx aiden-runtime@latest ``` The [v4.19.0-rc.1 release candidate](https://github.com/taracodlabs/aiden/releases/tag/v4.19.0-rc.1) is archived. ### Verify the installed version ```bash aiden --version ``` Expected output: ```text 4.21.2 ``` Both public commands, `aiden` and `aiden-runtime`, start the same standalone local runtime. The separate desktop/API client is an internal build artifact for connecting to an already-running service and is not included as an npm command. Verify the stable release without a permanent installation: ```bash npx aiden-runtime@latest --version ``` **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.21.2 **Aiden v4.21.2 improves setup, connection management and terminal reliability while preserving Workbench continuity and dependable execution.** Discover existing capabilities from Connections in Workbench or `/discover` in the CLI. Choose a local, API-key or supported subscription model. Apps and remote MCP require provider setup and your consent; account linking remains optional. The package includes updated HTTP/IMAP dependencies and safer rapid input in the optional terminal renderer. See the release notes for limitations and deferred platform acceptance. - **Workbench control.** A one-click Auto mode follows the saved autonomy policy and keeps required approvals enforced. - **Connections surface.** Apps, messaging channels, MCP servers, coding tools, and provider setup are discoverable from dedicated Workbench pages and their CLI commands, with explicit status and reconnect paths. - **Model choice.** ChatGPT OAuth exposes GPT-6 Astra, GPT-5.6 Sol/Terra/Luna, GPT-5.5, and supported Codex models when the connected plan entitles them; Aiden keeps provider and model identity visible. - **Reasoning effort.** Supported models expose the levels they accept: `low`, `medium`, `high`, and, for the strongest OAuth models, `xhigh` or `max`. Unsupported levels stay hidden rather than being silently substituted. - **Completed work.** Jobs, Artifacts, Evidence and Verification remain discoverable after restart and reopen. - **Reliable Automations.** Required child outcomes stay linked to their parent, with truthful success and failure visibility. - **Visual workflows.** The Workbench can design bounded, typed, workspace-safe workflows that compile to the existing Automation contract. - **Core hardening.** Browser/session identity, approval snapshots, model binding, cancellation, Retry and late-result fencing remain durable and exact-once. - **Runtime boundary.** The source CLI and bundled runtime share the supported CommonJS module boundary and continue to support Node 20 and Node 22. ### Known limitations - Real third-party account connections require provider setup and authorization in Apps. - Aggressive terminal resizing may produce cosmetic activity-row projection artifacts. No duplicate execution, duplicate mutating effect, durable-state corruption, approval corruption, lost input or crash was found; this remains a P2 cosmetic issue. - Windows installer/uninstall acceptance is deferred. The public release is the runtime package; no desktop installer is attached. ## What's new in v4.19.0 **Aiden v4.19.0 is the stable Worker and Model Bridge release.** - **Durable Worker contracts.** Read-only repository Workers use explicit parent and child execution authority. - **Immutable model binding.** Each Worker keeps its provider and model binding fixed for the admitted execution. - **Accounting and budgets.** Logical provider calls, physical attempts, tokens, usage, reservations, and pre-send budget enforcement remain distinct and durable. - **Resilient provider work.** Bounded retries, provider fallback, cancellation during provider work, and rejection of late provider results protect current execution truth. - **Restart and evidence.** Workers can restart and reopen; child Evidence is verified by the parent before completion is accepted. - **Bounded parallelism.** Parallel Worker admission and reservations use stable joins and deterministic reconciliation. ### Known issue Aggressive terminal resizing may produce cosmetic activity-row projection artifacts. Investigation found no duplicate tool execution, duplicate mutating effect, durable-state corruption, approval corruption, lost input, or crash. This is tracked as a P2 cosmetic issue. ### Feedback Please report feedback through [GitHub Issues](https://github.com/taracodlabs/aiden/issues) or the [Aiden Discord community](https://discord.gg/CU5wshJW4F). Include: - operating system; - Node version; - installation command used; - Aiden version from `aiden --version`; - provider and model, when relevant; - exact reproduction steps; - relevant logs or Evidence; - whether restart/reopen recovered the Job. Do not include API keys, tokens, secrets, or private repository content. This GitHub README update does not change the README captured on the already- published npm package page. Updating that page would require publishing a new version. ## What's new in v4.18.0 **Aiden v4.18.0 introduces durable Codebase Mode and a substantially rebuilt Operator TUI.** ### Codebase Mode - **Repository snapshots.** Aiden records repository root, VCS state, branch, HEAD, dirty files, untracked files, manifests, lockfiles, hashes, build commands, test commands, CI configuration, and snapshot identity before making changes. - **Safe file changes.** Mutations are bound to an Attempt, source snapshot, expected base revision, and Effect. Stale bases, unsafe paths, symlink escapes, and conflicting user edits are blocked rather than silently overwritten. - **Fresh readback and conflict Evidence.** Aiden reads changed files back from disk, records hashes and diffs, and preserves durable conflict Evidence when a requested change cannot be applied safely. - **Structured validation.** Test, build, and diagnostic runs are bound to repository snapshots and record commands, parsed outcomes, artifacts, failures, and verification state. - **Git Effects.** Branch, stage, commit, fetch, pull, push, tag, and related Git operations are represented as reconcilable Effects instead of invisible terminal mutations. - **Repository understanding.** Aiden can inventory languages, manifests, source/test relationships, imports, symbols, commands, CI configuration, and architectural signals before planning work. - **Durable execution projection.** Runtime plans, code claims, repository operations, Evidence, and Verification are projected into the existing execution graph and Proof system. ### Operator TUI - **Semantic activity.** Aiden shows meaningful phases such as thinking, planning, inspecting, working, testing, verifying, recovering, and finalizing instead of exposing provider plumbing. - **Summary and full activity modes.** Normal operation stays compact, while `/activity full` exposes deeper execution detail when needed. - **Compact durable Evidence.** File changes, test outcomes, diagnostics, readbacks, and Verification are presented separately from the final answer. - **Responsive borderless composer.** The input area is wide, multiline, cursor-safe, and free from reflow-prone box borders. - **Stable Windows resizing.** Resize transactions preserve terminal ownership without duplicating prompts, activity rows, startup cards, composers, footers, or stale animation frames. - **Native terminal scrollback.** Completed prompts and answers remain reviewable through normal PowerShell and Windows Terminal scrolling. - **Preserved operator state.** Drafts, Unicode input, queued messages, semantic activity, approvals, cursor position, and the status footer survive resizing and restoration. - **Provider and model identity.** Narrow layouts preserve the complete provider/model identity before compressing secondary status information. See the full [v4.18.0 release notes](https://github.com/taracodlabs/aiden/releases/tag/v4.18.0).
Earlier v4 release highlights — v4.17 through v4.5
## What's new in v4.17.0 **Aiden v4.17.0 unified durable runtime authority with a responsive operator terminal.** - **One durable lifecycle.** Interactive, one-shot, API, Workbench, daemon, channel, child, and MCP execution share authoritative Job and Attempt transitions. - **Stale-result protection.** Generations, leases, fence tokens, terminal-state guards, and persist-first cancellation prevent old work from rewriting current truth. - **Evidence-based completion.** Proof, Verdict, exact file readback, Effect reconciliation, and failure-injection coverage strengthen completion claims and recovery. - **Operator TUI foundation.** The Aiden startup identity, responsive metadata, composer, status strip, themes, compact outcomes, and durable queue controls share one terminal owner. - **Platform reliability.** Windows process cleanup, ConPTY coverage, and cross-platform CI preserve clean startup, activity rendering, and shutdown. See the full [v4.17.0 release notes](https://github.com/taracodlabs/aiden/releases/tag/v4.17.0). ## 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 attempts 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. - **Eval harness v1.** 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 with CLI and auto-review - **Hooks** — secure subprocess hook system with observe, decide, and transform modes plus a full audit trail - **Strategic substrate** — UUIDv7 IDs, W3C trace propagation, durable runs, idempotency, and crash recovery Plus the theme system, MCP integration for supported clients, 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, watchdog handling for missing paste-end markers, degraded marker normalization, universal newline normalization, and timing-based accumulation that catches line-by-line paste delivery. - **Markdown tables render as proper grids.** Proportional column-width distribution with header-floor minimums. - **Version reporting reads runtime `package.json`.** Boot card and `/version` no longer report stale numbers after `/update install`. - **`/update install` cleanups.** Install progress shown via a sliding-shimmer indicator. Install-method detection broadened to Windows user-mode globals. - **Loading indicator + spacing.** Indicator aligned with the rest of the terminal surface. - **Status bar timer glyph.** Visible at all supported terminal widths. - **Single approval panel** per `file_write`. ### v4.8.0 — Events backbone + visual identity - **Watch the agent work.** Structured `ui_*` events let the model emit progress signals instead of writing them as prose. - **Aiden-native visual chrome.** Token-sourced design system with centralized palette, glyphs, and spacing. - **Packed status bar.** Model name, token ratio, context meter, turn counter, elapsed timer, and state. - **Sliding-block loading indicator.** - **Onboarding refresh.** ANSI AIDEN banner, capability disclaimer, loading sequence, and Built solo card. - **Markdown polish.** Code blocks, lists, and task lists render with Aiden-native formatting. - **Provider routing fixes.** Auxiliary calls use configured supporting providers where available instead of consuming the main model unnecessarily.
## 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 and intersected toolset; `subagent_fanout` runs multiple children with merge strategies 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. - **Self-improvement loop foundation.** TCE classifications and recoveries persist to durable SQLite records; `/recovery list|show|clear` surfaces recurring failure patterns. - **REPL parent-run lineage.** Each REPL turn writes a run row; sub-agent children link back through parent lineage. - **PlannerGuard opt-in.** Keyword-based per-turn tool narrowing remains optional for smaller local models. - **Onboarding redesign.** Provider picker, connection probe, success screen, and `/walkthrough` guided tour.
## 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. - **Autonomous trigger dispatch.** File watchers, webhooks, email polling, and schedules can launch real agent turns. - **Execution guardrails + risk tiers.** Filesystem boundaries, dry-run preflight, and optional Docker-backed execution. - **State-aware browser depth.** URL, DOM, iframe, and interaction-state capture before and after browser actions. - **Continuous error recovery.** Failure classification, bounded retries, cooldowns, dead-letter handling, and recovery reports. - **Live-flip slash commands.** Toggle sandbox, TCE, browser depth, daemon behavior, suggestions, and updates without restarting. - **Update notification + `/update` CLI.** Full v4.5 internals: [`docs/v4.5/`](docs/v4.5/).

## Core capabilities | Category | What Aiden does | |---|---| | **Inference & providers** | Anthropic, OpenAI, Groq, Gemini, OpenRouter, Together, NVIDIA NIM, DeepSeek, Mistral, Z.ai, Kimi, MiniMax, Hugging Face, Ollama, Nous Portal, custom OpenAI-compatible endpoints, and additional configured routes. ChatGPT Plus OAuth includes GPT-6 Astra, GPT-5.6 variants, GPT-5.5, and supported Codex models where entitled. | | **Built-in tools** | Web search and fetch, deep research, YouTube search, browser automation, file operations, process control, shell execution, code execution, system information, screenshots, clipboard, app launch, media controls, MCP bridge, memory operations, session search and recall, skill management, and self-update workflows. | | **Bundled skills** | Composable workflows with a `SKILL.md`, optional helper scripts, and tool requirements. Includes GitHub workflows, trading tools, security lookups, Windows administration, Docker management, research, and content workflows. | | **v4.18 Codebase Mode** | Durable repository snapshots, conflict-safe file changes, fresh readback, structured TestRun / BuildRun / Diagnostic records, Git Effects, repository understanding, code claims, Evidence, Verification, and execution-graph projection. | | **v4.18 Operator TUI** | Semantic activity phases, summary/full activity modes, compact Evidence, responsive borderless multiline input, native terminal scrollback, provider/model identity preservation, and stable draft, queue, activity, approval, and cursor restoration during resize. | | **Self-promoting memory** | `USER.md` + `SOUL.md` identity, plus durable and recent-session memory. Sessions end with structured summaries, while semantic recall can retrieve relevant earlier work. | | **Voice** | Edge TTS / Windows SAPI text-to-speech and speech-to-text helpers. | | **Channel adapters** | Discord, Slack, Telegram, WhatsApp, Email, Webhook, Twilio SMS, iMessage on macOS, and Signal. Channels use 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 interaction, and partial mouse/keyboard automation. | | **v4.5 daemon mode (opt-in)** | File watcher, webhook, email, and scheduled triggers route through a durable trigger bus consumed by the dispatcher. **Off by default.** | | **v4.15 interaction reliability** | Single-owner activity and timer lifecycle, exact FIFO queued input, truthful approval and interruption states, responsive startup chrome, stronger claim verification, and clearer recovery guidance. | | **Plugins** | Bundled integrations include a Chrome DevTools Protocol bridge and ChatGPT Plus OAuth. Plugins use explicit permission states such as pending grant, loaded, and suspended. | | **MCP** | Model Context Protocol bridge and client with stdio and Streamable HTTP transports, schema discovery, OAuth, approval-gated external tools, and tool dispatch. | | **Security moat** | Tiered approvals, dangerous-command classification, outcome Verification, artifact provenance, trust controls, memory guardrails, tool narrowing, SSRF-safe fetching, secret/PII scanning, browser exfiltration defenses, and skill governance. |
## Architecture Aiden is a durable autonomous work engine rather than a collection of disconnected agent loops. ```text Goal → Job → Plan & Claims → Attempt → Effect → Approval → Execution → Evidence → Verification → Verdict → Proof ``` A **Job** represents the requested outcome. Each execution happens through a fenced **Attempt** with its own generation, lease, cancellation state, budget, and terminal-state protection. Consequential operations are registered as **Effects**, bound to exact approvals, executed through the existing authorities, and reconciled when an external outcome is uncertain. A command exiting with code `0` is not automatically treated as success. Aiden attaches **Evidence**, performs explicit **Verification**, records a **Verdict**, and produces **Proof** only when the requested Claims are supported. Codebase Mode extends this same kernel rather than creating a separate coding-agent runtime. Repository snapshots, safe changes, TestRun and BuildRun records, diagnostics, Git operations, code Claims, conflicts, artifacts, and fresh readbacks remain linked to the owning Job, Attempt, Effect, and Evidence records. The Operator TUI is a projection over this durable state. It does not become the authority for execution. Semantic activity, approvals, queued input, drafts, Evidence, Verification, and final answers are rendered from the same lifecycle and remain recoverable across interruption and restart. The daemon, channels, MCP surfaces, browser workflows, and interactive terminal reuse the same runtime authorities. Generations, fence tokens, leases, exact approvals, process supervision, restart recovery, Effect reconciliation, and stale-result rejection prevent older work from rewriting current truth. Detailed historical diagrams and module maps remain available 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 ```bash npm install -g aiden-runtime aiden ``` Or launch the Workbench: ```bash aiden web ``` ### Windows ```powershell npm install -g aiden-runtime aiden ``` If you hit native-build errors on Windows, confirm that your Node version is supported and that the required native build prerequisites are installed. ### Try without installing ```bash npx aiden-runtime@latest ``` ### After pulling updates ```bash npm install -g aiden-runtime@latest ``` The permanent bootstrap checks for stable updates before the full runtime loads. When an update is available, choose Update, Later, or Skip. You can also use: ```bash aiden update --check aiden update aiden update --yes aiden update --version 4.21.2 ``` The default channel is npm `latest`. Set `AIDEN_UPDATE_CHANNEL=beta` to follow npm `beta`, or `AIDEN_UPDATE_CHANNEL=off` to disable bootstrap checks. The existing in-session command remains available: ```text /update install ``` Aiden supports Node 20 and Node 22. If an older 4.19.0 installation cannot start, repair it once under the Node version you intend to use: ```bash npm uninstall -g aiden-runtime npm install -g aiden-runtime@latest ``` Reinstalling the global package does not remove Aiden's workspaces, settings, history, Jobs, Evidence, or provider configuration from the Aiden data home. ### Uninstall ```bash npm uninstall -g aiden-runtime ``` To also remove your local Aiden home, including config, sessions, memory, and installed 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 another modern terminal with truecolor support - **Color depth:** truecolor / 24-bit Aiden works on other terminals, but glyphs and color depth may degrade gracefully on older or minimal setups. ## Setup wizard The first time you run `aiden`, you'll see: 1. **Disclaimer screen** — honest about what Aiden can touch, including files, browser, and shell 2. **Loading sequence** — system checks, skills, tools, memory, and runtime initialization 3. **Provider picker** — choose from supported providers with no hidden default 4. **Live model fetch** — retrieve the available model catalog from the selected provider where supported 5. **Connection probe** — validate authentication, model access, and tool-use support 6. **Success screen** — example prompts to help you get started 7. **Operator TUI handoff** — enter the interactive terminal with the current composer and status surface To re-run the wizard later: ```bash aiden setup ``` To diagnose your environment without re-running setup: ```bash aiden doctor ```
## Switching models Inside the REPL: ```text /model ``` This opens the provider and model picker, shows configured authentication where available, fetches the live model list, and saves your choice to `config.yaml`. To set a default through environment variables: ```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 through ChatGPT OAuth, GPT-5, Claude Sonnet 4.6 / Opus, Gemini 2.5 Pro | | **ChatGPT OAuth / no separate API key** | GPT-5.5, GPT-5.4, GPT-5.3 Instant, GPT-5, and other models exposed through the connected ChatGPT plan | | **Speed + free tier** | Groq Llama 3.3 70B, Cerebras Llama 3.3 70B | | **Fully local** | Ollama with capable coding or reasoning models supported by your hardware | | **Open weights via subscription** | Nous Portal and other supported provider routes | | **Long context** | High-context Gemini and other supported long-context models | > **Quality scales with model capability.** Aiden’s output quality depends heavily on the model you choose. Real codebase work, multi-step recovery, and verification generally benefit from the strongest model your budget allows. > **ChatGPT subscribers:** use the OAuth flow rather than a separate API key where supported. Choose `chatgpt-plus` as the provider during `/model` setup, then sign in through the browser. Usage follows the available models and allowances on your connected plan.
## Skills Aiden ships with 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 include GitHub PR and issue workflows, trading integrations, security research, Windows administration, Docker management, browser research, document workflows, and content tools. ### Managing skills | Action | Command | |---|---| | List installed skills | `/skills` | | Browse the community registry | Visit [skills.taracod.com](https://skills.taracod.com) | | Install a skill from the 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 are welcome. Each skill needs: - A `SKILL.md` describing what it does and when to use it - Optional tool declarations - Optional helper scripts in `lib/`
## Configuration Aiden reads `~/.aiden/config.yaml` on Linux/macOS or `%LOCALAPPDATA%\aiden\config.yaml` on Windows. The setup wizard writes a starter configuration on first boot; later changes are merged without replacing unrelated settings. ### Common environment variables | 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 | | `AIDEN_DAEMON_MODEL` | unset | Override the model for daemon turns using `/` | | `AIDEN_SANDBOX` | `1` | Set to `0` to disable supported sandbox controls | | `AIDEN_TCE` | `1` | Set to `0` to disable continuous error recovery | | `AIDEN_BROWSER_DEPTH` | `1` | Set to `0` to disable state-aware browser observation | | `AIDEN_API_KEY` | unset | Required for non-loopback daemon binding | | `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 | Most flags can also be changed live through slash commands.
## CLI commands | Command | What it does | |---|---| | `aiden` | Start the Operator TUI and run setup on first launch | | `aiden -q "..."` | Run a one-shot prompt for scripting or automation | | `aiden setup` | Re-run onboarding | | `aiden doctor` | Diagnose providers, authentication, configuration, and environment | | `aiden --version` | Print the installed runtime version | | `aiden --help` | Show the CLI manual | | `aiden update` | Check for and install updates | | `aiden daemon start` | Run the daemon in the foreground | | `aiden daemon install` | Install the daemon as a supported system service | | `aiden daemon status` | Show daemon health, triggers, and recent 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 configured triggers | | `aiden runs list` | List recent interactive and daemon runs | | `aiden runs show ` | Inspect a specific run and its tool chain | | `aiden runs stats` | Show aggregate run statistics |
## In-chat slash commands Type `/help` inside Aiden for the complete command list grouped by category. ### Configuration `/model` · `/personality` · `/skin` · `/streaming` · `/reasoning` · `/verbose` · `/debug-prompt` · `/identity` ### Session `/clear` · `/cls` · `/compress` · `/save` · `/title` · `/usage` · `/undo` · `/retry` · `/queue` · `/activity` ### System `/sandbox` · `/tce` · `/browser-depth` · `/daemon` · `/suggestions` · `/update` · `/skills` · `/tools` · `/plugins` · `/cron` · `/runs` · `/trigger` · `/tasks` · `/adjust` · `/trace` · `/artifacts` · `/home` · `/doctor` · `/status` · `/show` · `/history` ### Sub-agents `/spawn-pause on|off|status` · `/recovery list|show|clear` · `/planner-guard on|off|status` ### Walkthrough and onboarding `/walkthrough` — guided tour of Aiden’s main capabilities ### Authentication `/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 ``` ### macOS ```bash export AIDEN_DAEMON=1 aiden daemon install ``` ### Windows See [`docs/v4.5/daemon-windows.md`](docs/v4.5/daemon-windows.md). Foreground execution with `aiden daemon start` is recommended for initial testing.
## Troubleshooting Common issues live in [`docs/v4.5/troubleshooting.md`](docs/v4.5/troubleshooting.md). Quick reference: - **Daemon already running** — inspect and remove a stale daemon runtime lock only after confirming no daemon process is active - **Webhook 401 despite valid HMAC** — confirm the expected webhook format - **IMAP authentication failure** — Gmail and Outlook commonly require app passwords - **High RSS or slow drain** — use the daemon soak tests and inspect active processes - **Boot stuck during setup** — non-TTY input may prevent interactive onboarding; configure the provider environment or use a supported non-interactive mode - **An old setup screen appears** — remove stale global binaries and reinstall with `npm install -g aiden-runtime@latest` - **`/help` does not list a command** — some commands require an active session or capability - **npm permission errors on Windows** — use a user-writable npm prefix and install into a normal directory rather than a drive root - **Native module version mismatch** — switch to Node 20 or Node 22, then reinstall `aiden-runtime` under that active Node version
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, infrastructure, and the time required to keep shipping. [![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 repository is appreciated.
## Acknowledgements Built solo by **Shiva Deore** at **Taracod**. Aiden builds on open-source foundations including TypeScript, Node.js, SQLite, `better-sqlite3`, Playwright, Chromium, `chokidar`, `croner`, `inquirer`, `marked`, `kleur`, the Model Context Protocol, and provider SDKs. Thank you to everyone building, testing, documenting, and maintaining the foundations that make Aiden possible.
## Contributing Aiden is built solo right now, but contributions are welcome — bug reports, skill submissions, provider adapters, tests, and documentation improvements. Before opening a PR: 1. Fork the repository 2. Run `npm install` 3. Make changes on a focused feature branch 4. Run `npm run typecheck` 5. Run `npm run build` 6. Test the relevant Aiden workflow locally 7. Open a PR with a clear description of what changed and why Keep PRs focused. One feature or fix per PR. Be honest about what works, what remains uncertain, and what was tested.
## License - **Core runtime:** [AGPL-3.0](LICENSE). You can self-host, modify, and distribute Aiden as long as covered modifications remain under the AGPL. - **Bundled skills:** Apache-2.0. - **Commercial licensing for closed-source derivatives:** contact [hello@taracod.com](mailto:hello@taracod.com). The planned `skills.taracod.com` marketplace will support community skills under their declared licenses.
## 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.18.0](https://github.com/taracodlabs/aiden/releases/tag/v4.18.0) · [v4.17.0](https://github.com/taracodlabs/aiden/releases/tag/v4.17.0) · [v4.16.1](https://github.com/taracodlabs/aiden/releases/tag/v4.16.1) · [v4.16.0](https://github.com/taracodlabs/aiden/releases/tag/v4.16.0) · [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) | | 📖 **Book — Omega** | [Amazon](https://amzn.to/49ceO8l) | | 📚 **Docs** | [`docs/v4.5/`](docs/v4.5/) | | 💖 **Sponsor** | [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 investigated and 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, tests, and documentation PRs are welcome. - **Sponsors and investors** — Aiden is built by one person and funded through client work. To help it grow faster, contact [contact@taracod.com](mailto:contact@taracod.com) or sponsor through [Razorpay](https://razorpay.me/@whitelotus9625). - **Beta testers** — try Aiden on real workflows, file reproducible issues, and share what works and what does not. ---

**By Taracod**
---

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