Open Magi Agent

<div align="center">

# Open Magi Agent

**A programmable AI agent that does real work under rules you author.**

[Website](https://openmagi.ai) ·
[CLI](docs/cli/magi.md) ·
[What works today](docs/what-works-today.md) ·
[Releases](https://github.com/openmagi/magi-agent/releases)

![ci](https://github.com/openmagi/magi-agent/actions/workflows/ci.yml/badge.svg)
![release](https://img.shields.io/github/v/release/openmagi/magi-agent)
![install](https://img.shields.io/badge/install-Homebrew-2563eb)
![license](https://img.shields.io/badge/license-Apache--2.0-111827)

</div>

> **Early beta.** Under active development; expect rough edges.

Magi is a governed agent runtime built on ADK. The model proposes work; a
deterministic control plane you program decides which of those proposals become
state, evidence, side effects, or user-visible output. It runs locally, works
with any provider you bring, and is Apache-2.0.

## Install & quickstart

```bash
# 1. Install (Homebrew, prebuilt bottle)
brew install --force-bottle openmagi/tap/magi-agent

# 2. Set whichever provider key you have (auto-detected, one is enough)
export ANTHROPIC_API_KEY=...     # or OPENAI_API_KEY / GEMINI_API_KEY (GOOGLE_API_KEY)
                                 #    / FIREWORKS_API_KEY / OPENROUTER_API_KEY

# 3. Run the CLI, or serve the local dashboard
magi -p "Inspect this repository and summarize the runnable surfaces"
magi-agent serve --port 8080     # then open http://localhost:8080/dashboard
```

One provider key builds a real model-backed runner; with none, the CLI falls
back to a model-free stub. Keys and the model can live in `~/.magi/config.toml`
instead of the environment. Local runs default to `bypassPermissions`; pass
`--permission-mode default` for per-tool approval prompts, or `--mode plan` for
read-only planning.

Two binaries: **`magi`** is the headless / TUI CLI, **`magi-agent`** runs the
server and local dashboard. The **Local web dashboard** runs at
http://localhost:8080/dashboard; run `magi-agent serve --help` for serve
options. If Homebrew tries to build from source instead of using the prebuilt
bottle, reinstall it: `brew reinstall openmagi/tap/magi-agent --force-bottle`.
Full setup, config resolution, flags, and runtime profiles:
[Getting started](docs/getting-started.md) · [CLI reference](docs/cli/magi.md).

## What you get today

With a provider key configured, a default local install runs, on by default:

- **Real model calls** across 5 providers (Anthropic, OpenAI, Gemini, Fireworks,
  OpenRouter) via LiteLlm.
- **First-party tools**: file read/write/edit, patch apply, Bash, ripgrep, LSP
  diagnostics, plus a stateful Python interpreter.
- **Subagents** (live child runner) and an in-turn **work queue**.
- **Memory** that captures, recalls, and rolls up across turns, and survives
  restarts via a durable plan ledger + an **ambient goal loop** that keeps going
  on multi-step work.
- **Sessions** with `--resume` / `--continue`, transcript logs, and an
  interactive TUI with `/` slash commands.
- **Keyless `WebFetch`** (jina-reader + local fetch), a browser tool, and a
  **local knowledge base** (`KnowledgeSearch` over your workspace).
- A **local dashboard** (Customize / Policies / Integrations / Credentials /
  Knowledge / Work Queue / Audit) and an encrypted local credential vault.
- The **pre-final evidence gate**, which blocks a coding turn's output when
  required evidence is missing.

The authoritative, source-cited map of what is on, default-off, or planned is
[What works today](docs/what-works-today.md).

## Why: programmable determinism

Prompt-only control is weak for real work: an agent can claim it read a document
it never opened, cite a source that does not support the claim, skip an approval,
or ship a plausible answer with no audit trail. Coding agents worked first
because tests, review, and git already governed the work for free. Most research,
finance, legal, and operations work has no such oracle, so the runtime has to
govern the work itself, and the rules have to become executable.

Magi makes the control *around* the model deterministic, not the model. A policy
you author decides what context the model sees, which tools are allowed or need
approval, which claims require source / file / test / delivery evidence, which
validators run before an answer or side effect, how failures are repaired, and
what lands in the audit ledger. The gate that decides is plain code reading an
append-only evidence record, with zero model calls. Policy is composed per task,
so the same engine becomes a strict coding agent or an audit-grade research agent
by changing the policy, not the core.

Stated honestly: in a domain with no free oracle, Magi does not guarantee the
answer is *correct* (no gate can, that is the model's job). It guarantees the
answer was produced *under your policy* and can prove it: only approved sources
used, every citation real, no prohibited action taken, a complete audit trail.
The full model, per-run

... (truncated)