█████╗  ██╗██████╗ ███████╗███╗   ██╗
██╔══██╗██║██╔══██╗██╔════╝████╗  ██║
███████║██║██║  ██║█████╗  ██╔██╗ ██║
██╔══██║██║██║  ██║██╔══╝  ██║╚██╗██║
██║  ██║██║██████╔╝███████╗██║ ╚████║
╚═╝  ╚═╝╚═╝╚═════╝ ╚══════╝╚═╝  ╚═══╝

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

Install · Capabilities · Models · Skills · Commands · Documentation · Discord

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.

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.

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

Inspect this repository, explain how it works, identify the three highest-risk areas, and support the findings with repository Evidence.

Find the cause of the failing tests, fix the root problem, rerun the relevant tests, and show me exactly what changed.

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
• Archived RC: v4.19.0-rc.1

Stable — v4.21.2

npm install -g aiden-runtime
aiden

Open the browser Workbench instead:

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:

npm latest → 4.21.2

Without permanent installation:

npx aiden-runtime@latest

The v4.19.0-rc.1 release candidate is archived.

Verify the installed version

aiden --version

Expected output:

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:

npx aiden-runtime@latest --version

Want Aiden to react to files, schedules, email, or webhooks? Enable autonomous triggers:

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.
• 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 or the Aiden Discord community. 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.

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.

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|<N>] lists; /adjust <task_id> cancel or /adjust <task_id> goal <new text> 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 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/.

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. OAuth subscription routing for ChatGPT Plus where supported. | | 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.

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.

https://github.com/user-attachments/assets/323c9aa7-959a-425a-a5b3-4bae2b1a14bc

Install, update, and first run

Linux / WSL / macOS

npm install -g aiden-runtime
aiden

Or launch the Workbench:

aiden web

Windows

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

npx aiden-runtime@latest

After pulling updates

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:

aiden update --check
aiden update
aiden update --yes
aiden update --version 4.21.0

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:

/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:

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

npm uninstall -g aiden-runtime

To also remove your local Aiden home, including config, sessions, memory, and installed skills:

# Linux / macOS
rm -rf ~/.aiden

# Windows PowerShell
Remove-Item -Recurse -Force $env:LOCALAPPDATA\aiden

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:

aiden setup

To diagnose your environment without re-running setup:

aiden doctor

Switching models

Inside the REPL:

/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:

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 | | Install a skill from the registry | /skills install <name> | | Remove a skill | /skills remove <name> | | Reload skills after edits | /skills reload |

Contributing skills

Skills live in 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 <provider>/<model> | | 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 <p> | Add a file-watcher trigger | | aiden trigger add webhook --label <n> | Add an HTTP webhook trigger | | aiden trigger add cron --schedule "<expr>" | Add a scheduled trigger | | aiden trigger list | List configured triggers | | aiden runs list | List recent interactive and daemon runs | | aiden runs show <id> | 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

export AIDEN_DAEMON=1
aiden daemon install
loginctl enable-linger $USER

macOS

export AIDEN_DAEMON=1
aiden daemon install

Windows

See 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.

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.

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.

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. 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 [email protected].

The planned skills.taracod.com marketplace will support community skills under their declared licenses.

Links

| Where | What | |---|---| | 🌐 Website | aiden.taracod.com | | 💬 Discord | discord.gg/CU5wshJW4F | | 📦 npm | aiden-runtime | | 🐙 Source | github.com/taracodlabs/aiden | | 📁 Standalone releases | github.com/taracodlabs/aiden-releases | | 🧾 Release notes | v4.18.0 · v4.17.0 · v4.16.1 · v4.16.0 · v4.15.1 · v4.15.0 · v4.13.0 · v4.12.0 | | 📖 Book — Omega | Amazon | | 📚 Docs | docs/v4.5/ | | 💖 Sponsor | razorpay.me/@whitelotus9625 | | ✉️ Contact | [email protected] |

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 [email protected] or sponsor through Razorpay.
• Beta testers — try Aiden on real workflows, file reproducible issues, and share what works and what does not.

By Taracod · White Lotus