 █████╗  █████╗ ██████╗
██╔══██╗██╔══██╗██╔══██╗
███████║███████║██████╔╝
██╔══██║██╔══██║██╔══██╗
██║  ██║██║  ██║██║  ██║
╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝

● adaptive action & reasoning · v0.3.2 · apache 2.0

built a lightweight AI agent.

open source python. ~80-line core loop. swap providers mid-session.
does what claude code, codex, and pi mono do — maybe a bit more.
if you want something you can actually read and modify, might be useful.

$ git clone https://github.com/fischerf/aar && cd aar && pip install -e ".[all]"

# no api key — fully local

$ ollama pull llama3 && aar chat --provider ollama --model llama3

# ~/.config/zed/settings.json (or %appdata%\zed\settings.json on windows)

"agent_servers": { "Aar": { "type": "custom", "command": "aar", "args": ["acp"] } }

what it is

a thin, readable agent.

most agent frameworks are opaque. aar isn't. open agent/core/loop.py and read the whole thing. no magic, no framework soup. extend it to fit how you actually work.

thin core

~80-line main loop. the entire execution path fits in your head. agent/core/loop.py

any provider

anthropic, openai, gemini, ollama, or any openai-compatible endpoint. switch with /model mid-session.

sandboxed

path restrictions, command deny-lists, approval gates. wsl / docker / landlock sandbox modes built in.

cost-aware

live token + cost tracking. configurable budget limits. warns before you burn through your credits.

typed events

every event, tool call, and result is a pydantic model. no raw dicts. serializable, debuggable.

extensible

three-tier extension api — global, per-user, per-project. event hooks, custom tools, slash-commands.

persistent sessions

every run saved as jsonl. resumable. forkable from any point. your history is your audit trail.

ide integration

zed and vscode via the agent client protocol. direct stdio — no cloud relay, no port needed.

modes

seven ways to run it.

command	use case	notes
`aar run "…"`	ci / automation	one-shot, runs to completion, exits.
`aar chat`	interactive cli	conversational loop with approval prompts.
`aar tui`	tui	rich tui with live token counters.
`aar tui --fixed`	full-screen tui	textual ui — fixed bars, mouse support, file picker. open-source equivalent of claude code / codex.
`aar serve`	http api	sse streaming, embeddable as asgi app.
`aar acp` ide	zed / vscode	acp stdio agent. editor connects directly.
`aar acp --http`	remote acp	acp over http/sse for remote or programmatic clients.

providers

bring your own model.

set an env var and go. switch mid-session with /model. run fully local with ollama — no api key, no cloud.

anthropic — claude 3.5, claude 4

openai — gpt-4o, o3, o4-mini

google — gemini pro & flash

ollama — any local model

generic openai-compatible endpoint

install

setup.

01 clone & install

$git clone https://github.com/fischerf/aar && cd aar

$pip install -e ".[all]"

installing aar-agent...

✓ done

-e makes it a live install — edits to agent/ are reflected immediately.

02 provider key

$export ANTHROPIC_API_KEY=sk-ant-...

# or OPENAI_API_KEY, GEMINI_API_KEY — or skip and use ollama locally

03 run

$aar tui --fixed

✓ ready

also: aar chat · aar tui · aar run "…" · aar serve

04 zed integration (optional)

~/.config/zed/settings.json

{
  "agent_servers": {
    "Aar": {
      "type": "custom",
      "command": "aar",
      "args": ["acp"]
    }
  }
}
        

vscode: install acp client, same config under "acp.agents". full guide: docs/acp.md.

05 wsl sandbox — windows only (optional)

$aar init # creates ~/.aar/distros/ profiles

$aar sandbox setup # downloads rootfs, installs packages

$aar sandbox status

routes all shell commands through a disposable alpine distro. see docs/safety.md.

changelog

releases.

full history at CHANGELOG.md and GitHub Releases.

v0.3.2 latest

2026-04-22

Gemini provider — Google Gemini Pro & Flash via official SDK + HTTP backend
ACP SDK transport — Zed stdio now uses the official agent-client-protocol SDK
Full ACP session lifecycle — load, list, fork, resume, set-mode all implemented
Docker sandbox — run agent tools inside an isolated container
Linux Landlock sandbox — kernel-level process isolation (Linux ≥ 5.13)
Windows Job Object sandbox — process isolation using Windows Job Objects
File picker in TUI — @ opens a modal file browser in the fixed TUI
Budget proximity warning — warns before approaching token/cost limits
Guardrails — configurable rules for autonomous loop safety
VSCode integration — launch profiles and ACP config
MCP server bridge in ACP — stdio and HTTP MCP servers registered per session

v0.3.1

2026-04-11 — initial public release

Anthropic, OpenAI, Ollama, generic provider support
Rich TUI + Textual full-screen TUI with themes
Web API (ASGI / SSE)
WSL sandbox, JSONL session persistence, MCP bridge
token budget and cost tracking

full changelog →