Quick Start

Install (one command)

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

Installs Node.js and the Aii CLI — no Docker required to get started. (Prefer npm? npm install -g @aiiware/aii.)

Start free — no Docker, no API key

aii cloud login
aii "what can you do?"

Sign in with Google or GitHub and your first answer lands in seconds — free on Aii Cloud (a daily free budget, no card required). Point it at a project and it reads your files, runs the tools it needs, and gets to work.

Go unlimited — your own key, your own budget

Prefer no daily limit and full local control? Point Aii at your own provider key and it runs a local AI server (via Docker) that your provider bills directly — no Aii limit.

aii config apikey anthropic <your-key>
aii "refactor this module and run the tests"

Supported providers include Anthropic, OpenAI, Google, and more. No key yet? Just run aii "…" and the setup wizard walks you through provider, model, and key. This is the home for heavy, sustained use.

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. Control the attribution footer (also on aii run git pr) with --no-signature / --signature "<text>", or persist it via git.commit_signature in config.

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

Or during a session: /model deepseek:deepseek-chat

Run it autonomously

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

The agent loops until your verification command passes or a limit is hit — see Autonomous Loops. Or give an interactive session a standing objective with /goal.

Providers

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

| Provider | What You Get | |----------|-------------| | Anthropic | Claude (Sonnet · Opus · Haiku) | | OpenAI | GPT + o-series | | Google | Gemini (pro · flash) | | DeepSeek | deepseek-chat, deepseek-reasoner | | Moonshot | Kimi | | Z.ai | GLM family | | 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 its built-in tools:

| Tool | What It Does | |------|-------------| | Read / Write / Edit | Read, create, and surgically edit files | | Glob / Grep | Find files by pattern, search contents (regex) | | Bash | Run shell commands (plus background jobs) | | WebSearch / WebFetch | Search the web, fetch and parse pages | | Task | Delegate to parallel subagents | | Skill | Invoke extensible skill packages |

…plus task-planning and interaction helpers. 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] / /provider [name] | View or switch model / provider | | /auto | Toggle auto-approve mode | | /plan | Toggle plan mode (read-only) | | /goal [objective] | Set a session goal the agent works toward autonomously (see Session Goals) | | /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 | | /exit | End session with summary |

Keyboard Shortcuts

| Key | Action | |-----|--------| | Esc | Cancel current request | | Ctrl+D | Graceful exit with session summary | | Ctrl+L | Clear conversation | | Ctrl+O | Peek full tool output · toggle subagent tree | | Ctrl+U | Clear type-ahead queue / input line |

Key Features

Subagents

The agent delegates complex work to specialized read-only subagents running in parallel — explore, plan, review, code-reviewer, code-architect, researcher — keeping the main context clean while they fan out.

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

Task Planning

For multi-step work, the agent breaks the job into a live task list and renders it inline in the stream — pending (☐), in-progress (▪), and done (✓) — updating as it goes. The plan is visible, not a black box: you always see what it intends to do next and what's already finished.

Security

Aii is an autonomous agent — so it's built to act without handing over your machine:

| Protection | What it does | |------------|--------------| | Workspace fence | File reads and writes stay inside your workspace, resolved through realpath so .. and symlink escapes are blocked; sensitive paths (~/.aii secrets, keychains) are denylisted | | Permission model | Asks before running commands or writing files; grants are scoped (per path / per session); --auto opts out when you trust the run | | Untrusted-content framing | Web and MCP content is fenced as untrusted, so a malicious page can't smuggle instructions into the agent (prompt-injection defense) | | Supply-chain integrity | Installed skills and personas are pinned by commit SHA and checked against per-file SHA-256 manifests at load — fail-closed if anything's been tampered with | | Persona-hook consent | Hooks bundled in a remotely-installed persona require explicit first-use consent (keyed on install origin), so adding a persona can't silently run code | | Per-channel caps | Telegram bots get a capability cap — read-only, no-bash, or full — so a chat bridge isn't a full shell by default |

Local-first by design — your code and API keys stay on your machine; the only thing that leaves is the prompt you send to your chosen LLM provider.

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 clean                   # Remove all clean worktrees

During a session, /worktree adds merge, diff, and commit: /worktree merge auth-refactor merges back.

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); timed pauses auto-resume | | /resume / /stop | Resume a paused loop / finish the current turn and exit cleanly | | /stats | Live view of tokens, cost, iterations, elapsed time | | /note <text> | Inject guidance immediately — seen at the next tool call (also works in normal sessions) | | Plain text + Enter | Queue guidance for the next iteration |

A canceled or exhausted loop is resumable: /loop list shows saved loops, /loop resume <id> continues one with its remaining limits. The status bar tracks iterations, tokens, cost, and pause state in real time.

Session Goals

Give the interactive session a persistent objective it keeps working toward until evidence says it's done — no more typing "keep going" after every turn:

/goal Make the checkout suite pass, verified by `npm test -w checkout`,
      without changing public API behavior. --budget 2.00

While a goal is active, the agent sees the objective every turn and auto-continues between turns — working, then declaring GOAL COMPLETE — evidence: … or GOAL BLOCKED — <what it needs>. The lifecycle stays yours:

| Command | What It Does | |---------|-------------| | /goal <objective> | Set the goal — flags: --verify "cmd" (repeatable), --budget, --auto-turns (0 or unlimited; default: unlimited — a goal runs until achieved), --max-time, --max-tokens, --no-proof, --no-auto/--auto-approve, --auto | | /goal | Status view — objective, status, verify, limits, usage | | /goal draft <description> | The model proposes a strong goal contract; you edit + submit | | /goal edit <text and/or flags> | Revise in place | | /goal pause / resume / clear | Suspend / re-arm / remove |

Verified completion — with --verify armed, GOAL COMPLETE only counts when every command exits 0; failures keep the goal active and feed back to the agent, so "done" means provably done. Even without --verify, a bare completion isn't taken at face value: the agent gets one nudge to show proof, self-contradicting evidence is rejected, and an uncapped goal (the default) never ends on an unverified claim (opt out with --no-proof or goal.proof_expected: false in config).

Guardrails: a goal runs until achieved by default and its own turns auto-approve tools (workspace-fenced; your typed turns keep prompting — opt out with --no-auto or goal.auto_approve: false in config) — cap it with --auto-turns <n> or a durable goal.auto_turns in config; anti-spin pauses a goal that stops doing work, limit stops hand off with measured progress/remaining/next, typing always wins the turn, Esc pauses, and the ◎ Goal status-bar segment keeps the state in view.

Finding a goal again — every goal carries its session's short id (◎ Goal paused #7khq), shown on the set card, status bar, /goal view, and the exit summary (which prints the exact pick-up command). Across sessions:

| Command | Purpose | | --- | --- | | aii goals | List every goal in this project's saved sessions — id, status, objective, usage, age | | aii --continue | Resume the most recent session of this project (conversation + goal) | | aii --continue <id> | Resume a specific session by short or full id (aii --continue 7khq) |

Sessions holding an open goal are exempt from the automatic session cleanup (up to 30 days since the goal last moved), so a paused goal is never silently deleted; complete goals age out normally.

/goal vs /loop: a loop grinds a fixed prompt with fresh context each iteration; a goal keeps one conversation converging on an outcome. Starting a loop auto-pauses an active goal.

Telegram Integration

Run the full agent from Telegram:

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

Responses stream live, and conversations continue across channels — start in Telegram, pick up 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. Switch with aii soul switch doer or /soul doer in a session.

| 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: drop a soul directory (SOUL.md, STYLE.md, IDENTITY.md) in .aii/soul/.

Personas

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

aii persona install github:aiiware/aii-personas/aiiware-full-stack-engineer   # or gitlab:
aii persona use aiiware/full-stack-engineer     # activate (switch roles anytime)
aii persona status                              # check what's active
aii persona use --none                          # deactivate

Official personas: github.com/aiiware/aii-personas — or create your own: a directory with a persona.json manifest and skill/soul files. In-session: /persona use, /persona list, /persona status.

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                     # Install a community skill repo
/skills install owner/repo/skill-name          # Install a specific skill
/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

Install accepts GitHub refs in any format — a bare owner/repo (Aii finds the skill, whether it's at the repo root or in a subdirectory, e.g. aii skill install tt-a1i/archify), explicit repo paths, blob URLs, and tree URLs. Every install pins the commit SHA, fetches binaries intact, and shows a trust preview (name, license, script payload) before anything is written — pass --yes to skip the prompt in scripts. Create your own 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, TaskCompleted

/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

MCP servers connect in the background during session start. If a server drops, /mcp reconnect <server> restores 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

Configuration

aii config init                          # Interactive setup wizard
aii config init --project                # Scaffold project config for this repo
aii config show --sources                # Per-key provenance (env/local/project/global)
aii config validate                      # Check config + API key validity
aii config set <key> <value>             # Set a specific value
aii config provider|model [name]         # Show or switch provider / model
aii config apikey <provider> [key]       # Set API key (masked input)

Run aii config help for the full list. 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 |

Common preference keys, one file:

# ~/.aii/config.yaml
git:
  commit_signature: none    # commit/PR footer: default | none | any literal text
sessions:
  keep: 50                  # most-recent sessions to retain; 0 = unlimited
goal:
  proof_expected: true      # /goal demands proof before accepting completion

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

Project-level config & commands

A repository can carry its own Aii config and slash commands — committed for the team, layered under your personal settings:

aii config init --project     # creates .aii/settings.json, gitignores .aii/settings.local.json

// .aii/settings.json (committed)
{
  "llm": { "model": "deepseek-v4", "provider": "deepseek" },
  "permissions": { "deny_write": ["db/migrations/**"], "deny_tools": ["Bash"] }
}

Precedence: flag > env > .aii/settings.local.json > .aii/settings.json > ~/.aii/config.yaml > defaults — your env pins always win; aii config show --sources shows where each value came from. A repo can only narrow, never widen: only safe keys are accepted (model, provider, output mode, persona, theme, deny rules); anything that would widen authority is rejected, and deny rules are enforced everywhere as hard tool errors.

Project slash commands live one markdown file per command under .aii/commands/ — typing /deploy staging expands .aii/commands/deploy.md (with $ARGUMENTS → staging) into the agent turn, and project commands carry a [project] badge in the / menu. First use asks once: a cloned repo's command, hook, or skill shows its full content and asks before it ever runs — remembered per file content in ~/.aii/project-trust.json until the file changes; headless runs fail closed. Skip the whole project layer with aii --no-project-config.

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 cloud <action> | Aii Cloud — connect this machine, dispatch from the web (BYOC) | | 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 plugin <action> | Plugin management | | aii prompt <action> | Prompt library | | aii upgrade | Self-update to latest version | | aii doctor | Health diagnostics |

Run aii help for the full command list.

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 | | --output-format <fmt> | json or stream-json (one-shot only) | | --tools / --exclude-tools <list> | Allow / deny specific tools | | --max-turns <n> | Cap ReAct iterations within a turn (0/unset = default 500) | | --max-budget-usd <amt> | Cumulative between-turns cost cap (0 = no cap) | | --bare | Result to stdout only; all chrome to stderr (one-shot) | | --append-system-prompt <text> | Append additive instructions to the run | | --append-system-prompt-file <path> | Append a workspace file of additive instructions |

Headless / CI Automation

Aii is scriptable and safe to run unattended:

# Bounded, machine-readable, pipe-clean:
aii "review the staged diff for correctness bugs" \
  --bare --max-turns 12 --max-budget-usd 1.00 --output-format json | jq -r '.result'

--max-turns bounds cost server-side; --bare keeps stdout pipe-clean for RESULT=$(aii "…" --bare); on a single one-shot turn, --max-budget-usd adds an advisory over_budget flag (pair with --max-turns to hard-bound cost). Ready-to-use GitHub Actions recipes live in examples/github-actions/ — they use the pull_request trigger (never pull_request_target with a PR checkout), reference AII_API_KEY via secrets., and consume Aii output as data (never eval).

Troubleshooting

Run aii doctor for automated diagnostics.

| Problem | Fix | |---------|-----| | aii not found | curl -fsSL https://aiiware.com/install.sh \| bash | | 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.