
![PyPI - Version](https://img.shields.io/pypi/v/lionagi?labelColor=233476aa&color=231fc935)
![PyPI - Downloads](https://img.shields.io/pypi/dm/lionagi?color=blue)
![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
[![codecov](https://codecov.io/github/ohdearquant/lionagi/graph/badge.svg?token=FAE47FY26T)](https://codecov.io/github/ohdearquant/lionagi)

# lionagi

Orchestrate multi-agent AI workflows from the command line or Python.

[Docs](https://ohdearquant.github.io/lionagi/) |
[Docs / Architecture (DeepWiki)](https://deepwiki.com/ohdearquant/lionagi) |
[Discord](https://discord.gg/JDj9ENhUE8) |
[PyPI](https://pypi.org/project/lionagi/) |
[Changelog](CHANGELOG.md)

## Lion Studio

![Lion Studio — run detail with execution DAG, branches, and multi-agent orchestration](assets/studio.png)

Lion Studio is the built-in web UI for managing and operating your agent workflows. Projects, schedules, playbooks, shows, and runs — all in one place.

```bash
pip install lionagi

# Option 1: Docker (recommended — one command, no Node.js needed)
li studio                       # auto-pulls ghcr.io/ohdearquant/lion-studio
                                # UI → http://localhost:3000  API → http://localhost:8765

# Option 2: From source (for development)
git clone https://github.com/ohdearquant/lionagi.git && cd lionagi
pip install ".[studio]"
li studio --dev                 # starts backend + frontend with hot reload
```

## What's New in 0.26

- **Lion Studio** — web UI for orchestrating agent workflows: projects, scheduled runs, execution DAGs, branch inspection, and multi-agent monitoring.
- **Project management (ADR-0026)** — per-repo `.lionagi/config.toml` for project identity. Sessions auto-group by project. `--project NAME` flag on all CLI commands.
- **Scheduled runs (ADR-0027)** — cron, interval, and GitHub-poll triggers with DAG-based conditional chains (`on_fail`/`on_success`). Studio becomes an active operator, not just a monitor.
- **Agent infrastructure** — `AgentConfig` presets (`.coding()`, `.research()`) with built-in permission policies, hooks, and tool registration via `create_agent()`.
- **Sandbox tool** — `SandboxSession` uses git worktrees for isolated editing: `create()` → edit → `diff()` → `commit()` → `merge()` or `discard()`.

## Install

```bash
pip install lionagi
```

**CLI provider auth** — CLI aliases spawn subprocess tools, not REST API calls:

- `claude`: install [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) → `claude login` (subscription) or `export ANTHROPIC_API_KEY=sk-ant-...` (API key)
- `codex`: requires ChatGPT Plus/Pro → `npm install -g @openai/codex` → `codex login`
- `deepseek`: `export DEEPSEEK_API_KEY=sk-...` for DeepSeek models
- `pi`: install [Pi Code CLI](https://pi.ai) for Pi models
- Python API (`iModel`, `Branch`): `export OPENAI_API_KEY=sk-...` for gpt-4.1-mini default

## First Flow

```python
import asyncio
from lionagi import Branch

async def main():
    b = Branch()          # default: gpt-4.1-mini (requires OPENAI_API_KEY)
    reply = await b.communicate("Name 3 features of async Python, one sentence each.")
    print(reply)

asyncio.run(main())
```

```text
# output:
1. Coroutines let you write non-blocking I/O without threads.
2. asyncio.gather runs multiple coroutines concurrently under one event loop.
3. async generators stream results lazily, pausing between each yield.
```

For multi-agent orchestration without Python, see [CLI Quick Start](docs/getting-started/first-flow.md).

## Concepts

| Term | What it is |
|------|------------|
| **Branch** | Single conversation thread — message history, tools, model config. Primary API surface. |
| **Session** | Coordinates multiple Branches; runs DAG workflows across them. |
| **flow** | `li o flow` — orchestrator plans a DAG, workers execute with dependency edges resolved. |
| **team** | Persistent inbox messaging between agents via `li team send/receive`. |
| **operate** | `branch.operate(instruction=…)` — tool use + structured output + optional streaming. |
| **persist** | Every run saved to `~/.lionagi/runs/{run_id}/`. Resume with `li agent -r <branch-id>`. |
| **AgentConfig** | Preset agent configurations (coding, research) with permission policies, hooks, and tool registration. |
| **Sandbox** | Git worktree isolation for safe experimentation — `SandboxSession.create()` → edit → diff → merge or discard. |

## CLI — `li`

```bash
# Single agent
li agent claude/sonnet "Explain the observer pattern in 3 sentences"

# Fan-out: N workers in parallel, optional synthesis
li o fanout claude/sonnet "Identify code smells in this codebase" -n 3 --with-synthesis

# DAG flow: orchestrator plans agents with dependency edges
li o flow claude/sonnet "Audit the auth module for security issues" --cwd .

# Team messaging: inbox coordination between agents
li team create "review" && li team send "Start analysis" -t <id> --to analyst

# Playbook: parametric flow spec at ~/.lionagi/playbooks/audit.playbook.yaml
li play audit --mode security "the auth service"
li play NAME --help                          # Show playbook parameters and usage

# Skill: print a CC-compatible reference body to stdout (for agent context injection)
li skill commit

# Resume any run
li agent -r <branch-id> "follow up on your findings"

# Time-bounded run: injects a [DEADLINE] preamble so the agent paces its own reasoning
li agent claude/sonnet --timeout 300 "Audit the auth module and produce a summary"
```

Full reference → [docs/cli-reference.md](docs/cli-reference.md) · Installable
templates → [examples/](examples/)

## CLI Commands

**`li agent`** — Run a single agent session against any CLI-compatible model.
`li agent [MODEL] PROMPT [-a NAME] [-r BRANCH_ID] [-c] [--yolo] [--bypass] [--fast] [-v] [--theme {light,dark}] [--effort LEVEL] [--cwd DIR] [--timeout SECS] [--invocation ID] [--project NAME]`
Load a saved profile with `-a`/`--agent`; resume a previous branch by ID with `-r`/`--resume`; reattach to the last branch with `-c`/`--continue-last`.

**`li o flow`** — Run a multi-agent DAG flow where an orchestrator model plans and dispatches specialist agents.
`li o flow [MODEL] [PROMPT] [-f FILE] [-p PLAYBOOK] [-a AGENT] [--with-synthesis [MODEL]] [--max-concurrent N] [--output {text,json}] [--save DIR] [--team-mode [NAME]] [--team-attach NAME] [--dry-run] [--show-graph] [--background] [--bare] [--workers M1,M2,...] [--max-ops N] [--reactive MODE]` plus shared flags (`--yolo`, `--bypass`, `--fast`, `-v`, `--theme`, `--effort`, `--cwd`, `--timeout`, `--invocation`, `--project`).
Provide the flow spec via `-f FILE` (YAML/JSON), a named playbook via `-p PLAYBOOK`, or a free-form prompt. `--dry-run` prints the planned DAG without executing; `--background` runs detached and requires `--save`.

**`li o fanout`** — Run the same prompt against multiple worker models in parallel with optional synthesis.
`li o fanout [MODEL] PROMPT [-a AGENT] [-n N] [--workers M1,M2,...] [--max-concurrent N] [--with-synthesis [MODEL]] [--synthesis-prompt TEXT] [--output {text,json}] [--save DIR] [--team-mode [NAME]]` plus shared flags.
Set the worker count with `-n`; specify explicit model specs with `--workers`; add a final synthesis pass with `--with-synthesis`.

**`li play`** — Shortcut for `li o flow -p NAME`; runs a named playbook from `~/.lionagi/playbooks/`.
`li play NAME [flow-flags...]` | `li play list` | `li play check NAME`
`li play list` enumerates installed playbooks; `li play check NAME` validates artifact contracts before a run; `li play NAME --help` shows playbook-declared parameters. All `li o flow` flags except `-f`/`--file` are forwarded after `NAME`.

**`li monitor` / `li mon`** — Inspect live and recent sessions, invocations, shows, and plays.
`li monitor [ID] [-w] [--refresh SECS] [--since WINDOW] [-t {session,invocation,show,play}] [-p PROJECT]`
Pass an ID or unique prefix for a detail view; `-w`/`--watch` enables live refresh at `--refresh` interval; `--since` accepts windows like `30m`, `1h`, `2d`.

**`li kill`** — Stop a running session or invocation.
`li kill [ID] [--reason TEXT] [--recursive] [--all-stale] [--threshold SECS] [--dry-run] [--grace SECS]`
Target by entity ID or unique prefix; `--recursive` also kills child entities; `--all-stale` sweeps processes with dead PIDs; `--dry-run` previews without changing state.

**`li studio`** — Launch the Lion Studio web UI (backend API + React frontend).
`li studio [start] [--port PORT] [--host HOST] [--frontend-port PORT] [--no-frontend] [--dev] [--no-docker]`
Defaults to Docker (`ghcr.io/ohdearquant/lion-studio`; auto-pulled); `--no-docker` uses a local install; `--no-frontend` starts the API server only; `--dev` enables hot-reload frontend for development.

## Python API

**Chat**

```python
from lionagi import Branch

b = Branch(chat_model="openai/gpt-5.4", system="You are a concise assistant.")
reply = await b.communicate("What causes rainbows?")
```

**Structured output**

```python
from pydantic import BaseModel

class Summary(BaseModel):
    points: list[str]
    confidence: float

result = await b.operate(instruction="Summarize this text.", response_format=Summary)
```

**Tools + ReAct**

```python
from lionagi.tools.types import ReaderTool

branch = Branch(tools=[ReaderTool])
result = await branch.ReAct(
    instruct={"instruction": "Summarize /path/to/paper.pdf"},
)
```

Full reference → [docs/api/](docs/api/)

## Docs

| | |
|--|--|
| [Getting Started](docs/getting-started/first-flow.md) | Install, first flow, API key setup |
| [Concepts](docs/concepts.md) | Branch, Session, flow, team, operate, persist |
| [CLI Reference](docs/cli-reference.md) | `li agent`, `li o fanout`, `li o flow`, `li team` — all flags |
| [Cookbook](docs/cookbook/) | 5 runnable scenarios: codebase audit, research synthesis, multi-model pipeline, team coordination, resumable background run |
| [API Reference](docs/api/) | `branch.operate`, `branch.ReAct`, `iModel`, `Session` |
| [Migration 0.22.5 → 0.22.6](docs/migration/0.22.5-to-0.22.6.md) | Breaking changes: `branch.instruct` removed, run paths changed |
| [Contributing](docs/contributing.md) | Dev setup, PR workflow |

## Optional Extras

```bash
uv add "lionagi[reader]"    # Document reading (PDF, HTML, DOCX)
uv add "lionagi[mcp]"       # MCP server support
uv add "lionagi[ollama]"    # Local models via Ollama
uv add "lionagi[rich]"      # Rich terminal output
uv add "lionagi[graph]"     # Flow visualization
uv add "lionagi[postgres]"  # PostgreSQL persistence
uv add "lionagi[all]"       # Everything
```

## Claude Code Marketplace

The lionagi marketplace provides installable Claude Code plugins for the lionagi agent runtime. Each plugin adds a focused set of skills and agents for a specific workflow: structured show runs, memory management, playbook authoring, developer tooling, and multi-agent orchestration.

**Install:**

```bash
claude /plugin marketplace add ohdearquant/lionagi
```

**Prerequisites:** lionagi (`pip install lionagi` or `uv pip install lionagi`) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed.

See [marketplace/README.md](marketplace/README.md) for the full plugin list and per-plugin install instructions.

## Community

- [Discord](https://discord.gg/JDj9ENhUE8) — questions, ideas, help
- [Issues](https://github.com/ohdearquant/lionagi/issues) — bugs and feature requests
- [Contributing](docs/contributing.md) — PR workflow

**Citation**

```bibtex
@software{Li_LionAGI_2023,
  author = {Haiyang Li},
  year   = {2023},
  title  = {LionAGI: Towards Automated General Intelligence},
  url    = {https://github.com/ohdearquant/lionagi},
}
```
