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

● adaptive action & reasoning · v0.4.0 · 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

skills

lazy-loaded instruction modules — drop a markdown file in ~/.aar/skills/ and the agent picks it up when relevant.

context compaction

llm-based summarization keeps long sessions inside the window. cut-point detection, token estimation, compact strategy.

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.

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.4.0 latest

2026-06-10

Skills — lazy-loaded instruction modules from ~/.aar/skills/ and .agent/skills/ (markdown + YAML frontmatter)
LLM context compaction — token estimation, cut-point detection, structured summarization via the compact strategy
Multi-provider config — single config file with /model to list, show & switch the active provider mid-session, plus capability-mismatch warnings
New built-in tools — grep (regex content search) and find_files (glob path search)
Tool-aware system prompt — tools contribute prompt snippets and guidelines to an "Available tools" layer; inspect with aar prompt --layers
Plugin extension system — agent/extensions/ loader + manager, aar install, aar extensions list / inspect, pipeline event transforms
ACP 0.10.0 — message_id, additional directories, extension slash commands, per-session MCP server bridge
TUI context bar — live token usage in the fixed header, queued prompts, kaomoji companion widget
Token/cost persistence — running totals saved and restored across sessions; offline analysis via scripts/analyze_tokens.py
/fork renamed to /branch · rate-limit resilience with jitter · VSCode launch profiles · large-file edit fixes

v0.3.2

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 →