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

Autonomous AI Engine — local-first, Windows-native, yours to own

74 skills · 60 tools · 19 providers · 9 channels · AGPL-3.0

Windows · Linux · WSL · macOS (API Mode)

Aiden

Autonomous AI Engine — local-first, Windows-native, yours to own

74 skills · 60 tools · 19 providers · 9 channels · AGPL-3.0

aiden.first.message.mp4

A semi-autonomous AI agent that runs on your machine. Touches your files, browser, and shell. Remembers what matters. Built solo. Open source. Still rough in spots.

Try it in 60 seconds

npm install -g aiden-runtime
aiden

That's it. Pick a provider (Groq is free + fastest), paste your key, and start chatting.

Want autonomous triggers?

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.

aiden.skills.video.mp4

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 (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 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 <id>.
• Execution sandbox with risk tiers. Filesystem allowlist + Docker session backend + dry-run preflight. Default on; flip live with /sandbox on|off.
• State-aware browser depth. URL + DOM + iframe-tree capture before/after every browser tool call. Stale-ref auto-retry. Surfaces login / 2FA / captcha / consent blockers as structured cards.
• Continuous error recovery (TCE). 16 failure categories classified per tool call. Smart retry with cooldown. Dead-letter for permanent failures. Recovery report enriches the REPL's capability card.
• Live-flip slash commands. /sandbox, /tce, /browser-depth, /daemon status, /suggestions, /update — toggle every subsystem without restart. Choices persist to config.yaml.
• Update notification + /update CLI. Boot prompt when a newer version is on npm. Skip-this-version persistence. Install-method detection (npm-global / npx / standalone).

Full v4.5 internals: 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 Claude Pro and ChatGPT Plus.
60 built-in tools	Web search & fetch, deep research, YouTube search, Playwright browser automation (10 tools), file ops, process control, shell exec, code execution, system info, screenshot, clipboard, app launch, media keys, MCP bridge, memory ops, session list/search/summary/recall, skill view/list/manage, aiden_self_update.
74 bundled skills	Composable workflows each with a SKILL.md prompt, optional helper scripts, and tool requirements. GitHub PR/issue workflows, NSE / Upstox / Zerodha trading, Censys / Shodan / VirusTotal lookups, Windows Defender / Task Scheduler, Docker management, YouTube content tools, and more.
Self-promoting memory	USER.md + SOUL.md identity, plus MEMORY.md split between durable facts (compression-protected) and recent-session distillations. Each session ends with a structured summary that graduates durable facts into the protected section. Semantic recall over past sessions via recall_session.
Voice	Edge TTS / Windows SAPI text-to-speech, speech-to-text helpers.
Channel adapters	Discord, Slack, Telegram, WhatsApp, Email (IMAP+SMTP), Webhook, Twilio SMS, iMessage (macOS), Signal — any channel triggers the same agent loop.
Computer use	Screenshot capture, screen-state vision loop, browser automation. Mouse/keyboard automation partial.
v4.5 daemon mode (opt-in)	File watcher / webhook / email IMAP / scheduled triggers route through a durable trigger bus consumed by the Phase 5a dispatcher. Triggers fire → real agent runs → tool calls execute → run_events captures the chain. Off by default.
Plugins	Three bundled plugins: Chrome DevTools Protocol bridge, Claude Pro OAuth, ChatGPT Plus OAuth. Permission-state machine (pending-grant / loaded / suspended).
MCP	Model Context Protocol bridge — stdio + HTTP transports, schema discovery, tool dispatch.
Security moat	Tiered approval engine (safe / caution / dangerous), dangerous-command pattern classifier, honesty enforcement (post-loop scan rewrites false claims), memory guard, planner-guard tool narrowing, SSRF-safe URL fetcher, secret/PII pre-write scanner, skill-teacher (auto-create skills from successful flows).

Architecture

Aiden is a local-first agent loop: provider adapters feed a 90-turn ceiling, every tool call passes through verification + failure classification + recovery, and tool results stream back as structured envelopes the model can reason over. v4.5 added a SQLite daemon foundation alongside the REPL — file watchers and webhook endpoints write to a durable trigger bus, a single-worker dispatcher claims events, and each trigger fires a fresh agent turn keyed by a stable session id. Sandboxed execution (filesystem allow/deny + Docker session backend), state-aware browser observation, and continuous error recovery apply to daemon-fired turns identically to REPL turns.

Detailed diagrams + module map in docs/v4.5/architecture.md.

aiden.first.message.mp4

Install + first run

Linux / WSL / macOS (one-line)

npm install -g aiden-runtime
aiden            # interactive setup wizard fires on first run

Windows (one-line)

npm install -g aiden-runtime
aiden

If you hit native-build errors on Windows, install the windows-build-tools prerequisite first.

Try without installing

npx aiden-runtime

After pulling updates

npm install -g aiden-runtime@latest

Or, from inside a running session, the slash command: /update install

(Aiden also prompts you on boot when a newer version is on npm — see /update auto off to silence.)

Uninstall

npm uninstall -g aiden-runtime

To also wipe your local Aiden home (config, sessions, memory, skills):

# Linux / macOS
rm -rf ~/.aiden

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

aiden.first.message.mp4

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:

aiden setup

To diagnose without re-running:

aiden doctor

Switching models

Inside the REPL: /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:

export AIDEN_DEFAULT_PROVIDER=groq
export AIDEN_DEFAULT_MODEL=llama-3.3-70b-versatile

Recommended models

Use case	Best models
General-purpose / quality	Claude Sonnet 4.6 / Opus, GPT-5, Gemini 2.5 Pro
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 — Claude Sonnet 4.6, GPT-5, or Gemini 2.5 Pro. Smaller models work for simple tasks but agentic loops benefit from stronger reasoning.

💡 ChatGPT Plus / Claude Pro subscribers: use the OAuth flow instead of an API key. Pick chatgpt-plus or claude-pro as your provider during /model setup, then sign in via browser. No separate API costs — uses your existing subscription's model allowances.

Skills

Aiden ships with 74 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
Install a skill from 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 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 (<provider>/<model>)
AIDEN_SANDBOX	1	0 to disable filesystem allowlist + Docker session backend
AIDEN_TCE	1	0 to disable continuous error recovery
AIDEN_BROWSER_DEPTH	1	0 to disable state-aware browser observation
AIDEN_API_KEY	unset	Required for non-loopback daemon bind
AIDEN_NO_UPDATE_CHECK	0	Set to 1 to silence the boot-time update probe
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 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 <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 all configured triggers
aiden runs list	List recent agent runs (interactive + daemon)
aiden runs show <id>	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. 38 commands total.

Configuration

/model · /personality · /skin · /streaming · /reasoning · /verbose · /debug-prompt · /identity

Session

/clear · /compress · /save · /title · /usage

System

/sandbox · /tce · /browser-depth · /daemon · /suggestions · /update · /skills · /tools · /plugins · /cron · /runs · /trigger · /doctor · /status · /show · /history

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

export AIDEN_DAEMON=1
aiden daemon install
loginctl enable-linger $USER     # keep running between sessions

macOS

export AIDEN_DAEMON=1
aiden daemon install              # installs launchd plist

Windows

See 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. 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:\)

aiden.stocks.mp4

aiden.last.mp4

aiden.github.mp4

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, and the time to ship features instead of taking client work.

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

The future skills.taracod.com marketplace will ship community skills under the same permissive terms.

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
📖 Book — Omega	Amazon
📚 Docs	docs/v4.5/ (in this repo)
💖 Sponsor (Razorpay)	razorpay.me/@whitelotus9625
✉️ Contact	contact@taracod.com

Disclaimer

Aiden can touch your files, run shell commands, and access the web. It's autonomous within the limits you set. Things will go wrong sometimes. Use at your own risk, read the code if you're nervous, and report what breaks.

Built solo. Started as a hobby project. Still rough in spots. Getting better every week.

Welcome

• Contributors — bug reports, skill submissions, provider adapters, and documentation PRs are all welcome. See 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 or sponsor via Razorpay.
• 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

---

Local-first. Windows-native. Yours to own.