lionagi: agent orchestration where the CLI is a model endpoint

Three descriptions for one package

The repository calls lionagi an intelligence orchestra, pyproject.toml calls it An Intelligence Operating System., and the README calls it a governed multi-agent orchestration framework built continuously since 2023. All three describe the same 0.35.2 package on PyPI, and the version in pyproject.toml matches the newest tag, v0.35.2, released on 25 August 2026 after v0.35.1 the same day and v0.35.0 on 12 August. The published surface is broad: requires-python is >=3.10 with classifiers running through 3.13, and the dependency list is mostly plumbing, aiocache, anyio, msgspec, orjson, psutil, tiktoken, pydantic-settings, sqlalchemy with asyncio extras and aiosqlite. The homepage is khive.ai while the documentation site is ohdearquant.github.io/lionagi. Root files show how the project is worked on: uv.lock, .pre-commit-config.yaml, .coveragerc, mkdocs.yml for the docs build, and separate trees for apps/, benchmarks/, cookbooks/, notebooks/, tests/ and lionrs/.

The provider CLI is the endpoint, not a REST call

The part that changes how you build is the model alias. A name like claude or codex in li commands spawns that provider's own command-line tool as a subprocess, which means an existing claude login subscription works with no API key at all. The Providers section states the rule plainly: CLI aliases spawn subprocess tools, not REST API calls. Claude Code can be installed and used with claude login, or you can export ANTHROPIC_API_KEY, while codex requires a ChatGPT Plus or Pro subscription. API providers take the usual environment keys, and .env.example lists OPENAI_API_KEY, PERPLEXITY_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY and EXA_API_KEY alongside it. In Python the same split appears in the constructor, where chat_model takes strings such as codex/gpt-5.5 or openai/gpt-5.4.

Fan-out and DAG flow are different commands

Three CLI shapes cover most work. A single agent is li agent with a prompt. li o fanout runs N workers in parallel, with -n 3 and --with-synthesis adding a synthesis pass over their answers. li o flow hands the job to an orchestrator that plans a DAG of specialists, where workers run as dependencies resolve, and --cwd . points it at the directory to inspect.

li o fanout claude/sonnet "Identify code smells in this codebase" -n 3 --with-synthesis
li play audit --mode security "the auth service"

The Concepts table keeps the vocabulary small: a Branch is one conversation thread with message history, tools and model config; a Session coordinates several Branches and runs DAG workflows across them. Beyond those, li play runs a parametric flow spec stored at ~/.lionagi/playbooks/audit.playbook.yaml, li team send and li team receive give agents a persistent inbox, and examples/ ships installable playbook and skill templates.

A run is a directory you can reopen

Every run persists under ~/.lionagi/runs/, keyed by run id, and the same fact is what makes the framework inspectable rather than opaque. Conversations are collections of typed messages with an explicit ordering, and state serializes, persists and resumes instead of hiding inside a chain. On the CLI that turns into four verbs: li agent -r resumes a branch by id and takes a follow-up instruction, -c reattaches, li monitor watches live work, and li schedule sets up recurring runs. In Python the entry point is Branch, either b.communicate for plain chat or b.operate with a pydantic model as response_format, which returns the parsed object rather than text you have to scrape.

Two watchdogs, two different retry rules

The .env.example documents the failure modes a subprocess endpoint actually has, and the two timeouts do not behave alike. LIONAGI_WORKER_LIVENESS_TIMEOUT is the number of seconds run() waits for a CLI worker's first stream chunk before retrying once and then failing with WorkerLivenessError; its default is 120 and 0 disables the watchdog, and by default it applies only to endpoints that stream early, claude_code and codex, leaving buffered endpoints such as gemini_code and pi alone unless liveness_timeout is passed. LIONAGI_WORKER_IDLE_TIMEOUT covers silence between chunks, defaults to 300, resets its window after every chunk, and a miss fails with worker.stream_idle and is never retried, because partial output may already have been consumed. The same file pins aiohttp at 3.14.3 for a CVE in the C response parser and WebSocket frame handling.

Lion Studio is a hosted page talking to your own daemon

The web UI needs no download and no build. Open lion-studio.khive.ai in a browser and that client-side page connects to a local daemon at http://127.0.0.1:8765, with your data staying on your machine and the hosted page acting only as the UI. Four flags decide how the backend comes up, and they are mutually exclusive: li studio on its own starts the daemon and opens the hosted page, li studio --docker is self-contained and auto-pulls ghcr.io/ohdearquant/lion-studio for UI and API on http://localhost:8765, li studio --no-frontend gives you the backend API alone, and li studio --dev runs the in-repo frontend with hot reload from a source checkout. --web is the default when no flag is given, and --no-open skips opening the browser.

SQLite by default, a throwaway Postgres 16 for the tests

State has two backends and the test targets show both. test-sqlite runs the StateDB tests on the default SQLite backend across tests/state, tests/apps_studio_server, tests/cli and tests/hooks. test-pg and test-dual need a database that pg-up starts for you: a container named lionagi-pg-test from postgres:16-alpine, mapped to host port 5433, with POSTGRES_PASSWORD=lionagi and POSTGRES_DB=lionagi_state, reachable at postgresql+asyncpg://postgres:lionagi@localhost:5433/lionagi_state. The target waits up to sixty half-second probes with pg_isready and exits with postgres did not become ready if the container never answers, and pg-down removes it. Linting is Ruff for both check and format, with pytest behind test-python, and the composite targets all shell out to scripts/ci.sh.

Guard hooks and worktrees, not just permissions

Governance is the part that separates this from a thin wrapper over a model call, and it is built from three pieces. Permission policies apply per tool call. Guard hooks block destructive commands and paths you have marked off limits before the call runs. Git-worktree sandboxing puts speculative edits in a worktree that never touches your branch until you merge it. The examples directory shows the same machinery at the level of its internals, with hook_bus.py, capability_bus_demo.py, reactive_spawn.py, casts_composition.py, pile_and_types.py, coding_agent.py, engine_lifecycle.py, event_lifecycle.py and orchestration_fanout.py alongside playbooks/ and skills/ folders. Root files for agent-facing work include AGENT.md, CLAUDE.md and a .claude-plugin/ directory, and the Makefile lints marketplace/ through its own lint-marketplace target.

Editorial conclusion

lionagi fits a Python team that already pays for a coding CLI subscription and wants those same agents inside a workflow, since `claude` and `codex` aliases spawn the real binaries and a `claude login` session is enough. It does not fit a team that wants a hosted control plane or a batteries-included runtime, because branches, sessions and flows are plain objects you assemble yourself and Lion Studio is only a UI over a daemon on 127.0.0.1:8765. Before you build on it, read the two watchdog variables: LIONAGI_WORKER_LIVENESS_TIMEOUT decides whether a silent CLI worker gets one retry, and LIONAGI_WORKER_IDLE_TIMEOUT decides whether a half-finished answer is thrown away, so set both for the slowest endpoint you plan to use rather than leaving the 120 and 300 second defaults.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. ohdearquant/lionagi on GitHub
3. Project website
4. README
5. Releases