Aii — AI Agent for Your Terminal

An autonomous AI assistant that lives in your terminal. Ask it anything — it reads your files, runs commands, searches the web, and writes code. No copy-pasting, no tab-switching. Just describe what you want.

npm: @aiiware/aii · Version: 0.13.7 · Node.js: >= 18

Quick Start

# 1. Install
npm install -g @aiiware/aii

# 2. Go
aii -D hi there!

On first run, Aii auto-launches a setup wizard to configure your AI provider, model, and API key. After setup completes, your command executes automatically.

Already know your provider? You can also configure directly: aii config apikey <provider> <key>

Requirements: Node.js 18+ and Docker

What Can You Do With It?

Talk to it

aii explain how this codebase is structured

Pipe anything in

git diff | aii review these changes for bugs
cat error.log | aii what went wrong?
echo "Hello world" | aii translate to Japanese

Let it commit for you

aii run git commit -y

It reads your staged changes, writes a Conventional Commits message, and commits — one command.

Start an interactive session

aii

You get a rich terminal UI with streaming responses, syntax highlighting, diff previews, and autocomplete for slash commands.

Switch models on the fly

aii --model ollama/llama3.1:8b write a bash one-liner to find large files
aii --model deepseek/deepseek-chat explain this regex
aii --model openai/gpt-4.1 refactor this function

Or during a session: /model anthropic:claude-sonnet-4

Run it autonomously

aii loop "fix all failing tests" --verify "npm test" --budget 0.50

The agent loops with fresh context each iteration, stopping when your verification command passes, the budget is hit, or you press Esc. Steer it mid-run with /pause, /resume, /stop, /stats, /note, and /now. Feedback appears in a dedicated toast zone — not mixed into agent output.

Providers

8 LLM providers, switch anytime with aii config provider <name>:

Ollama users: aii config provider ollama auto-discovers your installed models and lets you pick from an interactive menu.

Tools

The agent autonomously picks from 10 built-in tools:

You control what the agent can do. By default, it asks before running commands or writing files. Use --auto to skip confirmations.

Slash Commands

During interactive sessions, type / to see all commands. Highlights:

Keyboard Shortcuts

Key Features

Subagents

The agent delegates complex tasks to specialized subagents running in parallel:

Define custom agents in .aii/agents/<name>.md with YAML frontmatter for custom system prompts, model tiers, and tool access.

Git Worktrees

Work on multiple features in parallel without stashing:

aii worktree create auth-refactor    # Create isolated workspace + branch
aii worktree list                    # See all worktrees
aii worktree merge auth-refactor     # Merge back
aii worktree clean                   # Remove all clean worktrees

Or use /worktree slash commands during a session.

Autonomous Loops

Run the agent in a continuous loop with guardrails:

aii loop "fix all TypeScript errors"
aii loop --max 10 --verify "npm test" "add missing tests"
aii loop --budget 1.00 --duration 8h "refactor the auth module"

Exit conditions: --max N, --budget $N, --verify "cmd", --promise "text", --duration <time>, --input-tokens N, --output-tokens N

Mid-loop controls — type while the loop runs:

Pause takes effect between tool calls — the agent finishes what it's doing, then waits. Timed pauses auto-resume after the duration. The status bar shows pause state with a countdown timer.

/note vs /now — /note queues guidance for the next iteration. /now delivers it immediately within the current turn, so the agent can pivot without waiting. If the agent has no more tool calls left, /now falls back to the next iteration — your note is never lost.

The status bar updates in real time with iteration count, token usage, estimated cost, and tool calls — you always know what the loop is doing and what it's costing.

Telegram Integration

Run the full agent from Telegram:

aii telegram pair mybot <bot-token>  # Pair with @BotFather token
aii telegram start mybot             # Start listening
aii telegram list                    # Manage bots

Responses stream live — you see the agent's reply building in real time, just like in the terminal.

Start a conversation in Telegram, continue it from the CLI — or vice versa.

Soul System

Each agent has a personality — called a soul — that shapes how it communicates. Built on SoulSpec v0.4.

aii soul help                     # See available souls
aii soul switch doer              # Switch personality

Or during a session: /soul doer

Built-in souls:

Your preference persists across sessions and channels.

Custom souls: Create your own in .aii/soul/ with SOUL.md, STYLE.md, IDENTITY.md, and an optional soul.json manifest. Custom souls introduce themselves as "{Name}, powered by Aii 🪼".

Theme System

7 built-in color themes — switch with /theme <name> or aii config set theme <name>:

classic (default), brand, teal, indigo, forest, amber, grayscale

Your preference persists across sessions.

Skills System

Extensible instruction packages you can install and invoke:

/skills                                        # List all skills
/skills install owner/repo/skill-name          # Install from GitHub
/aii how do loops work?                        # Built-in: self-serve help
/commit                                        # Built-in: AI git commit
/review-pr                                     # Built-in: PR review
/explain this function                         # Built-in: code explainer
/<custom-skill> [args]                         # Any user-invocable skill

Install accepts GitHub URLs in any format — repo paths, blob URLs, and bare repo URLs all work.

Create skills in .aii/skills/<name>/SKILL.md with YAML frontmatter.

Project Instructions (AGENTS.md)

Drop an AGENTS.md file in your project root to give the agent project-specific context — coding conventions, architecture notes, preferred patterns. It's loaded automatically.

/init                   # Auto-generate by analyzing your project
/memory                 # View loaded instructions

Also discovers CLAUDE.md, .cursorrules, and .github/copilot-instructions.md.

Hook System

Run custom scripts when the agent takes actions. Configure in .aii/hooks.json:

Events: PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop

/hooks                  # View configured hooks
/hooks reload           # Hot-reload without restart

MCP Servers

Extend the agent with Model Context Protocol servers:

aii mcp catalog                    # Browse available servers
aii mcp install github             # One-command install
aii mcp add my-server npx my-mcp   # Add custom server
aii mcp list-tools github          # Discover tools
aii mcp test github                # Connectivity test

MCP servers connect in the background during session start — no waiting on first use. If a server drops, use /mcp reconnect <server> or /mcp reconnect all to restore it without restarting your session.

Server Sessions

Conversations persist across restarts and channels:

aii sessions list                  # Browse recent sessions
aii sessions resume <id>           # Pick up where you left off
aii sessions info <id>             # View stats (tokens, cost, tools)

Configuration

aii config init                          # Interactive setup wizard
aii config show                          # Current settings
aii config validate                      # Check config + API key validity
aii config set <key> <value>             # Set a specific value
aii config provider [name]               # Show or switch provider
aii config model [name]                  # Show or switch model
aii config apikey <provider> [key]       # Set API key (masked input)
aii config apikey list                   # Show all provider key status
aii config apikey remove <provider>      # Remove a provider's key
aii config apikey help                   # Show API key help
aii config host [host:port]              # Show or change server URL
aii config models                        # List all available models
aii config providers                     # List all providers with status
aii config help                          # Show config help

Config lives in ~/.aii/:

Environment variables also work: ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, etc.

CLI Reference

Global Flags

Troubleshooting

Run aii doctor for automated diagnostics.

Links

• npm: @aiiware/aii
• Website: aiiware.com

License: Proprietary — Copyright 2025-present AiiWare.com. All rights reserved.