# Magi Agent

Programmable AI agent runtime for agents that actually get things done through composable determinism.

## Canonical Links

- Website: https://openmagi.ai
- Source: https://github.com/openmagi/magi-agent
- Docs: https://openmagi.ai/docs
- Full agent docs: https://openmagi.ai/docs/llms-full.txt

## User Install Target

The target Magi Agent UX is a local app install with a CLI and local dashboard.

Install from Homebrew, then start the local HTTP API and dashboard:

```bash
brew install --force-bottle openmagi/tap/magi-agent
magi-agent serve --port 8080
open http://localhost:8080/dashboard
```

Configure a provider with one API key (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, or `FIREWORKS_API_KEY`) or `~/.magi/config.toml`. With a provider key the local `magi` CLI runs a real model plus first-party tools behind permission prompts. Run `magi doctor` to verify setup.

## Source Checkout For Contributors

```bash
git clone https://github.com/openmagi/magi-agent.git
cd magi-agent
uv sync --extra dev --extra cli
uv run --extra cli magi --help
uv run --extra dev pytest -q
```

The source checkout is for contributors developing the runtime. Normal users install via Homebrew.


## Docs Index

- OpenMagi Docs: https://openmagi.ai/docs/overview - Open-source documentation for the Magi Agent programmable AI agent runtime.
- Getting Started: https://openmagi.ai/docs/getting-started - Status: ✅ Active — Homebrew install plus one provider key gives a real local model and first-party tools today.
- Quickstart: https://openmagi.ai/docs/quickstart - Status: ✅ Active — Homebrew install plus one provider key runs a real model-backed task today.
- CLI: https://openmagi.ai/docs/cli - Type: Guide — what the Magi Agent CLI is and the happy-path commands. For the
- Configuration: https://openmagi.ai/docs/configuration - Status: ✅ Active — the local CLI is configured with a single provider key or a
- Customization: https://openmagi.ai/docs/customization - Customize Magi Agent with skills, hooks, model profiles, and workflow policy.
- Runtime: https://openmagi.ai/docs/runtime - How Magi Agent turns model proposals into governed state transitions via the Python ADK runtime.
- Tools: https://openmagi.ai/docs/tools - Status: ✅ Active — first-party tools are registered and on by default; file/search/edit/patch/Bash run live once a provider key is set (`magi_agent/tools/catalog.py`, `core_toolhost.py`).
- Contracts: https://openmagi.ai/docs/contracts - Contracts define the runtime obligations for a governed agent run.
- Hooks: https://openmagi.ai/docs/hooks - Hooks let projects attach policy and evidence behavior without rewriting the
- Memory: https://openmagi.ai/docs/memory - Memory gives the runtime durable context beyond one turn.
- Skills: https://openmagi.ai/docs/skills - Status: ✅ Active — 14 first-party skills ship bundled under `magi_agent/skills/bundled/superpowers/`; each is a `SKILL.md` the model can load to follow a procedure.
- Automation: https://openmagi.ai/docs/automation - Automation covers scheduled work, background tasks, delegated work, and
- Integrations: https://openmagi.ai/docs/integrations - Status: 🚧 Default-off — external side-effect surfaces (chat channels, Composio) ship gated; they require explicit scope, credentials, and approval, and most run in shadow / record-intent mode today.
- API: https://openmagi.ai/docs/api - `magi-agent serve` exposes the local runtime API and dashboard.
- Deployment: https://openmagi.ai/docs/deployment - Status: ✅ Active — local self-host runs today; enforcement boundaries are default-off (shadow).
- Security: https://openmagi.ai/docs/security - Status: ✅ Active — boundaries, default-off authority, and projection control are the security model.
- Architecture: https://openmagi.ai/docs/architecture - The two-plane architecture behind Magi Agent composable determinism.
- Reference: https://openmagi.ai/docs/reference - magi
- Troubleshooting: https://openmagi.ai/docs/troubleshooting - Status: ✅ Active — covers the local `magi` CLI and dashboard path.
- Learning Path: https://openmagi.ai/docs/learning-path - Status: ✅ Active — Homebrew ships now; the user track installs and runs a real task today.
- Sessions: https://openmagi.ai/docs/sessions - How Magi Agent sessions manage state, context, and continuity across turns.
- Checkpoints: https://openmagi.ai/docs/checkpoints - Durable checkpoints for resuming, inspecting, and auditing governed agent runs.
- Work Console: https://openmagi.ai/docs/work-console - The local dashboard for inspecting, approving, and managing agent work.
- Boundaries: https://openmagi.ai/docs/boundaries - Status: 🚧 Default-off — boundary enforcement ships disabled or observe-only until explicitly configured.
- Evidence: https://openmagi.ai/docs/evidence - Evidence ledger entries, source receipts, claim graphs, and evidence contracts that back runtime decisions.
- Projection: https://openmagi.ai/docs/projection - How runtime state is projected into model-visible context and user-visible output.
- Repair and Fallback: https://openmagi.ai/docs/repair-fallback - How the runtime handles missing evidence: retry, downgrade, approve, fallback, abstain, or block.
- Recipes: https://openmagi.ai/docs/recipes - Recipes are the public way to describe reusable agent workflows. A recipe names
- Harnesses: https://openmagi.ai/docs/harnesses - Harnesses are reusable runtime contracts that make a workflow checkable. A
- Build a Recipe: https://openmagi.ai/docs/build-a-recipe - Step-by-step guide to creating a new recipe pack with tool, evidence, and validator refs.
- Build a Harness: https://openmagi.ai/docs/build-a-harness - Step-by-step guide to creating evidence contracts and attaching them to the harness engine.
- Source-Verified Research: https://openmagi.ai/docs/source-verified-research - Worked example of a research recipe requiring SourceInspection and WebSearch evidence before claims.
- Coding Verification: https://openmagi.ai/docs/coding-verification - Worked example of a coding recipe requiring GitDiff, TestRun, and CodeDiagnostics evidence.
- General Automation: https://openmagi.ai/docs/general-automation - Worked example covering approval gates, delivery boundaries, artifact verification, and commit boundaries using openmagi.office-automation and openmagi.spreadsheet-automation packs.
- First-party Packs: https://openmagi.ai/docs/first-party-packs - First-party packs are Magi-owned recipe, harness, plugin, and tool surfaces for
- Multi-Recipe Composition: https://openmagi.ai/docs/multi-recipe-composition - How multiple recipe packs compose via profile resolution, and how harness scoping selects evidence contracts by role.
- Runtime Interfaces: https://openmagi.ai/docs/runtime-interfaces - Python interfaces exposed by the Magi Agent runtime for extension.
- Hook Points: https://openmagi.ai/docs/hook-points - Lifecycle hook points with HookRegistry registration and HookBus dispatch.
- ToolHost: https://openmagi.ai/docs/toolhost - Tool catalog, ToolManifest schema, ToolRegistry, and governed tool dispatch.
- Evidence Contracts: https://openmagi.ai/docs/evidence-contracts - Define and test evidence contracts that declare required evidence for agent actions.
- Plugin Manifest: https://openmagi.ai/docs/plugin-manifest - Package and distribute runtime extensions as plugins with a declared manifest.
- Testing Recipes: https://openmagi.ai/docs/testing-recipes - Test recipes and harnesses with deterministic replay, contract tests, and shadow runs.
- Config Reference: https://openmagi.ai/docs/config-reference - Complete reference for RuntimeConfig (config/env.py), PythonMemoryAdapterConfig, PythonToolHostAttachmentConfig, PythonRuntimeAuthorityConfig, and all Literal[False] safety invariants.
- Environment Variable Reference: https://openmagi.ai/docs/env-reference - Status: ✅ Active — the local `magi` CLI and dashboard run with a single
- Recipe Schema Reference: https://openmagi.ai/docs/recipe-schema - Complete schema reference for RecipePackManifest, RecipeSnapshot, and ProfileResolutionRequest.
- Harness Schema Reference: https://openmagi.ai/docs/harness-schema - Complete schema reference for HarnessEngine, HarnessResolutionRequest, ResolvedHarnessPresetState, EvidenceContractScope, and BuiltinHarnessPreset.
- Hook Points Reference: https://openmagi.ai/docs/hook-points-reference - Complete reference for all 15 HookPoint enum values, their camelCase keys, firing conditions, payloads, and blocking behavior.
- Evidence Types Reference: https://openmagi.ai/docs/evidence-types-reference - Complete reference for all 15 built-in evidence types, their producers, typical fields, and the EvidenceFieldMatcher for requirement matching.
- ToolHost API Reference: https://openmagi.ai/docs/toolhost-api - Reference for ToolManifest full schema (tools/manifest.py), ToolRegistry (tools/registry.py), tool execution flow, ToolEvidenceRecord, and governed dispatch status.
- Runtime Events Reference: https://openmagi.ai/docs/runtime-events - Reference for runtime event kinds, their payloads, and how events relate to SSE streaming, boundary decisions, and evidence recording.
- Streaming Events: https://openmagi.ai/docs/streaming-events - Magi Agent streams public runtime progress through Server-Sent Events and CLI
- Frequently Asked Questions: https://openmagi.ai/docs/faq - Answers to common questions about Magi Agent: recipes vs harnesses, default-off boundaries, local testing, repair decisions, model compatibility, and custom evidence types.
- What Works Today: https://openmagi.ai/docs/what-works-today - Status: ✅ Active — with a provider key, the local `magi` CLI runs a real model and first-party tools today.
- Common Tasks: https://openmagi.ai/docs/common-tasks - Status: ✅ Active — the local `magi` CLI runs a real model and first-party tools once a provider key is set (`magi_agent/cli/app.py`, `magi_agent/tools/catalog.py`).
- Channels (Telegram, Discord): https://openmagi.ai/docs/channels - Status: 🚧 Default-off — channel code (Telegram, Discord) ships in shadow / local-fake mode; live send/receive is gated and produces intent + receipt records, not real delivery (`magi_agent/channels/telegram_adapter.py`, `contract.py`).
- CLI Reference: https://openmagi.ai/docs/cli-reference - Type: Reference — the full flag, output-mode, exit-code, keybinding, and
- In-session Commands: https://openmagi.ai/docs/cli-commands - The `/`-prefixed slash commands available inside a `magi` session (builtins, bundled, and project-discovered).
- Changelog: https://openmagi.ai/docs/changelog - Status: ✅ Active — this page tracks user-facing changes; tagged builds are on GitHub Releases.
- Upgrading: https://openmagi.ai/docs/upgrading - Status: ✅ Active — covers upgrading the Homebrew install and source checkouts.
- Glossary: https://openmagi.ai/docs/glossary - Status: ✅ Active — definitions of the core Magi Agent terms.
- Contributing: https://openmagi.ai/docs/contributing - Thank you for your interest in contributing!