Get started

npm install -g @aiiware/aii
aii login
aii --inference cloud "explain how this codebase is structured"

Sign in with Google or GitHub. Your first answers run free on Aii Cloud, within a daily free budget and with no card required.

No Node.js yet? curl -fsSL https://aiiware.com/install.sh | bash installs Node.js and Aii together.

Why Aii

• Start free, no API key. aii login, then --inference cloud: a daily free budget, no card.
• Any model, on your bill. Your API key, your ChatGPT or Grok plan, or local models through Ollama.
• Your models, continued in the browser. aii --remote-control --inference server runs on your own Aii server; pick the conversation up on cloud.aiiware.com.
• One command, no session. Pipe anything in and get an answer: cat main.go | aii --inference cloud "explain this file". With your own Aii server, aii run git commit writes the commit message from your diff.
• Works until it is done. /goal make the tests pass --verify "npm test" keeps going until your check passes.
• Loops with guardrails. /loop "fix all TypeScript errors" --max 10 --verify "npm test" repeats the task until it passes or hits the limit.
• Runs from Telegram. With your own Aii server and a bot token from @BotFather, aii telegram start mybot puts the same agent in a chat after a one-time aii telegram pair; pick the conversation up in the terminal later.
• Yours to extend. Skills, MCP servers, hooks, subagents and AGENTS.md.
• And more. Git worktrees, memory, personas, themes and saved conversations: see Key Features.

What it does

git diff | aii --inference cloud review these changes for bugs
cat error.log | aii --inference cloud "what went wrong?"
aii --inference cloud                                 # interactive session

Ways to run it

| | Start with | What to know | | --- | --- | --- | | Aii Cloud | aii login, then add --inference cloud | A free daily budget, no card. Credits for more. | | Your API key | aii config apikey anthropic <your-key> | Your provider bills you, with no Aii limit. Uses your Aii server, which runs locally in Docker by default. | | Your subscription | aii connect chatgpt or aii connect grok | Uses your ChatGPT or Grok plan through your Aii server, which runs locally in Docker by default. | | Local models | aii config provider ollama | Models run on your machine through Ollama and your local Aii server (Docker). |

More examples

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.

While the agent works, you can keep typing:

| Input | What It Does | |-------|-------------| | Plain text + Enter | Steers the running turn on steering models; otherwise it waits for the turn to end | | /steer <text> | Steers the running turn on any model | | /queue <text> | Runs after the current turn | | /btw <question> | Asks a side question about the work; the agent never sees it | | /steering | Shows or sets the default: /steering on, off or auto | | !<command> | Runs a shell command after the current turn; at the prompt it runs at once |

Shell commands. Start a line with ! to run it as a shell command in the session's folder: !git status. It runs without approval, as in your own terminal: permission modes, allow and deny lists and hooks do not apply, and no model call is made. To send a message that starts with !, type \!. The command and its output join the conversation, so your next message can ask about it; with an active /goal the agent continues on its own and sees it. In Aii Cloud and remote sessions the output is shown but not added to the conversation. In the note Aii removes user:password@ from plain and JSON-escaped addresses and replaces its own provider keys, sign-in tokens and MCP server settings, and the values of environment variables whose names end in _TOKEN or _KEY or contain SECRET or PASSWORD, with [REDACTED]; other secrets in the output are sent as printed. Earlier replies that quoted a command's output are sent as they are. A command has 120 seconds and no keyboard, so prompts for input or a password fail. ! does not run during a loop.

Resume a saved conversation

aii resume

Browse All workspaces, choose a folder, then choose a conversation to continue. Aii validates the saved session and switches into its folder; your parent shell stays in its launch folder. See Saved Conversations for keyboard controls, search and exact-ID commands.

Continue in AiiCloud

aii login
aii --remote-control --inference server

Open the printed AiiCloud link to continue the same conversation and respond to tool approvals. The running Aii process also makes its declared workspaces available for new web conversations. It must remain running on your computer or VPS.

The link appears in terminal history after the welcome banner, followed by Type /remote to show this URL and status again. Run /remote at any time to retrieve the complete URL and remote-control status.

--remote-control controls browser access. --inference server uses your configured Aii Server, whether local or remote; --inference cloud uses AiiCloud inference. Signing in for remote control does not change your inference preference. Omit --inference to use your saved preference, or the original conversation's settings when resuming.

aii resume <full-id> --remote-control

Run this exact-ID command from the saved workspace on the computer holding the session to restore its context and AiiCloud conversation. To browse saved workspaces and conversations, see Saved Conversations.

/remote off disables remote control during a session; /remote on enables it again. Enabling control does not copy earlier private messages into AiiCloud. Cloud inference keeps its ordinary configured history independently of remote control.

Manage directories offered for new web conversations with aii cloud workspace list, add <path> or remove <label|path>, then restart the hosting Aii process to apply the change.

The pre-GA --remote, --local and aii cloud connect entry points have been removed. Use the single launcher above; the old spellings are not aliases.

Memory foundation (v0.26)

Save complete project facts or personal preferences, inspect what was recalled, and correct or forget them. Generated suggestions stay pending until you review their exact text and scope. Retrieval is local lexical search; it makes no ranking-model request. Conditions and exceptions are kept together.

Activation is explicit. Installing the update does not migrate or enable the new store. Stop other Aii processes, then use these commands in a local interactive session—even if you have no old memories:

/memory migrate bind-project
/memory migrate preview
/memory migrate confirm <preview-token>
/memory migrate activate <migration-id> --offline-confirm
/memory review

Use the token and migration ID printed by the preceding commands. Staging imports candidates without approving them; activation preserves inventoried originals in quarantine. The inventory covers your profile and current project. Activation disables legacy learned-memory readers and writers for the whole local home; other projects must be bound and staged separately. After activation, do not run older Aii versions against that home. -y and unattended modes cannot approve migration or candidates.

After activation:

/memory save --project "Use an isolated Git worktree under .worktrees for changes in this project."
/memory save --profile "Prefer concise progress reports."
/memory show <id>
/memory recall
/memory replace <id> "The complete corrected fact, including exceptions."
/memory forget <id>
/memory settings use off
/memory settings learn off

Use and Learn are independent; explicit saves still work with Learn off. /memory review shows candidate text, scope and hash before approval. /memory list, /memory use and /memory reload retain their authored-instruction meanings.

If a changed or revoked memory influenced the current conversation, inference pauses. /memory clean starts an empty continuation once local work has settled; it transfers no old transcript or summary. Bound remote sessions and ambiguous request outcomes require a fresh local session. Stateful server-managed sessions, remote Ask, and child delegation into a different project binding are refused under active foundation until their history/scope can be verified. Forgetting prevents future learned-memory use; it does not erase historical transcripts or undo external actions.

Storage and retrieval stay local, but selected memory can be sent through your configured inference provider. This follows Aii’s trusted-host model: it does not protect runtime files from a malicious unrestricted process running as your OS user. Paraphrase matching is limited in this lexical baseline.

Project Markdown recall (v0.26.7)

Aii can discover existing notes in the current project’s ~/.aii/projects/<project-key>/memory/ folder and read complete relevant notes before acting. Project notes can describe preferences, corrections and exceptions, such as using .worktrees for code changes while allowing documentation-only edits on the current branch. The agent uses the current user request together with those notes; a fresh explicit instruction can override a saved preference for that run.

Discovery sends bounded private filenames and short cues to the configured task provider. Complete selected notes are delivered through registered file reads, with per-turn limits and checks for changed or revoked memory. Existing files are not rewritten during recall, and reviewed-save controls remain in place. Per-command working directories are validated and honored without changing the project’s identity.

Complete-note delivery allows up to 32 KiB conservative units, eight complete reads and sixteen attempts per turn; exact serialized overhead counts. When capacity runs out, further recall closes while agents and subagents continue independent work. Aii reports notes it could not read and asks for clarification before actions dependent on unread instructions. Capacity alone does not impose a blanket edit lock. Actual memory revision, identity or access changes still hold execution until context is refreshed.

Conversational project memory maintenance (v0.26.8)

In an attended local interactive session, you can ask Aii to correct or forget a project memory in ordinary language. The agent discovers relevant notes and reads a complete note before proposing one replacement or deletion. For example: “Change the worktree preference: documentation-only changes may use the current branch.” Existing matching memories should be reused, and conflicting notes should be clarified before changing them.

Aii shows the complete current note and proposed replacement or deletion in a local review, with No selected by default. Approval applies once to that exact revision. A successful change ends the old inference turn and offers a clean continuation after local work has settled. The fresh continuation carries no old conversation, tasks or queued input; restate your next task. If storage verification is uncertain, inspect the note before continuing. Unattended sessions and subagents cannot approve these changes.

To roll back after activation, stop Aii, preserve the new memory authority and its revocations, and run the older CLI only with a separate clean configuration home and learned memory disabled. Do not restore quarantined files into discovery paths or resume old conversations into inference on the downgrade.

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.

Install details

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 login
aii --inference cloud "what can you do?"

Sign in with Google or GitHub and your first answer lands in seconds — free on AiiCloud (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 --inference server "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.

Accounts and subscriptions

aii login                      # Sign into Aii Cloud
aii connect                    # Choose ChatGPT or Grok
aii connect chatgpt             # Connect a ChatGPT subscription
aii connect grok                # Connect a Grok subscription
aii disconnect grok             # Remove only the Grok subscription connection
aii connections                # Inspect local connection state
aii connections --json         # Structured local inventory

If a subscription connection is already saved, connecting asks Reconnect? [y/N] before opening authentication. Declining keeps your connection and model. Connecting asks whether to make the service your local default. Accept to choose an available model; decline to keep the current model. Your inference route stays separate. aii cloud login remains a Cloud sign-in alias.

For server inference, connected subscriptions take priority over API keys. Intentional disconnect permits your configured API-key access; a failed connected subscription requires explicit API-billing consent before paid dispatch. Credential and model availability remain provider-dependent. Cloud inference has its own routing and billing.

Old ChatGPT/Grok aii login --provider ... actions now show the replacement command without executing. Legacy status/about and GLM plan-key management remain available. Slack, Gemini and Claude subscription connections are not offered.

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 with four modes — Ask (the default: asks before edits and commands), Accept edits (edits run, commands still ask), Read-only (reads and searches, changes are refused) and Auto (nothing asks first, not limited to the workspace; secrets stay closed). /permissions shows and sets them, and Shift+Tab cycles them.

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 | | /permissions [mode] | See and set what Aii may do: mode, the repo's deny rules, session grants (revoke), recent refusals, writable folders. /permissions ask\|accept-edits\|read-only\|auto switches in one step | | /auto | Switch to Auto, or back to Ask | | /read-only | Switch to Read-only (reads and searches; changes are refused). /permissions ask leaves it; /plan toggles it | | /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 | In Ask and Accept edits, writes outside your workspace need your approval, and loops and goal turns started from them run in Auto · workspace. Aii Server sessions and turns steered from your phone or the Portal always keep the fence. Auto lifts it for your own turns, loops and goal turns. Paths are resolved through realpath, so .. and symlink escapes are caught; sensitive paths (~/.aii secrets, keychains) stay refused in every mode | | Permission model | Four modes (Ask, Accept edits, Read-only, Auto) set with /permissions or Shift+Tab; grants are scoped (per path / per session) and revocable; secrets and credential stores are refused in every mode; permissions.default_mode in ~/.aii/config.yaml sets where new sessions start | | 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 | | Plain text + Enter | Type while the agent works; it reads your message at its next step | | /steer <text> | Send a message the agent reads at its next step, on any model | | /queue <text> | Add a message to the next iteration instead; queued text is used one message per iteration | | /steering | Show whether typed text steers by default; /steering on, off or auto changes it |

A canceled or exhausted loop is resumable: /loop list shows saved loops, /loop resume <id> continues one with its remaining limits. A loop or goal turn runs in Auto · workspace (no prompts, writes stay inside the workspace) only while it runs, unless you started it in Auto: if Aii is stopped or killed mid-loop, the saved session keeps the permission mode you had before the loop, so aii resume never comes back in auto on its own. The status bar tracks iterations, tokens, cost, and pause state in real time.

Work survives a crash. A loop, a goal, or a session that starts agents keeps a work log in Aii's private store. After aii resume <id> or /loop resume <id>, Aii marks what was interrupted, brings back your task list (labelled as restored), re-checks each agent's worktree, and tells the model which agents it may continue with TaskContinue. /tasks lists past agents; /tasks unlock <id> clears a lock left by a process that no longer runs.

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, or not limited to the workspace if you are in Auto; 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

Since v0.24.1, installing a persona shows what it will actually activate — soul, skills, hook commands, MCP servers, instructions and theme — and asks before writing anything. The counts describe what activation resolves, including surfaces the tree carries but persona.json never declares. In scripts, pass --trust-source.

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. Since v0.24, --yes does not authorise installing third-party code — in scripts, pass --trust-source to confirm you trust the source. Create your own skills in .aii/skills/<name>/SKILL.md with YAML frontmatter. Skills in the cross-tool ~/.agents/skills/ directory are shown once before their first run, since other tools can write there.

Project skills are also discovered in .agents/skills/<name>/SKILL.md. Both project skill roots require first-use content approval and are disabled by --no-project-config. Run /skill reload after adding or editing skills.

For matching names, priority is: project commands → project .aii/skills/ → project .agents/skills/ → user ~/.aii/skills/ → active persona → plugin → shared ~/.agents/skills/ → built-in → remote. User skills override persona and plugin defaults. Project commands conflicting with protected built-in, persona, plugin, shared or remote skills are ignored; explicit source/plugin IDs remain available.

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.

Saved Conversations

Run aii resume from any folder to browse conversations saved on this computer, including sessions controlled through AiiCloud. The picker starts in All workspaces; Current limits it to the folder where you launched Aii. Type to search by first message, full session ID or workspace path.

Choose a workspace, press → or Enter to open its Sessions pane, then use ↑/↓ and Enter to resume a conversation. The active pane has a highlighted selection, and the selected full workspace path and session ID appear below the lists. On narrow terminals, the panes stack vertically.

| Key | Picker action | | --- | --- | | ↑ / ↓ | Move through folders or sessions in the active pane | | → or Enter in Workspaces | Open the selected workspace's sessions | | Enter in Sessions | Validate and resume the selected conversation | | ← in Sessions | Return to Workspaces | | Tab / Shift+Tab | Cycle focus through Workspaces, Sessions and Scope | | ← / → with Scope focused | Select All / Current, then return to Workspaces | | Esc | Return to Workspaces, or cancel from Workspaces | | Ctrl+C | Exit the picker |

Selecting a session rechecks its saved state and folder before launch, then switches only the Aii process into the saved folder. Your parent shell stays in its launch folder. Running, unavailable or recovery-required sessions explain why they cannot resume. Resume requires an intact, safely stopped session; interrupted work with an uncertain outcome is not automatically replayed.

For an exact session or a script, use the full ID. Exact-ID commands still require you to run from the saved workspace. The picker requires an interactive terminal; aii sessions list works offline and shows full IDs, workspaces, inference backends and recovery status without displaying prompts.

aii resume                         # Browse workspaces, then conversations (terminal only)
aii sessions list                  # Browse saved conversations on this computer
aii sessions info <full-id>        # Check status and resume instructions
aii resume <full-id>               # Run from the saved workspace
aii resume <full-id> --remote-control  # Enable control from AiiCloud

After a saved interactive session ends cleanly with /exit or Ctrl+D, the summary's Resume section includes the full resume command and picker label. Commands too long for the frame remain complete below it. Ctrl+C leaves plain resume guidance. If the latest save is unconfirmed or needs recovery, the guidance points to session details instead.

Inside a conversation, /sessions and /sessions info <full-id> show the same saved catalog. An open session must finish or close before another process can resume it. Hosted conversations continue in AiiCloud with their computer connected; unresolved execution requires recovery before resuming.

For conversations managed by the separate Aii Server Session API, use aii sessions server list or aii sessions server resume <id>. These commands use your configured Aii Server regardless of your inference preference.

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.

Usage analytics

Usage analytics is not active in this build. Telemetry-capable releases enable limited analytics by default for eligible use after showing a notice. Older releases do not upload historical usage. Signals describe launches, setup and request outcomes using random pseudonymous identifiers and broad product metadata; they exclude prompts, responses, files, command arguments, API keys and access tokens.

aii telemetry status
aii telemetry off
aii telemetry on
AII_TELEMETRY=off aii

Environment OFF overrides the saved preference and sends nothing. The OFF command saves your choice before new usage requests and may attempt one minimal disable-action receipt for a previously enabled installation. Repeating OFF sends nothing. Previously transmitted requests cannot be recalled and may still arrive. Analytics failures are silent and do not prevent CLI work. Recognized automation and initially Windows are excluded; unavailable safety controls or an undelivered notice also suppress collection.

See the Privacy Policy for exact data, receipt and retention details, and the Terms. A release default is distinguished from an explicit ON preference.

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 --remote-control | Enable AiiCloud continuation and new web conversations | | aii resume | Browse All/Current workspaces and resume in the selected session's folder | | aii resume <session-id> | Restore an exact saved conversation in its original workspace | | aii cloud <action> | AiiCloud sign-in, status and workspace management | | 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) | | --inference cloud\|server | Select inference for this invocation; independent of remote control | | --remote-control | Enable AiiCloud access to an interactive conversation and host new web conversations | | --auto | Start in Auto: nothing asks first and writes are not limited to the workspace (secrets and project deny rules still apply). With aii loop it keeps the workspace fence | | --dangerously-skip-permissions, --yolo | Start in Auto, on every lane including aii loop | | -y, --yes | Auto-confirm shell prompts (does not authorise installs — see --trust-source) | | --trust-source | Authorise installing third-party code (skills, plugins, personas) non-interactively | | -c, --continue-chat <id> | Deprecated — no effect. Use --continue <id> | | -n, --new-chat | Deprecated — no effect. Use /new in-session | | -i, --interactive | Force agent mode (already the default with no query; with a query it is still a one-shot run) | | --offline | Skip MCP servers. Web tools stay available — drop them with --exclude-tools WebSearch,WebFetch | | -D, --direct | Direct LLM mode (bypass server intent recognition) | | --no-colors | Disable colors (one-shot + command output; the interactive agent UI is unaffected) | | --no-streaming | Disable streaming output | | --show-tokens | Deprecated — no effect. Use -v for a token/cost line | | --show-cost | Deprecated — no effect. Use -v for a token/cost line | | -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 | | --reconnect-window <secs> | One-shot runs: retry dropped connections for up to N seconds (default 0 = fail fast; env twin AII_RECONNECT_WINDOW) |

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 ship with Aii's documentation — 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).

Connection drops

Each execution lane has a deliberate, documented answer to "the network dropped mid-turn":

| Lane | Transport-failure behavior | | --- | --- | | Interactive session | 60s reconnect window — Esc to stop, continue resumes the same turn | | Auto / goal (in-session) | retries until success (Ctrl+C exits) | | Loop (aii loop, /loop) | 10 transient retries per iteration + a circuit breaker | | One-shot / scripts | fail fast by default; opt into a bounded window with --reconnect-window <secs> or AII_RECONNECT_WINDOW | | Cloud dispatch (web-originated) | deliberately no retry — a re-run would re-feed the conversation mirror |

# Ride out a wifi handoff in an unattended one-shot (retries transport drops
# for up to 60s; permanent errors still fail instantly; chatter goes to stderr):
aii "run the full test suite and summarize failures" --reconnect-window 60

Only transport failures retry — provider/server errors classified permanent exit immediately, window or not. Retry chatter is stderr-only, so --bare/--output-format stdout stays pipe-clean; with --output-format json, a multi-attempt run adds an attempts field and tokens/cost report the completed turn's server totals (the session trace's usage events carry the full spend record). With --bare, an active window buffers stdout and writes the result once on completion (live token streaming resumes when the window is 0/off) — so a dead attempt's partial output never duplicates into RESULT=$(…). Exit code on an exhausted window stays 1.

Fetched web sources

WebFetch retains the complete extracted Markdown temporarily in your runtime configuration directory under web-artifacts (normally ~/.aii/web-artifacts). The agent keeps compact references in conversation history and can reread the stored source for follow-up questions. Tool rows distinguish network fetches and local stored reads. Sources expire after 24 hours or may be evicted earlier by storage limits.

Agent output budgets default to the selected model’s capability, subject to remaining context estimates, provider and account limits. Set a lower ceiling with aii config set llm.max_output_tokens 32768; restore automatic selection with aii config set llm.max_output_tokens auto. Unknown models use an 8,192-token fallback. New servers report the effective budget; ChatGPT subscription caps are advisory because that transport has no native output-limit parameter. Older servers remain usable.

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 | | File names in tool rows aren't clickable | Links appear only where they work: in the native screen (AII_MANAGED_SCREEN=native), and only in a terminal known to support OSC 8 links (iTerm2, WezTerm, VS Code, Ghostty, Hyper, Windows Terminal, kitty, Alacritty, foot, GNOME Terminal and other VTE terminals); never inside tmux/screen or over SSH. FORCE_HYPERLINK=1 turns them on for another capable terminal; FORCE_HYPERLINK=0 turns them off |

Links

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

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