Reference

Install

Homebrew

brew install wess/packages/ainz

Verified installer

curl --proto '=https' --tlsv1.2 -LsSf \
  https://raw.githubusercontent.com/wess/ainz/main/install.sh | sh

Cargo

cargo install --git https://github.com/wess/ainz --tag v0.10.3 --locked

Release archives are available for Apple Silicon macOS, and x86_64 and arm64 Linux.

To build the current checkout, run cargo install --path . --locked --force from its root. Use command -v ainz and ainz --version to check which executable is on your path, then restart Ainz. Theme and header files are separate from the executable; older releases may not include the commands documented here.

Providers and models

Run ainz without a configured model to enter setup, or use /config later. The same operations are scriptable:

ainz providers list
ainz providers add ollama --preset ollama
ainz models list ollama --refresh
ainz providers use ollama qwen3:8b

ainz providers add litellm --preset lite-llm --api-key-env LITELLM_API_KEY
ainz models list litellm --refresh

HTTP providers use Ainz's tool loop. The LiteLLM preset points at a local proxy on port 4000, reads its key from an environment variable, and lists the models the proxy serves, so one profile covers every provider behind it. Codex and Claude Code presets launch their installed, authenticated CLIs headlessly and return their final response as an Ainz turn. Permission mode is carried into those runs. Setup asks an HTTP provider for its own /models rather than expecting a name typed from memory, and ainz models list NAME --refresh replaces a stored list the same way. A connection failure, a 408, a 429, or a 5xx status is retried with exponential backoff, a Retry-After header honoured when it names a plain number of seconds; a retry never happens once a response has started streaming text. provider_retries sets how many, three by default.

Tools

Each one's arguments, what it returns, and the risk it counts as are in the tool reference.

The tool loop starts with a fixed set of built-ins, extended by MCP servers, skills, and plugins covered further down this page.

fetch reads the page or file at a URL as text, stripping markup from HTML; it will not reach localhost, loopback, or a private address range, since a coding agent that can reach the machine's own network is a way into everything on it, cloud metadata services included. todo holds short step texts with a pending, doing, or done state; nothing in it survives the session.

CLI commands

Global options include --workspace, --model, --endpoint, --provider, --mcp-config, --permissions, --yeet, and --initial-prompt.

Buffer and completion

Ainz uses an IRC-style buffer: <you> message and <Ainz> reply share a line, with wrapped text aligned under the message. Headings, lists, tables, links, and code render as terminal Markdown. The right-hand roster switches between agent transcripts; the top row shows the selected agent's task and current tool.

The activity row distinguishes Working, Responding, Running tools, and Waiting for approval. A quiet provider is still active while it says Working. Completed, Cancelled, or Failed remains above the prompt until the next run and leaves a marker in the transcript. Completion waits for end hooks. Cancellation covers providers, compaction, approvals, tools, and hooks; it does not undo work already completed.

Reading earlier output holds your position; Ctrl+End returns to the latest output. Steering submitted during a run waits for a safe conversation boundary, up to 32 messages of 64 KiB each. Rejected steering reports why and keeps the draft. See the interface guide and reliability notes.

Headers and Masthead Studio

/header mascot
/header mascotascii
/headers
/header myainz

mascot selects the mascot at a size suited to the terminal; mascotascii uses plain ASCII. The old ainz and ainzascii names remain aliases. A named selection previews immediately and remembers the choice without clearing your conversation. Press any key to return. /header builtin chooses from bundled artwork; /header random includes custom files.

In Masthead Studio, choose the mascot, a wordmark, a blank canvas, or an existing half-block ANSI file. Draw with the tools and palette, undo mistakes, and preview the result. Name it, choose a platform and installation scope, copy the install command into your shell, then run the displayed /header NAME inside Ainz. The command writes one file and refuses to overwrite another. The studio keeps a local draft and also supports download and copy.

Manual files go in ~/Library/Application Support/ainz/headers/ on macOS, $XDG_CONFIG_HOME/ainz/headers/ (default ~/.config/ainz/headers/) on Linux, or .ainz/headers/ in a project or ancestor. The nearest project file wins. /headers and /header NAME discover new files without restarting. ANSI SGR colors and plain text are supported; cursor movement and other terminal controls are rejected. Limits are 128 KiB, 240 columns, and 80 rows. See the full header guide.

Themes and Theme Designer

/themes
/theme mytheme
/theme default

The Theme Designer previews a real palette against an IRC-style buffer and right-hand roster. Choose Classic, Nazarick, or Paper, tune each color, then copy the install command and run /theme NAME inside Ainz. You can download or reopen the TOML file, restore colors with Undo, and see contrast ratios before installing. Artwork keeps its own colors.

Theme files go in the user configuration directory's themes/ folder or a project's .ainz/themes/. The nearest project definition wins. Files are regular .toml files, at most 16 KiB, with a [colors] table:

[colors]
background = "#14121b"
text = "#e3decd"
muted = "#9e93af"
accent = "#d5b879"
bar = "#492958"
bar_text = "#f5ead4"
border = "#755087"

Additional roles are success, info, warning, error, special, and bright. Values are #RRGGBB; background also accepts "default". Omitted roles use built-in colors. Unknown roles or tables and invalid colors reject the file; /themes reports errors.

/theme NAME applies, reloads, and remembers a palette immediately. /theme default restores the built-in colors. Themes color the chat interface and its dialogs; setup screens and message formats keep their existing layout. Already-flushed inline scrollback keeps its earlier colors. See the full theme guide.

Embed Ainz or its Markdown renderer

The Rust core runs without a terminal or background service. Your host supplies the provider, tools, workspace, events, approvals, and session. Constructing an agent does not discover extensions, read credentials, or save state. Disable default features to omit the CLI and optional plugin runtimes:

[dependencies]
ainz = { path = "../ainz", default-features = false }

cli, lua, and wasm can be enabled independently. Native Tokio hosts are supported; browser WebAssembly and language bindings are not provided. The separate termweave crate renders Markdown to ANSI or Ratatui. Both libraries are currently used from source. See the embedding contract and examples.

TUI controls

The prompt supports shell-style editing and history.

Slash commands: /help, /settings, /config, /permissions [ask|auto|read-only], /rules [clear], /agents, /agent N, /status, /usage, /history, /checkout NODE, /image PATH PROMPT, /sessions, /memory [QUERY], /remember TEXT, /synapse, /import, /yeet, /skills, /prompts, /plugins, /mcp, /headers, /header NAME, /themes, /theme NAME, /vim, /inline, /new, /cancel, /exit, plus any discovered prompt template.

/rules lists the standing rules a session has written by pressing a at an approval prompt; /rules clear forgets them. /vim turns on modal editing in the prompt. /inline draws the prompt at the bottom of the terminal's own scroll instead of taking the whole screen, so finished output stays in the scrollback the terminal already keeps, at the cost of the roster; it applies at the next launch.

Configuration

Configuration is stored in the platform user config directory. Environment variables and flags override it.

endpoint = "http://127.0.0.1:11434/v1"
model = "qwen3:8b"
api_key_env = "AINZ_API_KEY"
provider_retries = 3
permissions = "ask"
context_tokens = 128000
compact_at_tokens = 96000
preserve_messages = 8

[rules]
allow = ["read", "shell(git *)"]
deny = ["shell(rm *)"]

[ui]
header = "mascot"
theme = "default"
roster_visible = true
vim = false
inline = false
bell = true

[memory]
backend = "local"
recall_on_start = true
remember_on_compact = true
teach = false

[synapse]
enabled = false
mesh = false

[hooks]
post_tool = [{ command = ["cargo", "fmt"], matcher = "edit" }]

/settings edits this list in place — provider and model, permissions, memory, Synapse, the agent mesh, the roster, and header art — with a line beside each saying what it changes. Named providers live under [providers.NAME] with provider selecting the active one, and the [ui] table remembers the roster, header, theme, vim, inline, and bell choices. Select themes with /theme NAME. [rules] holds the standing allow and deny lists a session writes by pressing a at a prompt, deny always winning; [hooks] is written by hand. Environment variables are AINZ_MODEL, AINZ_ENDPOINT, AINZ_PROVIDER, AINZ_API_KEY, AINZ_MEMORY, AINZ_SYNAPSE, AINZ_CONFIG, and AINZ_MCP_PROFILE. Use a provider's api_key_env field to keep the secret itself outside configuration files.

Hooks

A session crosses a few fixed points nothing else can see: before its first turn (session_start), before and after every tool call (pre_tool, post_tool), and when a run ends (session_end). A hook is a command run at one of those, given the event as JSON on stdin. pre_tool is the one event with a vote: a hook that exits non-zero blocks the call, and its stderr becomes the error the model reads; every other event is advisory. The full guide is in the repository: hooks.

The activity row stays active until end hooks finish. Cancellation interrupts every hook phase and skips remaining hooks. Hook output is drained with bounded retention; long-running child processes are cleaned up on cancellation. Tool results completed before a hook fails remain in the conversation.

Memory and self-improvement

A session that forgets everything at the end re-derives the same things next week. Memory is on by default and local: Markdown files under the data directory, private to this machine, scoped to the workspace or global. The newest are recalled into the system prompt when a session opens, a memory tool recalls and stores more, and when the transcript is compacted the session is asked to write down anything durable it has not stored yet — the one moment where not having written something down costs you immediately.

ainz memory add the staging database is named orbit
ainz memory search staging
ainz sessions --search "certificate error"

A sessions tool searches earlier transcripts by term and returns ids and excerpts, so a problem solved last week is recoverable without having remembered it in advance. With memory.teach on, a learn tool lets a session propose a skill from a procedure it worked out and correct one that turned out wrong; a proposal waits in skills/proposed/, which discovery does not read, until ainz skills approve NAME. The full guide is in the repository: memory.

Import

Skills, commands, and instruction files are read where they already live, so most of a machine needs no import step. Tool servers are the exception: MCP configuration is per-tool, and Ainz starts servers only from its own profile.

ainz import
ainz import --all
ainz import github

/import opens the same list in a session as a checklist. It reads Claude Code, Claude Desktop, Codex, Cursor, Windsurf, Gemini CLI, and the workspace's own .mcp.json or .vscode/mcp.json, plus skills from the Synapse library, Codex, and pi. Anything Ainz already reads is marked already available and left unticked. An entry holding a token or password inline is marked as carrying credentials, because importing copies the secret into the Ainz profile; move it to header_env afterwards to name an environment variable instead. Imported servers are never required, so one that will not start costs its tools and not the session. The full guide is in the repository: import.

Extensions

MCP

ainz mcp add NAME --required -- COMMAND ARG…
ainz mcp

Stdio servers are registered from the CLI; Streamable HTTP servers are added to the profile file in the user config directory. Tool schemas stay out of model context until searched and selected.

Skills and commands

Ainz reads the layouts other harnesses already use, so an existing project needs no import step. AGENTS.md and CLAUDE.md are both read at every level from the filesystem root down to the workspace, nearest last. Skills are discovered from .claude/skills/, .agents/skills/, skills/ and .ainz/skills/ beside the workspace, plus ~/.claude/skills/ and the config directory; their names and descriptions occupy the prompt and one skill tool loads the text on demand, including any scripts or reference files bundled beside it. Prompt templates come from .claude/commands/ and .ainz/prompts/, namespace by subdirectory as /api:audit, and expand $ARGUMENTS and $1 as well as {{args}} and {{1}}.

Plugins

Ainz discovers native manifests and portable Agent Plugins 1.0 packages from user and workspace plugin roots. Discovery never executes a plugin; approve its content hash first:

ainz plugins list
ainz plugins approve NAME
ainz plugins revoke NAME

See the repository guides for plugin manifests, custom headers (paint one in the masthead studio), MCP, and custom providers.

Synapse

Synapse keeps memory, one skill library, and an agent mesh on your machine, shared with the other tools you use. Ainz can use all three, and runs the same without it: the setting has to be on and the binary has to be installed.

ainz synapse enable
ainz memory backend synapse
ainz synapse mesh on

Turning it on registers synapse mcp for the session, appends Synapse's guidance and your SOUL.md to the system prompt, and points memory and taught skills at Synapse instead of local files, so a decision recorded here reaches a later session in Claude Code or Codex. With the mesh on, the session and every subagent register under their own names, message each other, and report status where you can watch them. First launch offers it once when an install is found, and takes no for an answer.

ainz mcp add synapse --required -- /path/to/synapse mcp

Registering the server by hand still works and gives the tools without the rest. Synapse can also pass --mcp-config FILE when it launches Ainz; harness integration goes through JSON-RPC mode. The full guide is in the repository: Synapse.

State and project paths

Security model

Permission modes are ask, auto, and read_only. JSON mode never opens an approval prompt, so noninteractive mutation requires explicit --permissions auto. --yeet, and /yeet inside a session, allows every tool call without asking and loads every plugin on disk whether or not it was approved, for that run only; neither the configuration file nor the plugin grants are written, and the status line says so while it is on, and choosing a permission mode ends it early. Component plugins receive bounded resources and capability-checked imports. Process plugins are native programs and cannot be sandboxed by a manifest; treat them as trusted code. Plugin approval is pinned to the manifest, the plugin directory, and the runtime artifact, which is rechecked when it runs, so a change returns the plugin to pending.

What may run without asking, and the standing rules that keep an answer, are in the permissions reference.

Report vulnerabilities privately through the repository's security advisory form.