# Aivo > Aivo is a command-line tool that lets you run almost any model inside your favorite coding agent — Claude Code, Codex, Gemini CLI, OpenCode, Amp, Pi, and more. It sits between the agent and the provider and converts protocols on the fly, so any agent can talk to any provider. Coding agents speak Anthropic, OpenAI, or Gemini protocols. Providers speak one of the same three. Aivo detects both ends and converts request and response shape on the fly — tools, streaming, and reasoning blocks included. There is no per-pair shim, so any new agent that speaks one of the three protocols works with every provider that speaks any of them. ## Install - Bash: `curl -fsSL https://getaivo.dev/install.sh | bash` - PowerShell: `irm https://getaivo.dev/install.ps1 | iex` - Homebrew: `brew install yuanchuan/tap/aivo` - npm: `npm install -g @yuanchuan/aivo` ## Quick start ``` aivo claude # or codex, gemini, opencode, amp, pi, omp, copilot, grok ``` Add a provider key with `aivo keys add`, then launch any agent. No key? The first run can use the built-in starter pool (see below). ## Bring your own keys Add API keys from any provider you trust. Keys are AES-256-GCM encrypted at rest in `~/.config/aivo/`, with the key derived from your machine. Requests go straight from your machine to the provider. ``` aivo keys add # interactive picker (most providers) aivo keys add --base-url --key sk-xxx # non-interactive aivo keys # list saved keys aivo keys use [name] # activate a key aivo keys cat # print saved data of a key aivo keys edit # edit a saved key aivo keys ping # health-check ``` The picker covers OpenRouter, Vercel AI Gateway, Fireworks, MiniMax, DeepSeek, Cloudflare, Google AI Studio, Kilo Gateway, Amazon Bedrock, Cursor, OpenCode Go, OAuth login for ChatGPT/Claude/Gemini subscriptions, GitHub Copilot, and local servers (Ollama, LM Studio, llama.cpp). A few notes: - **OAuth login (ChatGPT/Claude/Gemini subscriptions)** only works inside its own agent (`aivo codex`, `aivo claude`, `aivo gemini`) — each subscription's terms restrict use to its own agent, and aivo respects that. - **Cursor subscription** (experimental) includes the Cursor SDK, so it works across agents like a BYOK key. `aivo pi -m composer-2.5` works after adding it. - **GitHub Copilot** subscriptions can be added as a provider. Be aware Copilot charges by request count, not token usage. - **Ollama / LM Studio / llama.cpp** are added as OpenAI-compatible endpoints. If an Ollama model isn't present, aivo asks to pull it before use. ### Export & import Move keys between machines through a single password-encrypted file. OAuth logins and GitHub Copilot are skipped by default — they're machine-bound. ``` aivo keys export ~/keys.bak aivo keys import ~/keys.bak aivo keys import https://example.com/keys.bak aivo keys export ~/keys.bak --password-stdin <<< "my secret" ``` ## Run a coding agent ``` aivo claude aivo codex aivo codex-app # Codex desktop app (macOS only) aivo gemini aivo opencode aivo amp # plugin: aivo plugins install github:yuanchuan/aivo-amp aivo pi aivo omp # plugin: aivo plugins install github:yuanchuan/aivo-omp aivo copilot # plugin: aivo plugins install github:yuanchuan/aivo-copilot aivo grok # plugin: aivo plugins install github:yuanchuan/aivo-grok # pass-through args aivo claude --dangerously-skip-permissions aivo claude --resume # pick key and model aivo claude -k openrouter aivo claude -m moonshotai/kimi-k2.5 aivo claude -k # open key picker aivo claude -m # open model picker # Claude Code only: 1M / 2M context window aivo claude -m deepseek-v4-pro --1m aivo claude -m grok-4.20-reasoning --2m # debug HTTP traffic aivo claude --debug aivo claude --debug=/tmp/aivo-http.jsonl # re-launch last selection aivo run ``` ### Per-slot models (Claude Code) Claude Code runs multiple models in a single session — `haiku`/`sonnet`/`opus` slots plus reasoning and subagent overrides. Pin each slot to a different model, or pass a slot flag without a value to open the picker. ``` aivo claude --sonnet-model deepseek-v4-pro --haiku-model deepseek-v4-flash aivo claude --reasoning-model gpt-5.4 --subagent-model claude-haiku-4-5 aivo claude --opus-model # open the picker for one slot ``` ### Amp (plugin) Amp support ships as a separate plugin. Install it once, then it works like any other agent. ``` aivo plugins install github:yuanchuan/aivo-amp ``` Amp routes between `rush`, `smart`, `deep`, and `large` modes. ``` aivo amp --smart-model claude-sonnet-4.6 --rush-model claude-haiku-4-5 aivo amp --deep-model gpt-5.4-thinking --large-model deepseek-v4-pro aivo amp --mode deep aivo amp --mode # open the mode picker ``` ### More plugins (omp, GitHub Copilot, Grok CLI) These ship as separate plugins too. Install once, then each runs like any other agent. ``` aivo plugins install github:yuanchuan/aivo-omp # then: aivo omp aivo plugins install github:yuanchuan/aivo-copilot # then: aivo copilot aivo plugins install github:yuanchuan/aivo-grok # then: aivo grok ``` ### Pi transform mode Because Pi supports multiple upstream protocols, aivo by default hands it the URL and API type so it talks to the provider directly. Use `--transform` to put aivo's local router in the middle and normalize the stream. ``` aivo pi --transform -k openrouter ``` ### Launch aliases Pin a coding agent and its usual flags under one name, then launch the whole thing with `aivo `. Inline flags at run time override the saved ones. ``` aivo alias work claude -k openrouter \ --opus-model deepseek/deepseek-v4-pro \ --sonnet-model deepseek/deepseek-v4-flash \ --1m aivo work # run it aivo work -k personal # inline flags override saved ones ``` ## Models and aliases ``` aivo models # list models for active provider aivo models -k openrouter aivo models -s claude # search by name aivo models --refresh # force-refresh cached list aivo models --json | jq # raw upstream list for scripts # model aliases (short names for long model IDs) aivo alias fast=claude-haiku-4-5 aivo alias mimo xiaomi/mimo-v2-pro aivo alias # list aivo alias rm fast # remove ``` ## Hugging Face Run any open-weight GGUF directly from a Hugging Face repo. The first reference downloads the file to `~/.config/aivo/cache/huggingface` and serves it through a bundled `llama-server`. Subsequent runs reuse the cached file. The `hf:` prefix and full `https://huggingface.co/…` URLs are accepted anywhere a model name works. ``` aivo hf:Qwen/Qwen2.5-0.5B-Instruct-GGUF aivo https://huggingface.co/allenai/Olmo-3-1025-7B # pin a quant (Q5_K_M, Q4_K_M, …); aivo prompts on first download otherwise aivo code hf:bartowski/Llama-3.2-3B-Instruct-GGUF:Q5_K_M aivo claude -m hf:bartowski/Llama-3.2-3B-Instruct-GGUF:Q4_K_M # tune the bundled llama-server (env vars, all optional) AIVO_LLAMA_CTX=16384 # smaller context on a low-RAM machine AIVO_LLAMA_NGL=20 # GPU layers (AIVO_GPU=cpu to stay on CPU) AIVO_LLAMA_ARGS='--temp 0.1' # extra llama-server flags AIVO_LLAMA_MMPROJ=off # skip the vision projector AIVO_LLAMA_DRAFT=off # skip the draft model # mix remote + local in one session aivo claude \ --opus-model claude-opus-4.7 \ --sonnet-model hf:Qwen/Qwen2.5-0.5B-Instruct-GGUF # re-open from the local cache (picker) aivo code hf: aivo claude hf: # manage the cache aivo hf # list cached repos aivo hf --verbose # show every downloaded quant aivo hf pull hf:Qwen/Qwen2.5-0.5B-Instruct-GGUF # pre-pull aivo hf rm --quant Q5_K_M # delete one quant aivo hf rm --all -y # delete a whole repo aivo hf clean -y # wipe the whole cache ``` ## Code `aivo code` is the built-in coding agent in your terminal — it reads and edits files and runs shell commands, each behind a permission prompt. It works with any model you've added, from a frontier API to a local GGUF. (`aivo chat` still works as an alias.) ``` aivo code # full-screen TUI aivo code -m gpt-5.4 aivo code -m # model picker aivo code -k # key + model pickers # resume a saved session (transcript, edits, and all) aivo code --resume aivo code --resume last # one-shot: plain reply, no tools aivo "pro tips for git" # shorthand for: aivo code -p "..." aivo -p "pro tips for git" -m gpt-5.4 aivo -p # type interactively, Ctrl-D to send # headless agent: run the full agent (tools + multi-step) on one prompt aivo code -e "add a --json flag to the export command" aivo code -e "fix the failing test" --output-format stream-json # shell pipelines (stdin appended as context, or used as the prompt) git diff | aivo -p "Write a commit message" cat error.log | aivo -p "Find the root cause" cat error.log | aivo -p # attach files / images (repeatable; or paste an image with Ctrl+V) aivo code --attach README.md aivo code --attach README.md --attach screenshot.png ``` Tools run inside an isolated workspace sandbox (macOS, and Linux via Landlock) that asks before reaching outside it. Inside the session, type `/help` for slash commands: change the model or reasoning effort mid-session, `/compact` the context, `/plan` before a big change, `/config` to toggle tools and web search, or prefix a line with `!` to run a shell command. ### Agent profiles A profile is a Markdown file: YAML frontmatter (`description`, optional `model`, optional `tools` allow-list) over a body that becomes a subagent's system prompt. Drop one in `.aivo/agents/.md` per project, or under `~/.config/aivo/agents` to reuse it everywhere. Existing `.claude/agents` files work as-is. Mid-session the agent delegates scoped tasks to a profile by name (chosen by its `description`) and folds the result back in. ## Serve Expose the active provider as a local OpenAI-compatible endpoint. Any tool that speaks the OpenAI API can use it. Model aliases are resolved at the server, so clients can post `{"model": "fast", ...}` and aivo rewrites it to the real upstream model. The alias list also shows up in `/v1/models`. ``` aivo serve aivo serve --port 8080 aivo serve --host 0.0.0.0 # failover: retry the next saved key on 429 / 5xx aivo serve --failover # logging aivo serve --log | jq . aivo serve --log /tmp/requests.jsonl # auth, CORS, timeout aivo serve --auth-token aivo serve --auth-token my-secret aivo serve --cors aivo serve --timeout 60 ``` Try it: ``` curl http://localhost:24860/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "hello"}]}' ``` ## Logs & stats One feed across aivo's own events (code, run, serve), native CLI sessions (claude, codex, gemini, pi, opencode), and amp threads — read from each tool's on-disk session files and aivo's local SQLite. Scoped to the current project by default. ``` # view aivo logs aivo logs --all # every project on this machine # filter aivo logs --by code -n 5 aivo logs --by claude --errors aivo logs --by native aivo logs --model glm-4.7 aivo logs -s "rate limit" aivo logs --since 24h aivo logs --json # share a session via tunneled viewer URL (server keeps no copy) aivo logs share aivo logs share 1335c631 aivo logs share --all aivo logs share --live --open aivo logs share --no-redact # usage stats — aggregates token counts across all supported tools aivo stats aivo stats claude aivo stats code aivo stats -n # raw numbers for scripts aivo stats -s openrouter aivo stats --since 7d aivo stats -a # show all models aivo stats -r # bypass cache ``` ## Starter models `aivo-starter` is a built-in provider for students and learners who want to try a coding agent without setting up a provider account. It's there to feel how aivo works before you bring your own key. - `aivo/starter` — DeepSeek V4 Flash, general-purpose default. - `poolside/laguna-s-2.1` — Poolside Laguna S 2.1, second-generation coding agent model in the S size class. The starter pool has a finite daily budget — intended for interactive coding-agent sessions. Not for automated scripts, batch jobs, benchmarks, third-party clients, or OpenClaw. For regular or automated use, add your own API key. ## Update `aivo update` detects whether you installed via Homebrew, npm, or the install script and updates accordingly. Failed updates roll back automatically. ``` aivo update aivo update --force # update even if installed via a package manager aivo update --rollback # restore the previous version from backup aivo update --sync-model-data # refresh model limits (from models.dev) without touching the binary ``` ## Privacy With your own provider keys, requests go straight from your machine to the provider — aivo runs no server in between and logs nothing. The starter pool and aivo-pro run through aivo's gateway, which records usage (the model, token counts, and a short snippet of recent input for abuse detection) to enforce limits and handle billing. Aivo doesn't sell your data or train on it. ## Links - Site: https://getaivo.dev - GitHub: https://github.com/yuanchuan/aivo