Avo

Reliable agent infrastructure for observable, resumable, provider-agnostic runs.

One conversation, many models: bounded tools, durable state, and automatic failover down to local Ollama.

Avo is an observable, resilient AI agent runtime that can use API providers, vendor-account OAuth, or local models behind one execution loop. When a quota, rate limit, or provider outage interrupts a turn, Avo can switch tiers without discarding the conversation or execution state. Runs are recorded in SQLite so you can inspect, resume, and explain what happened.

The core package stays dependency-light (Pydantic only). Provider clients, Docker sandboxing, MCP, OpenTelemetry, and the LangChain bridge are optional extras, so you can install only the capabilities your deployment needs.

What Makes Avo Different?

┌─────────────────────────────────────────────────────────────┐
│                      Avo Runtime                            │
└───────────────────────────┬─────────────────────────────────┘
                            │
              ┌─────────────▼─────────────┐
              │    ComboRouterProvider    │
              └─────────────┬─────────────┘
                            │
      ┌─────────────────────┼─────────────────────┐
      │ (Tier 1: Primary)   │ (Tier 2: Cheap)     │ (Tier 3: Free Floor)
┌─────▼──────────────┐┌─────▼──────────────┐┌─────▼──────────────┐
│ Claude / ChatGPT   ││ OpenRouter / Groq  ││ Ollama (Local)     │
│ (Account / Quota)  ││ (Pay-per-token)    ││ (Zero Cost / Free) │
└────────────────────┘└────────────────────┘└────────────────────┘
         │ (429/Quota)         │ (429/Quota)
         └──────► Fallback ────┴──────► Fallback ────► Done

1. 🔑 Vendor Account Login & Universal Login

Open the official Claude, ChatGPT/Codex, or Google Gemini login in your browser via standard PKCE flows (avo login claude, avo login codex, avo login gemini). Free and paid accounts can have different model access and quotas; Avo never claims that a plan is required or bypasses vendor limits. AVO_ALLOW_SUBSCRIPTION=1 is an explicit opt-in for OAuth-backed inference. Tokens are stored as plaintext alongside API keys in ~/.config/avo/auth.json, protected by 0600 file permissions rather than encryption, and refreshed automatically in the background with deduplication.

2. 🔀 Multi-Tier Combo Routing & Quota Failover

Never suffer crashed agent runs from HTTP 429 or exhausted token quotas again. Configure named combo profiles (default, coder, budget) where models are organized in priority order (account → cheap API → free local floor). Avo detects rate limits and credit exhaustion mid-turn, switches to the next tier, and continues streaming.

3. 📜 Event-Sourced Ledger & Replay

Every decision, prompt, tool call, output, and failover is recorded as an immutable event in a durable SQLite ledger. Any past run can be inspected with chronological traces (avo runs inspect <id>) or resumed deterministically (avo runs resume <id>).

4. 🛡️ Hardened Workspace & Ephemeral Sandboxing

File tools strictly enforce POSIX O_NOFOLLOW boundaries—null bytes, symlink escapes, and ../ traversal are blocked before any I/O occurs. Shell commands run in isolated, ephemeral Docker containers with CPU/memory limits and disabled networking by default.

5. 🪶 Zero Extra Core Dependencies

The core agent loop, state machine, event store, and providers require only Pydantic. Additional capabilities (Docker sandbox, OpenTelemetry, CLI extras) remain opt-in.

6. 🧠 Deterministic Token Savers

Long tool-heavy conversations can opt into internal compact, full, or terse-output presets with avo saver use NAME. Avo preserves the original event history and reports estimated savings; no external RTK/Caveman binary is required.

Terminal Visual Walkthrough

Experience interactive agent loops with real-time model failover:

$ export AVO_PROVIDER=combo
$ export AVO_COMBO=coder
$ avo

       ▄██▄           Avo CLI 0.7.1
     ▄██████▄         Fqih (account quota)
    ███    ███        provider: combo · model: coder [account -> cheap -> free]
   ███  ▄▄  ███       workspace: ~/Project/Loopward
   ███  ▀▀  ███       session: c8f921ab04e1
  ──────────────────────────────────────────────────────

> Analyze the authentication flow in src/avo/auth.py and write unit tests

⠋ Thinking...
⤾ Fallback: switched from 'account' (claude) to 'cheap' (openrouter) [rate_limited_429]

I've analyzed `src/avo/auth.py`. Here is the architecture breakdown and test suite...

Quickstart (Under 2 Minutes)

1. Installation

Requires Python 3.11+.

User-global CLI installer

For a user-global command, install Avo with the OS-native installer. It uses uv tool and does not require sudo or Administrator access.

Linux, macOS, or Git Bash on Windows:

curl -fsSL https://avo.faqihhakim.tech/install.sh | bash

Native Windows PowerShell:

irm https://avo.faqihhakim.tech/install.ps1 | iex

The installer installs the avo[all] runtime bundle, ensures Python 3.13 is available through uv, and updates the user PATH for avo. Review the plan without making changes first:

bash install.sh --dry-run
# PowerShell: .\install.ps1 -DryRun

For a smaller installation, override the package or Python version:

AVO_PACKAGE='avo[providers]' AVO_PYTHON_VERSION=3.12 bash install.sh

The global installer only installs the CLI. Run avo setup once to create the global ~/.avo configuration, then use avo doctor to inspect what Avo will resolve. Workspace state and run history remain local to the project.

For vendor-account OAuth providers, opt in explicitly so the choice is visible and reproducible:

avo setup --allow-subscription
avo doctor

Development checkout

git clone https://github.com/Fqih/avo.git
cd avo
python -m pip install -e ".[dev,providers,sandbox]"

2. Authenticate and configure

Log in through an official vendor browser flow or plain API keys:

# Official browser login (Claude, ChatGPT Codex, or Gemini)
avo login claude
avo login codex
avo login gemini

# Or store plain API keys in permission-restricted auth.json
avo login openrouter --key-stdin

# Authenticate every missing cloud vendor used by a combo, one at a time
avo combo auth coder

# Inspect local hardware before choosing a model to download
avo models ollama recommend
avo models ollama pull qwen2.5-coder:7b

Verify the resolved provider, model, endpoint, and credential requirements with one command. doctor does not make a provider request:

avo doctor

The first successful setup/login becomes Avo's remembered route in ~/.avo/config.json, so launching avo again reuses that provider and model. The setup wizard offers a numbered model picker; available access still depends on the account's plan and quota. Use /model in the REPL to inspect the catalog or override the model for the next turn.

3. Interactive Chat REPL

Launch the agent with multi-tier combo routing:

AVO_PROVIDER=combo AVO_COMBO=coder avo chat

Inside the REPL:

• Type /combo to view real-time tier health and latencies.
• Type /combo budget to hot-swap to another profile.
• Type /diff to inspect uncommitted workspace modifications.
• Type /model to pick a specific standalone model.

4. Python API Example

Embed Avo's resilient loop directly into your Python service:

import asyncio
from pydantic import BaseModel

from avo import AgentRuntime, FunctionTool, ModelResponse, TokenUsage, ToolCall
from avo.providers import FakeProvider


class AddArguments(BaseModel):
    left: int
    right: int


async def add(arguments: AddArguments) -> object:
    return {"sum": arguments.left + arguments.right}


async def main() -> None:
    # 100% offline testable fake provider
    provider = FakeProvider(
        [
            ModelResponse(
                tool_call=ToolCall(
                    tool_call_id="addition-1",
                    name="add",
                    arguments={"left": 2, "right": 3},
                ),
                usage=TokenUsage(input_tokens=12, output_tokens=5),
            ),
            ModelResponse(
                content="The sum is 5.",
                usage=TokenUsage(input_tokens=18, output_tokens=6),
            ),
        ]
    )

    runtime = AgentRuntime(
        provider=provider,
        tools=[
            FunctionTool(
                name="add",
                description="Add two integers.",
                arguments_model=AddArguments,
                function=add,
            )
        ],
    )
    result = await runtime.run("What is 2 + 3?")
    print(result.status.value, result.stop_reason.value, result.output)


if __name__ == "__main__":
    asyncio.run(main())

Comparison Matrix

How does Avo compare to alternative model proxies and CLI tools?

Supported Providers

Live model catalogs and Antigravity

For gemini-cli, Avo does not need to maintain a second model list. In an interactive terminal, /model fetches the current account catalog from Antigravity's agy models command. If you use CLIProxyAPI, point Avo at its OpenAI-compatible server instead; Avo fetches GET /v1/models and sends turns to POST /v1/chat/completions:

export AVO_PROVIDER=gemini-cli
export AVO_GEMINI_CLI_TRANSPORT=cliproxyapi
export AVO_CLIPROXYAPI_BASE_URL=http://127.0.0.1:8317
export AVO_CLIPROXYAPI_API_KEY=your-local-proxy-key   # optional for an open localhost proxy
avo

When neither a proxy nor agy is available, Avo reports the missing transport instead of silently using a stale model catalog. The coding agent also exposes a run_terminal tool for commands, tests, and linters in the active workspace; require explicit approval with AVO_TOOLS_REQUIRE_APPROVAL=run_terminal when needed.

CLI & REPL Cheat Sheet

Core CLI Commands

Essential Chat Slash Commands

• /combo [NAME]: View live tier health status or hot-swap combo profiles.
• /model [NAME]: Switch active provider or model on the fly.
• /provider: Inspect resolved endpoint and credentials.
• /context: Snapshot token usage, session turns, and active persona.
• /diff: Display unified git diff or status in the current workspace.
• /undo: Revert uncommitted workspace modifications.
• /export [PATH]: Export session history to formatted Markdown.
• /clear: Clear terminal screen.
• /quit: Exit REPL.

Acknowledgments & Upstream Lineage

Avo is built upon and inspired by excellent open-source projects:

• decolua/9router (MIT): Upstream reference and port for OAuth PKCE authorization-code token exchange shapes, vendor endpoints, and token-refresh lifecycle patterns.
• clash-ru/CLIProxyAPI (MIT): Upstream Go lineage for subscription flow verification.
• BerriAI/liteLLM (MIT): Reference for provider fallback matrices and error categorization.
• Textualize/rich (MIT): Inspiration for terminal styling and visual design.
• Anthropic, OpenAI, Google, and Ollama: For developer APIs and local inference engines.

Documentation

Full documentation, architecture specs, and user guides are available at avo.faqihhakim.tech:

• Quickstart
• Installation & global CLI
• Provider login and quota guide
• Combo Routing & Failover Guide
• CLI reference
• Full Project API Reference
• SemVer & Stability Policy

Project status and boundaries

Avo is currently alpha software. The durable runtime, provider adapters, CLI, event ledger, and offline test suite are usable for local prototypes and evaluation. Treat subscription OAuth, sandbox execution, and provider failover as evolving interfaces until the project reaches a stable release.

Before deploying Avo in an unattended environment, review the permission mode, workspace boundaries, credential storage, and provider fallback policy for your own threat model.

Contributing

python -m pip install -e ".[dev,docs,providers]"
python -m ruff check .
python -m ruff format --check .
python -m pytest

Bug reports and focused pull requests are welcome. Start with the smallest reproducible test, especially for provider behavior, replay, or workspace security changes.

License

Distributed under the MIT License. See LICENSE for details.