# lionagi

> An open-source Python framework for building governed multi-agent LLM workflows with typed state, a CLI, persistent runs, and MCP integration.

lionagi is a governed multi-agent orchestration framework for Python, built continuously since 2023 by Haiyang Li under the Apache-2.0 license. It lets developers build single agents, parallel fan-outs, and DAG-based flows where an orchestrator plans specialist workers — all from Python code or the `li` command-line interface. The project is the orchestration layer in a three-part open-source stack alongside khive (knowledge/memory runtime) and lattice (local inference engine).

## What It Is

lionagi is a Python library and CLI tool for composing multi-step LLM workflows with typed, inspectable state. The core abstraction is a **Branch** — a single conversation thread with message history, tools, and model configuration — and a **Session** that coordinates multiple Branches across DAG workflows. Every run persists to `~/.lionagi/runs/` and can be resumed, reattached, or monitored live. The framework is designed so developers own the loop: there is no hidden prompt assembly or opaque runtime between the user and the model.

## How the Orchestration Model Works

lionagi supports three primary execution patterns via the `li` CLI:

- **Single agent** (`li agent`): a resumable, single-conversation run against any supported model
- **Fan-out** (`li o fanout`): N workers run in parallel, with an optional synthesis pass
- **DAG flow** (`li o flow`): an orchestrator plans a dependency graph of specialist agents; workers execute as their dependencies resolve

CLI model aliases (`claude`, `codex`, etc.) spawn the provider's own CLI as a subprocess, so existing subscriptions (Claude Code, ChatGPT Plus/Pro) work without an API key. API-endpoint providers (OpenAI, Anthropic, Gemini, Ollama, Groq, OpenRouter, and others) use standard environment key configuration.

## Governance and Safety Features

A distinguishing design choice in lionagi is built-in governance. The framework includes:

- **Permission policies** per tool call
- **Guard hooks** that block destructive commands and off-limits file paths
- **Git-worktree sandboxing** for speculative edits that never touch the working branch until explicitly merged
- **Audit trails** on task completion and delegation

This makes lionagi oriented toward production use cases where agent actions need to be inspectable and controllable, not just exploratory prototyping.

## Lion Studio: Observability UI

Lion Studio is a hosted web UI at `lion-studio.khive.ai` that connects to a local lionagi daemon running at `127.0.0.1:8765`. It provides live views of agent runs, schedules, playbooks, execution DAGs, and run inspection. Because the page is a client-side app that talks to the local daemon, no data leaves the user's machine. It supports 16 languages including full right-to-left support. Installation requires only `pip install "lionagi[studio]"` followed by `li studio start`.

## MCP Integration and Ecosystem Position

lionagi ships with optional MCP server support (`lionagi[mcp]`) and integrates natively with the khive knowledge-graph runtime, which is served over MCP from a single Rust binary. The `li` CLI can mirror Claude Code sessions via `li mirror`, and installable Claude Code Marketplace plugins cover memory management, playbook authoring, and multi-agent orchestration. The broader khive.ai stack positions lionagi as the orchestration layer above a local inference engine (lattice) and a persistent memory/knowledge-graph layer (khive).

## Update: v0.35.2

The latest release is v0.35.2, published on 2026-08-25, with the repository last updated in September 2026. The project has been under active development since October 2023 and shows consistent release cadence. Recent additions visible in the README include team messaging (`li team send/receive`), playbook support (`li play`), time-bounded runs with deadline preambles, and the Lion Studio observability UI going live. The GitHub repository lists 408 stars and 81 forks as of the last crawl.

## Features
- Multi-agent DAG orchestration with dependency resolution
- Single-agent and parallel fan-out execution modes
- Typed, inspectable Branch and Session state
- Persistent runs saved to ~/.lionagi/runs/ with resume support
- li CLI with agent, fanout, flow, team, monitor, schedule, and kill commands
- Structured output via Pydantic response_format
- ReAct tool-use loop
- Permission policies and guard hooks per tool call
- Git-worktree sandboxing for speculative edits
- Lion Studio hosted observability UI (local data, no upload)
- MCP server support
- Claude Code Marketplace plugins
- Playbook support for parametric flow specs
- Team messaging inbox coordination between agents
- Time-bounded runs with deadline preambles
- 16-language UI with RTL support
- Optional extras: PDF/HTML/DOCX reader, Ollama, PostgreSQL persistence, Rich terminal, flow visualization

## Integrations
Claude Code CLI, OpenAI Codex, Cursor, Windsurf, OpenAI API, Anthropic API, Google Gemini, Ollama, NVIDIA NIM, Perplexity, Groq, OpenRouter, DeepSeek, MCP protocol, khive knowledge runtime, lattice local inference, PostgreSQL, PyPI, Docker

## Platforms
MACOS, LINUX, WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v0.35.2

## Links
- Website: https://khive.ai
- Documentation: https://ohdearquant.github.io/lionagi/
- Repository: https://github.com/ohdearquant/lionagi
- EveryDev.ai: https://www.everydev.ai/tools/lionagi