Quick Start

Get up and running in under a minute.

1. Install

One command installs Node.js and the Aii CLI — Docker only if you later choose the local path:

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

Or if you already have Node.js 18+:

npm install -g @aiiware/aii

2. Go

aii

On first run, Aii shows a choice screen — start free on Aii Cloud (no Docker, no key), or set up your own key or a local Ollama model. The provider wizard only runs if you choose the local path; the first-run choice takes it from here.

Update

aii install

Self-updates to the latest version. Use aii install 0.13.10 to pin a specific version.

What Can You Do With It?

Real commands, real results. Here's what Aii does in your terminal:

Interactive Mode

aii

Just type aii to start an interactive session. Ask questions, edit files, run commands, and use slash commands — all in a persistent conversation with full project context.

Understand Any Codebase

aii explain how this project works

Drop into any repo and get an instant architectural overview — files, patterns, dependencies, all synthesized from the actual code.

Fix Bugs Autonomously

aii fix the failing tests --auto

Point Aii at a problem and let it work. It reads files, edits code, runs tests, and iterates until the fix passes.

AI-Powered Git Workflow

aii run git commit -y

Analyzes your staged changes and generates a conventional commit message automatically.

Process Anything via Pipe

git diff | aii summarize the changes

Pipe any output to Aii for instant analysis — logs, diffs, error traces, API responses.

Autonomous Loops

aii loop "improve test coverage" --verify "npm test" --budget 5

Set a goal, define exit conditions, and let the agent work continuously until the task is done or the budget is hit.

CLI Reference

The Aii CLI is an autonomous AI agent for your terminal. It reads files, writes code, runs commands, and searches the web — all through natural language.

Commands

Agent Tools

Tools the agent uses autonomously during execution:

Options

Examples

# Start interactive agent session
aii

# Ask a question
aii explain what git rebase does

# Execute a task with agent capabilities
aii refactor this file to use async/await

# Auto mode (auto-approve all actions)
aii fix the failing tests --auto

# Pipe content for processing
cat error.log | aii summarize the errors

# Generate git commit message
aii run git commit

Slash Commands

Available inside interactive agent mode. Type /help to see all commands.

Telegram Bot Channel

Connect Aii to Telegram as a bot — chat with your AI agent from anywhere, on any device.

# Pair a bot with your Telegram token
aii telegram pair mybot 7123456789:AAF...xyz

# Pair with a specific project directory
aii telegram pair mybot TOKEN --project /path/to/project

# Start the bot
aii telegram start mybot

# List all configured bots
aii telegram list

Architecture

All Aii clients connect to a single local server that routes requests to your configured LLM provider.

    Aii CLI         Aii VSCode        Aii Chrome
    v0.14.9            v0.8.3            v0.5.7
       |                 |                 |
       +-----------------+-----------------+
                         |
             WebSocket (localhost:26169)
                         |
                +--------+--------+
                |   Aii Server    |
                | Docker · :26169 |
                +--------+--------+
                         |
       +-----------------+-----------------+
       |                 |                 |
   Anthropic          OpenAI           Google    ...
   (Claude)           (GPT)           (Gemini)

Soul System

Each Aii agent has a soul — a personality that shapes how it communicates. Souls define tone, vocabulary, and interaction style without changing what the agent can do. Built on the open SoulSpec v0.4 standard.

Built-in Souls

Each soul is defined by four files: SOUL.md (personality and values), STYLE.md (communication rules), IDENTITY.md (who the agent is), and AGENTS.md (operational workflow and tool behaviors). A soul.json manifest ties them together with metadata and versioning. These are resolved automatically — you just pick a name.

Switching Souls

Switch souls from the CLI or mid-session with a slash command. Your preference persists to ~/.aii/config.yaml and applies across all channels.

# Show available souls
aii soul help

# Switch to doer
aii soul switch doer

# Switch to coder
aii soul switch coder

# Switch back to thinker (default)
aii soul switch thinker

# During an interactive session
/soul doer
/soul coder

Personas

A persona bundles soul + skills + hooks + instructions + theme into a single installable package. One command to load a complete AI engineering identity. Built on SoulSpec v0.4 and the Agent Skills standard.

Commands

Install Sources

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

# From GitLab
aii persona install gitlab:owner/repo/persona-dir

# From local directory
aii persona install ./my-persona

Official Personas

Browse and install from github.com/aiiware/aii-personas

Create Your Own

A persona is a directory with a persona.json manifest at its root, plus skill, soul, hook, and theme files. See the official personas for examples.

my-persona/
├── persona.json          # Manifest (name, version, skills, soul, hooks)
├── skills/               # Bundled skills (SKILL.md files)
├── souls/                # Soul definition (SoulSpec v0.4)
├── hooks/                # Quality gates (hooks.json + scripts)
└── themes/               # Visual theme

Skills System

Skills are reusable prompt templates that extend the agent with domain-specific capabilities. They can be built-in, installed from GitHub, or created as custom project-level skills.

Built-in Skills

# Ask about Aii features
/aii how do loops work?
/aii what commands are available?

# Generate a commit message from staged changes
/commit

# Preview without committing
/commit --dry-run

# Explain code or concepts
/explain this function
/explain how the auth module works

# Review current PR
/review-pr

# Review a specific PR by number
/review-pr 42

Installing Skills

Install skills from GitHub repositories or manage installed skills. Install accepts GitHub URLs in any format — repo paths, blob URLs, and bare repo URLs all work.

# Install a skill from GitHub
/skills install owner/repo/skill-name

# List all available skills
/skills

# Reload skills after changes
/skills reload

# Uninstall a skill
/skills uninstall skill-name

Custom Skills

Create custom skills by adding a SKILL.md file in your project's .aii/skills/ directory or globally in ~/.aii/skills/.

---
name: my-skill
description: What this skill does
argument_hint: "[options]"
allowed_tools:
  - Bash
  - Read
  - Grep
---

# My Custom Skill

Instructions for the agent when this skill is invoked...

## Steps
1. First do this
2. Then do that

MCP Integration

The Model Context Protocol (MCP) connects Aii to external tools and services. Install servers from the built-in catalog or add custom ones to extend what the agent can do.

Commands

# Browse and install from catalog
aii mcp catalog
aii mcp install filesystem

# Add a custom server
aii mcp add myserver npx my-mcp-server --port 3000

# Check status of all servers
aii mcp status

# List available tools
aii mcp list-tools

Catalog

The MCP catalog provides a curated list of servers that can be installed with a single command. Server configurations are stored in ~/.aii/mcp_servers.json.

Autonomous Loops

Autonomous loops let the agent work continuously on a task until a completion condition is met. Configure exit conditions to control when the loop stops. Steer the agent mid-run with pause, resume, stop, note, and now commands — feedback appears in a dedicated toast zone, not mixed into agent output.

CLI Usage

# Basic loop with max iterations
aii loop "refactor all components to use hooks" --max 20

# Loop with verification command
aii loop "fix all test failures" --verify "npm test"

# Loop with budget limit
aii loop "improve test coverage" --budget 5

# Loop with duration limit
aii loop "clean up technical debt" --duration 30m

# Loop with completion promise
aii loop "migrate to TypeScript" --promise "ALL_FILES_MIGRATED"

# Combine multiple conditions
aii loop "fix all lint errors" --verify "npm run lint" --max 50 --budget 3

# Interactive: start from a session
/loop "optimize database queries" --max 10 --verify "npm test"

Exit Conditions

Mid-Loop Controls

Type these commands while the loop is running to steer the agent:

Pause takes effect between tool calls — the agent finishes its current tool, then waits. The status bar shows real-time telemetry including pause state with 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.

Session Management

Sessions persist across channels — start a conversation in the CLI, continue it in VSCode, and pick it up again from Telegram. All sessions are managed by the Aii Server.

CLI Commands

# List all sessions
aii sessions list

# Filter by project
aii sessions list --project /path/to/project

# Show session details
aii sessions info abc123

# Resume a previous session
aii sessions resume abc123

Slash Commands

# List sessions from inside a chat
/sessions list

# View session info
/sessions info abc123

# Resume a session
/sessions resume abc123

# Rename current session
/sessions rename abc123 my-feature-work

Hook System

Hooks let you run custom logic in response to agent events — validate tool calls before they execute, log actions, or enforce project rules.

Events

Hook Types

Configuration

Configure hooks in .aii/hooks.json (project-level) or ~/.aii/hooks.json (global).

{
  "hooks": [
    {
      "event": "PreToolUse",
      "type": "script",
      "command": "node .aii/validate-tool.js",
      "timeout": 10000
    },
    {
      "event": "PostToolUse",
      "type": "script",
      "command": "echo \"Tool $TOOL_NAME completed\""
    }
  ]
}

Worktrees

Git worktrees let you work on multiple branches simultaneously in isolated directories. Aii manages worktrees automatically — creating branches, tracking changes, and cleaning up when done.

CLI Commands

# Create a worktree for a new feature
aii worktree create my-feature

# List all active worktrees
aii worktree list

# Clean up finished worktrees
aii worktree clean

Slash Commands

Alias: /wt can be used instead of /worktree.

Subagent System

Subagents are specialized AI workers that the agent delegates tasks to. Each subagent runs in its own context with a focused purpose, keeping the main conversation clean and enabling parallel work.

Built-in Agents

# In interactive mode, view available agents
/agents

# View running and completed tasks
/tasks

# View details of a specific task
/tasks task-id

Custom Agents

Define custom agent types with an AGENT.md file in .aii/agents/ or ~/.aii/agents/.

---
name: my-agent
description: Specialized agent for specific tasks
model_tier: standard
permission_mode: default
max_iterations: 50
allowed_tools:
  - Read
  - Grep
  - Glob
  - Bash
---

# My Custom Agent

You are a specialized agent that...

## Guidelines
- Focus on specific domain
- Follow these patterns

LLM Configuration

Aii supports 8 LLM providers. Switch between them at any time.

API Key Management

Use aii config apikey to set, list, or remove provider API keys. Keys are stored securely in ~/.aii/secrets.yaml with 0600 permissions.

# Set API key inline
aii config apikey anthropic sk-ant-xxx

# Set API key with masked input prompt
aii config apikey openai

# Set Ollama URL (Ollama uses URL instead of API key)
aii config apikey ollama http://localhost:11434

# List all configured providers
aii config apikey list

# Remove a provider key
aii config apikey remove deepseek

Supported providers: anthropic, openai, gemini, deepseek, moonshot, zai, ollama, openrouter. You can also use environment variables:

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

Ollama (Local Models)

Ollama runs AI models locally on your machine. When you switch to Ollama, the CLI automatically queries your installed models and presents an interactive selector — no need to memorize model names.

# Switch to Ollama — auto-detects installed models
aii config provider ollama

# CLI queries localhost:11434 and shows:
# Select an Ollama model:
#   ► llama3.1:8b
#     mistral:7b
#     codellama:13b
#     gpt-oss:20b
#     gemma2:9b

If Ollama is not running or has no models installed, the CLI falls back to a default and provides guidance. To configure a custom Ollama URL (e.g., remote server), use aii config apikey ollama http://your-host:11434.

Configuration

Aii configuration lives in ~/.aii/. Project-level settings go in .aii/ inside your project root.

# ~/.aii/config.yaml
llm:
  provider: anthropic
  model: claude-haiku-4-5
  temperature: 0.7
  max_tokens: 4000

api:
  url: http://localhost:26169

streaming:
  enabled: true

output_modes:
  default: standard   # clean | standard | thinking

AGENTS.md

Create an AGENTS.md file in your project root to give Aii project-specific context. Run /init inside a chat session to generate one automatically.

aii
# Inside the session:
/init                    # Generate AGENTS.md
/memory list             # Show loaded instruction files

Environment Variables

Troubleshooting

Use the built-in diagnostics and debug flags to identify and resolve issues quickly.

aii doctor

Run aii doctor to check system health. It runs 5 checks and reports status for each:

Aii Doctor v0.14.9

  Config .............. OK  (~/.aii/config.yaml)
  API Key ............. OK  (google/gemini-2.5-flash)
  Aii Server .......... OK  (127.0.0.1:26169)
  MCP Servers ......... OK  (4 configured)
  Node.js ............. OK  (v24.7.0)

  All checks passed.

Common Issues

For detailed debugging, use the --debug or --verbose flags with any command to see additional diagnostic output.

VSCode Extension

AI-powered code generation, commit messages, and interactive chat directly in your editor. Install from Marketplace

Chrome Extension

Side panel chat with full page context awareness. Install from Chrome Web Store

• Intelligent page context awareness — AI understands what you're reading
• Real-time streaming responses
• Slash commands — type / to access 80+ AI prompts
• Selection quick actions — select text to translate, explain, or summarize
• Custom prompts — create and organize your own AI prompts
• Conversation history saved locally
• Download as Image — export AI responses as PNG
• Privacy-focused — no data sent to third parties