$

Aivo is a lightweight CLI for managing API keys and launching coding agents across providers. It automatically transforms protocols from one to another whenever necessary, so you can use DeepSeek, MiniMax, Kimi or locally running models in coding agents like Claude Code or Codex.

curl -fsSL https://getaivo.dev/install.sh | bash
brew install yuanchuan/tap/aivo
npm install -g @yuanchuan/aivo

After installation, you can try Claude Code. No login or API key required.

aivo claude

Aivo includes a FREE provider for everyone to get started and try things out.

Why This Tool

Getting API access to coding agents isn't straightforward for everyone. Payment methods, regional restrictions, complicated setup. Aivo tries to make it easier for more people to use better coding agents.

  • Free tier included. Get started without any API key at all. Try things out, then add your own provider when you're ready.
  • Use providers you already have. DeepSeek, MiniMax, Kimi, Zhipu, or any API endpoint. Aivo translates between protocols automatically.
  • Works with Ollama. Run models locally on your machine. No network needed.

Manage API Keys

To get the best experience, you should add your own API keys from providers you trust. You can maintain multiple keys from different providers, switch between them as needed. Aivo encrypts and securely stores your keys locally.

# list all saved keys aivo keys # interactively add a key aivo keys add # or quickly add a key with options aivo keys add --base-url https://openrouter.ai/api --key sk-xxx # activate a key to use aivo keys use aivo keys use mykey # print saved data of a key aivo keys cat # for more options aivo keys --help

GitHub Copilot

If you have a GitHub Copilot subscription, you can add it as a provider in aivo. (Be aware of the GitHub Copilot charges by request count, not by token usage)

aivo keys add copilot

Ollama

With aivo, you can easily connect to Ollama and use models from your local machine or its cloud service. If the model is not present, aivo asks to pull it first before use.

aivo keys add ollama # chat with ollama model aivo chat -m ministral-3:3b

Models & Aliases

Once you add a provider and set up the key, you can use the models command to see the available models the provider offers. Most providers provide the model list through API, so aivo fetches it on demand and caches it for later use.

aivo models aivo models --key openrouter # search by name aivo models -s sonnet # force refresh the cached list aivo models --refresh

Aliases

If a model name is too long, you can give it a short alias.

aivo alias fast=claude-haiku-4-5 aivo alias mimo xiaomi/mimo-v2-pro # use it aivo claude -m fast aivo chat -k vercel -m mimo # list and remove aivo alias aivo alias rm fast

Run Coding Agent

Launch an agent with the active provider key. All extra arguments are passed through to the underlying tool. The run keyword is optional — aivo claude is equivalent to aivo run claude.

aivo claude aivo codex aivo gemini aivo opencode aivo pi # all extra args pass through aivo claude --dangerously-skip-permissions aivo claude --resume 16354407-050e-4447-a068-4db222ff841

Pick a model

Override the model for one run. Omit the value to open the model picker.

aivo claude --model moonshotai/kimi-k2.5 aivo claude -m

Use a different key

Switch provider for just this launch, without changing your default.

aivo claude --key openrouter aivo claude --key copilot aivo claude -k

Dry run & env

Preview the resolved command and environment without launching. Or inject extra environment variables into the agent process.

aivo claude --dry-run aivo claude --env BASH_DEFAULT_TIMEOUT_MS=60000

Quick start

Without a tool name, aivo run remembers your last key and tool selection, so next time it skips the prompts and goes straight to launching.

aivo run

Interact with LLM

Talk to any model directly from your terminal. Full-screen TUI for conversations, or one-shot mode for quick answers and shell pipelines.

Full-screen TUI

Interactive chat in your terminal with streaming and markdown rendering. The selected model is remembered per saved key.

aivo chat aivo chat --model gpt-4o aivo chat -m claude-sonnet-4-5 aivo chat -m # opens model picker

One-shot prompts

Send a single prompt and exit. When -x has a message, piped stdin is appended as context. When -x has no message, the entire stdin becomes the prompt.

aivo -x "Summarize this repository" aivo -x # type interactively, Ctrl-D to send

Shell pipelines

Pipe anything into aivo. It reads stdin, adds your prompt, and sends it to the model.

git diff | aivo -x "Write a commit message" cat error.log | aivo -x "Find the root cause" cat error.log | aivo -x

Attach files

Send files alongside your prompt. Images work too.

aivo chat --attach README.md --attach screenshot.png

Use a different key

aivo chat --key openrouter aivo chat -k # opens key picker

Serve

Expose your active provider as a local OpenAI-compatible endpoint. Any tool that speaks the OpenAI API can use it — VS Code extensions, Cursor, Python scripts, anything.

Start the server

aivo serve aivo serve --port 8080 aivo serve --host 0.0.0.0

Failover

If a request hits a rate limit (429) or server error (5xx), aivo retries with the next saved key automatically.

aivo serve --failover

Logging

Log every request and response. Pipe to jq for readable output, or write to a file.

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 with curl

curl http://localhost:24860/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "hello"}]}'

Logs & Stats

Every request is logged to a local SQLite database — chat, agent launches, serve. Token counts, models, response times, errors. All queryable from the command line.

View logs

aivo logs

Filter and search

Narrow by source, tool, or text. --errors shows only failures.

aivo logs --source chat -n 5 aivo logs --tool claude --errors aivo logs "rate limit" aivo logs --json

Live watch

Tail logs in real time. New entries appear as they happen.

aivo logs --watch aivo logs --watch --jsonl aivo logs --watch --interval 2

Log details

aivo logs show 7m2q8k4v9cpr aivo logs path aivo logs status

Usage stats

Aggregates token counts from aivo chat, Claude Code, Codex, Gemini, OpenCode, and Pi by reading each tool's native data files.

aivo stats aivo stats claude aivo stats chat

Filter and format

# raw numbers for scripts aivo stats -n # filter by provider aivo stats -s openrouter # show all models aivo stats -a # bypass cache aivo stats -r

Example output

$ aivo stats ───────────────────────────────────────────────────── 948M tokens · 5.9B cached · 3.3K sessions · 52 models By tool sessions tokens codex 166 697M ████████████████████ claude 2.8K 231M ██████▋ opencode 145 9.8M ▎ chat 63 8.0M ▎ gemini 139 2.9M ▏ pi 32 113K ▏ By model tokens gpt-5.4 651M ████████████████████ claude-sonnet-4.6 74M ██▎ minimax-m2.5 63M ██ gpt-5.3-codex 47M █▍ minimax-m2.7 37M █▏ claude-opus-4.6 27M ▉ claude-haiku-4-5-20251001 17M ▌ glm-4.7-free 6.0M ▏ claude-sonnet-4.5 5.0M ▏ claude-haiku-4.5 3.3M ▏ gpt-5.1-codex 1.5M ▏ deepseek-reasoner 1.1M ▏ kimi-k2.5 1.1M ▏ others (39 models) 5.4M ▏

FAQ

Is aivo free?
Yes. Aivo is free, open source, and MIT licensed. aivo-starter is a built-in free provider that works out of the box with no API key required. When you are ready for more, add your own keys from any provider.
Where are my keys stored?
Keys are encrypted and stored locally in ~/.config/aivo/. Requests go directly from your machine to the provider. Aivo never proxies, collects, or sees your data.
Which providers and protocols are supported?
Any endpoint that speaks the OpenAI, Anthropic, or Gemini protocol. Aivo translates between them automatically. OpenRouter, DeepSeek, MiniMax, Kimi, Groq, Vercel AI Gateway, GitHub Copilot, Ollama, Cloudflare — all work out of the box.
Which coding agents can I run?
Claude Code, Codex, Gemini CLI, OpenCode, and Pi. Aivo sets up the environment and passes all extra arguments through, so nothing is lost.
Can I use local models?
Of course, create a key pointing to your local server endpoint. For Ollama, use aivo keys add ollama to connect to your local instance. If the model hasn't been pulled yet, Aivo will automatically download it before starting.
How do I update?
aivo update detects whether you installed via Homebrew, npm, or the install script and updates accordingly.
How do I report a bug or give feedback?
Open an issue on GitHub. github.com/yuanchuan/aivo

Support

If you find aivo useful, consider supporting the project.

Star on GitHub Buy me a coffee