From zero to first run.

Install the binary

On macOS or Linux with Homebrew:

brew install wess/packages/ainz

Or with the verified installer:

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

The installer selects your architecture, verifies its SHA-256 checksum, and writes to ~/.local/bin. Set AINZ_INSTALL_DIR to choose another directory.

Open setup

ainz

With no model configured, Ainz opens setup inside the TUI. Pick from a list of endpoints, the credential environment variables already in your shell, and the coding agents already on the machine; models are pulled from the endpoint's own /models list rather than typed by hand. Save, and you can return at any time with /config.

Choose a provider

Ollama

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

LiteLLM proxy

ainz providers add litellm --preset lite-llm --api-key-env LITELLM_API_KEY
ainz models list litellm --refresh
ainz providers use litellm gpt-5.6-sol

Codex process

ainz providers add codex --preset codex --known-model gpt-5.6-sol
ainz providers use codex gpt-5.6-sol

Claude Code process

ainz providers add claude --preset claude-code --known-model sonnet
ainz providers use claude sonnet

Process providers use your existing authenticated CLI. Ainz does not need a separate Claude API key for the Claude Code preset.

Run a task

ainz ask "inspect this project and explain its architecture"

Or stay in the full-screen interface:

ainz

Type / for fuzzy command search. Ctrl+L toggles the right-hand agent roster; Ctrl+1 selects the main session, Ctrl+2..9 select subagents, and Ctrl+=/- cycle (or /agent N in terminals without the kitty keyboard protocol). A failed model request retries with backoff instead of losing the turn, and the status line shows what a turn cost when the provider reports it.

Edit the prompt

/inline
/vim

The prompt is a readline: Up and Down walk earlier prompts and come back to the line you were writing, word and line keys edit it, and Shift+Enter — or a trailing backslash — adds a newline. @ completes a path in the workspace, and Esc twice steps back to the last prompt and puts it in the line to change, taking the session from there. Ctrl+O expands what a tool returned in full, and the mouse and wheel select text and scroll. /inline draws the prompt in the terminal's own scroll instead of taking the whole screen, so finished output stays in the scrollback the terminal already keeps; /vim turns on modal editing.

Approve what runs

/rules

A permission prompt shows what a call would actually do — an edit as a diff, a command as the command — and takes three answers: y allows it once, n refuses, and a keeps the decision — the tool alone, or the tool with the first word of its command, so shell(git *) is a rule you can mean. /rules lists what has been kept, and /rules clear forgets it. A long command reports itself while it runs — the call in the transcript grows a line showing the last thing it wrote.

Resume and branch

ainz sessions
ainz resume
ainz resume SESSION_ID --at NODE_ID "try the smaller fix"
ainz sessions export SESSION_ID --out session.md

Sessions are tree-structured. Resuming at an earlier node creates another path without erasing what came after it. sessions export writes the active path as Markdown.

Bring what you already have

ainz import
ainz import --all

Skills, commands, and AGENTS.md are read where they already live. Tool servers are not, because every tool keeps its MCP configuration in its own file — so import lists what Claude Code, Codex, Cursor, and the rest have and copies over the ones you pick. /import is the same list as a checklist inside a session.

Let it remember

ainz memory add the staging database is named orbit
ainz memory list

Memory is on and local by default. What is stored for a workspace is recalled into the system prompt when a session opens, the session can write more with its memory tool, and it is asked to save anything durable before a long transcript is compacted. /settings changes any of it.

Hook into it

[hooks]
pre_tool = [{ command = ["./scripts/guard-writes.sh"], matcher = "write" }]

A hook is a command run at a point a session crosses: before its first turn, before and after every tool call, and when a run ends, taking the event as JSON on stdin. A pre_tool hook has a vote — a non-zero exit blocks the call and its stderr becomes the error the model reads.

Connect Synapse

ainz synapse enable
ainz memory backend synapse
ainz synapse mesh on

Synapse is optional and keeps memory, one skill library, and an agent mesh shared with your other tools; turning it on also loads your SOUL.md guidance and gives each subagent its own seat on the mesh. Registering the server by hand still works, and Ainz accepts an ephemeral MCP launch profile with --mcp-config, so Synapse can start it with a mesh-specific tool configuration.

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

Make it yours

/header mascot
/theme default

Open Masthead Studio to draw or extend a header, or Theme Designer to tune the chat palette. Both provide one install command for your platform and project scope. Paste it into your shell, then run the displayed /header NAME or /theme NAME inside Ainz. New files are discovered immediately; theme changes preserve artwork colors.

/headers and /themes list installed files and errors. See the header and theme guides for manual installation and sharing.