Quick Start

One-command install (recommended)

curl -fsSL https://aiiware.com/install.sh | bash

Installs everything — Node.js, Aii CLI, Docker, and the AI server. No prerequisites.

Or via npm

npm install -g @aiiware/aii
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 (both auto-installed if missing)

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, and /note. Feedback appears in a dedicated toast zone — not mixed into agent output.

Providers

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

| Provider | What You Get | |----------|-------------| | Anthropic | Claude Sonnet 4, Opus 4, Haiku 4.5 | | OpenAI | GPT-5.2, GPT-4o, GPT-4.1 | | Google | Gemini 3-pro, 2.5-pro, 2.5-flash | | DeepSeek | deepseek-chat, deepseek-reasoner | | Moonshot | Kimi K2 Thinking, Vision | | Z.ai | GLM-4.7, GLM-4.6V, GLM-4.5 | | Ollama | Any local model — free, private, offline | | OpenRouter | 300+ models through one API key |

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:

| Tool | What It Does | |------|-------------| | Read | Read any file | | Write | Create or overwrite files | | Edit | Surgical find-and-replace edits | | Glob | Find files by pattern | | Grep | Search file contents (regex) | | Bash | Run shell commands | | WebSearch | Search the web | | WebFetch | Fetch and parse web pages | | Task | Delegate to parallel subagents | | Skill | Invoke extensible skill packages |

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:

| Command | What It Does | |---------|-------------| | /help | Show all commands | | /model [name] | View or switch model | | /provider [name] | View or switch provider | | /soul [name] | View or switch soul (thinker, doer, coder) | | /theme [name] | View or switch color theme | | /auto | Toggle auto-approve mode | | /plan | Toggle plan mode (read-only) | | /diff | See all file changes this session | | /undo | Revert the last file change | | /stats | Session stats — tokens, cost, duration | | /context | Context window usage; /context clear to summarize | | /aii [question] | Ask about Aii features, commands, and usage | | /commit | AI-powered git commit | | /review-pr | AI-powered PR review | | /worktree create | Isolated workspace for experiments | | /mcp install | Add MCP server from catalog | | /mcp reconnect | Reconnect failed MCP servers | | /persona [action] | Manage workspace personas (install, use, list, status) | | /skills | List and manage skill packages | | /sessions | Browse and resume past sessions | | /exit | End session with summary |

Keyboard Shortcuts

| Key | Action | |-----|--------| | Enter | Submit input | | Esc | Cancel current request | | Ctrl+C | Exit immediately | | Ctrl+D | Graceful exit with session summary | | Ctrl+L | Clear conversation | | Ctrl+U | Clear type-ahead queue / input line | | Up/Down | Navigate input history | | Tab | Autocomplete commands |

Key Features

Subagents

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

| Agent | Purpose | Tools | |-------|---------|-------| | Explore | Fast codebase search and analysis | Read-only | | Plan | Architecture and implementation design | Read-only | | Review | Code quality analysis | Read-only | | Code | Full implementation | All tools |

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:

| Command | What It Does | |---------|-------------| | /pause [duration] | Pause after the current tool call (e.g., /pause 5m, /pause 2h) | | /resume | Resume a paused loop | | /stop | Finish current turn, then exit cleanly | | /stats | Live view of tokens, cost, iterations, elapsed time | | /note <text> | Inject a note immediately — the agent sees it at the next tool call boundary | | Plain text + Enter | Queue guidance — consumed one per iteration with visual feedback |

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 plain text — /note delivers your message immediately within the current turn, intercepting the next tool call so the agent can pivot without waiting. Plain text queues guidance for the next iteration — the agent sees it when the new iteration starts. If the agent has no more tool calls left, /note falls back to the next iteration — your note is never lost.

/note also works in Normal mode (interactive sessions) — type it while the agent is processing to steer it mid-turn.

Migration note: /now still works as an alias in v0.13.10 but will be removed in a future version. Use /note instead — same behavior, clearer name.

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:

| Soul | Display Name | Style | |------|-------------|-------| | thinker | Aii Thinker 🪼 | Patient and collaborative — thinks out loud, walks through reasoning (default) | | doer | Aii Doer 🪼 | Direct and efficient — leads with the answer, every sentence earns its place | | coder | Aii Coder 🪼 | Pair-programming partner — reads your codebase, references specific lines |

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

Personas

Bundle soul, skills, hooks, instructions, and theme into a single installable package — one command to load a complete AI engineering identity.

# Install from GitHub
aii persona install github:aiiware/aii-personas/aiiware-full-stack-engineer

# Install from GitLab
aii persona install github:aiiware/aii-personas/aiiware-full-stack-engineer

# Activate it
aii persona use aiiware/full-stack-engineer

# Switch roles instantly
aii persona use aiiware/code-reviewer
aii persona use aiiware/mentor

# Check what's active
aii persona status

# Deactivate
aii persona use --none

Official personas: github.com/aiiware/aii-personas

Or during a session: /persona use aiiware/full-stack-engineer, /persona list, /persona status

Create your own — just a directory with a persona.json manifest and skill/soul files. See the personas repo for examples.

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

| File | Purpose | |------|---------| | config.yaml | Provider, model, server host, preferences | | secrets.yaml | API keys (file mode 0600) | | mcp_servers.json | MCP server configuration |

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

CLI Reference

| Command | Description | |---------|-------------| | aii | Start interactive agent session | | aii <query> | Single-shot query | | aii run git commit [-y] | AI-powered git commit | | aii loop [query] [--flags] | Autonomous agent loop | | aii config <action> | Configuration management | | aii mcp <action> | MCP server management | | aii telegram <action> | Telegram bot management | | aii sessions <action> | Session management | | aii persona <action> | Workspace persona management | | aii skill <action> | Skill management (list, info, install) | | aii soul <action> | Soul (personality) management | | aii worktree <action> | Git worktree management | | aii prompt <action> | Prompt library | | aii upgrade | Self-update to latest version | | aii doctor | Health diagnostics | | aii help | Show help | | aii version | Show version |

Global Flags

| Flag | Description | |------|-------------| | --model <name> | Override model (e.g., deepseek/deepseek-chat) | | --auto | Auto-approve all tool actions | | -y, --yes | Auto-confirm prompts | | -c, --continue-chat <id> | Resume a specific session | | -n, --new-chat | Force new session | | -i, --interactive | Force interactive mode | | --offline | Disable web search and MCP | | -D, --direct | Direct LLM mode (bypass server intent recognition) | | --no-colors | Disable colors | | --no-streaming | Disable streaming output | | --show-tokens | Show token usage | | --show-cost | Show cost estimates | | -v, --verbose | Verbose output | | -d, --debug | Debug-level output |

Troubleshooting

Run aii doctor for automated diagnostics.

| Problem | Fix | |---------|-----| | aii not found | curl -fsSL https://aiiware.com/install.sh \| bash | | Update to latest | aii upgrade | | Server won't start | Make sure Docker is running | | API key error | aii config apikey <provider> <key> or aii config init | | Wrong model | aii config model <name> | | Ollama not connecting | Start Ollama first, then aii config provider ollama | | Context window full | /context clear during session |

Links

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

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