Skip to content

Resumable Background Runs

Long flows finish while you sleep. li o flow --background detaches immediately and writes all progress to a log file. Resume any branch afterward with li agent -r.

Setup

pip install lionagi          # or: uv add lionagi
# claude — Option A (subscription): npm install -g @anthropic-ai/claude-code && claude login
#          Option B (API key):      export ANTHROPIC_API_KEY="sk-ant-..."

Launch

--background requires --save.

li o flow claude/sonnet \
  "Audit the auth module, find security gaps, draft fixes" \
  --background --save ./auth-audit

# output:
Flow running in background (PID 84231)
Output: auth-audit/flow.log
Monitor: tail -f auth-audit/flow.log

The parent exits immediately. The subprocess runs the full flow and writes all output to auth-audit/flow.log.

Monitor progress

tail -f ./auth-audit/flow.log

# output:
Planning DAG...
Plan done (1.8s): 3 agents, 3 ops — o1:r1 | o2:i1 ← o1 | o3:rv1 ← o2
Executing DAG: 3 agents / 3 ops...
  ▶ r1 started
  ✓ r1 done (9.4s)
[...4 more lines...]
Saved to /Users/you/auth-audit
Total: 47.2s

Find branch IDs

Branch snapshots land under ~/.lionagi/runs/<run_id>/branches/. Read the run manifest:

cat ~/.lionagi/runs/$(ls -t ~/.lionagi/runs/ | head -1)/run.json

# output:
{
  "run_id": "20260420T140312-a1b2c3",
  "kind": "flow",
  "branches": [
    {"id": "b7f2a1e3...", "provider": "anthropic"},
    {"id": "c4d8e9f0...", "provider": "anthropic"}
  ]
}

Resume a branch

# prefix match — full id not required
li agent -r b7f2a1 "Which gaps are highest severity?"

# continue the most recently used branch — no id needed
li agent -c "Add rate-limit tests for the two critical gaps."

# output:
The highest-severity gaps in the auth module are:
1. Missing expiry check on /api/auth/refresh — token replay window is unlimited
2. Legacy session cookie sent without Secure flag on HTTP endpoints

Run directory layout

~/.lionagi/runs/<run_id>/
  run.json                           # manifest: command, branches, artifact_root
  branches/<branch_id>.json          # branch snapshot — restore point for -r
  stream/<branch_id>.buffer.jsonl    # live chunk buffer during stream

<--save dir>/
  flow.log                           # all stdout from the background subprocess
  flow_dag.png                       # DAG render (only with --show-graph)
  <agent_id>/                        # per-agent working directories

Deleting the --save directory does not break resume — branch snapshots are always in ~/.lionagi/runs/.

LIONAGI_RUN_ID

Set this env var to group separate CLI invocations under the same run directory:

export LIONAGI_RUN_ID=20260420T140312-a1b2c3
li agent claude/sonnet "Write integration tests for the auth fixes"

The new agent's snapshot lands in ~/.lionagi/runs/20260420T140312-a1b2c3/branches/ alongside the background flow's branches. The subprocess itself checks LIONAGI_RUN_ID on startup via allocate_run() — set it before launching background flows you want grouped.

Next