pydantic-deepagents

From the team behind this repo: AgenticOS, the Sovereign Agentic AI Layer. AI agents your whole team can use and improve: open source (Apache-2.0), self-hosted, built on Pydantic AI.

Pydantic Deep Agents

Open-source Claude Code — that you can also build on. A self-hosted terminal AI assistant and the Python framework behind it. Use it today, or ship your own agent in one function call. Any model. 100% type-safe. MIT.

Docs · PyPI · Forking · Why · CLI · Framework · Examples

---

Pydantic Deep Agents is two things in one repo:

🖥️ A terminal AI assistant — a self-hosted, open-source alternative to Claude Code. Install it, point it at any model, and it plans, edits files, runs commands, searches the web, remembers across sessions, spawns sub-agents, and connects to MCP servers. Almost everything Claude Code does — on the model you choose.

🐍 A Python framework — the exact same harness behind a single function call. create_deep_agent() hands a model a filesystem, shell, planning, memory, sub-agents, sandboxed execution, MCP, and unlimited context. Build your own assistant, research agent, or coding tool without rewiring the plumbing every time.

Both run on Pydantic AI, work with any model (Claude, GPT, Gemini, local), and are 100% type-safe and MIT-licensed — and they share one trick nothing else has: Live Run Forking, splitting a single run into parallel branches an AI judge merges back together.

Two ways to use it

🖥️ 1. Use the assistant

A Claude-Code-style TUI in your terminal, on any model — no Python setup (the script installs uv + the CLI for you):

curl -fsSL https://raw.githubusercontent.com/vstorm-co/pydantic-deepagents/main/install.sh | bash
pydantic-deep

Windows / manual: pip install "pydantic-deep[cli]"

🐍 2. Build your own

One function call gives you a full deep agent:

pip install pydantic-deep

from pydantic_deep import create_deep_agent

agent = create_deep_agent(model="anthropic:claude-sonnet-4-6")
result = await agent.run("Build a REST API for auth")

---

⑂ Live Run Forking — the feature no one else has

Claude Code can't do this. Aider can't. LangGraph and CrewAI can't. It's the reason to use pydantic-deep.

When an agent hits a fork in the road — "should I refactor this with a decorator or a context manager?" — most tools force one bet. Pydantic Deep Agents lets the run branch:

                                  ┌──  branch A: "use a decorator"      ── tests: 8/8 ✓  conf 0.71
   agent.run("refactor auth") ──┬─┼──  branch B: "use a context manager" ── tests: 6/8 ✗  conf 0.42
       (shared history)         │ └──  branch C: "extract a base class"   ── tests: 8/8 ✓  conf 0.55
                                │
                                └──►  ⚖️  AI judge weighs quality + tests + consistency
                                          → adopts branch A, continues the run

Each branch is fully isolated: a copy-on-write filesystem overlay (reads fall through to the parent, writes stay local), its own steering message, and its own budget_usd cap. The coordinator resolves the fork with one of four acceptance modes — manual, auto, auto_with_fallback (default), or vote — and the winning branch's history is adopted as the parent run's continuation.

Framework — opt in with one flag:

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    forking=True,                 # gives the agent: fork_run, inspect_branches,
)                                 # merge_or_select, diff_branches, fork_cost, terminate_branch

Or run a real test command against every branch and let exit codes decide the winner:

from pydantic_deep import LiveForkCapability

agent = create_deep_agent(
    forking=LiveForkCapability(test_command="pytest -q", test_timeout_s=120),
)
# confidence = quality_spread·0.4 + test_pass_ratio·0.4 + internal_consistency·0.2

CLI — fork an in-flight conversation, watch branches stream live, merge the best:

/fork                 # split the current run into N parallel branches
>>A try a decorator   # steer branch A
>>B use a contextmgr  # steer branch B
/merge                # resolve — manual picker, AI judge, or vote

Live per-branch panels stream each approach side by side; a judge screen scores them; you accept, review the diff, or decline. Configure branch count, budgets, per-branch models, and merge strategy with /fork-config.

📖 Full reference: docs/capabilities/live-fork.md

---

🆚 Why pydantic-deep?

The only tool that is a terminal assistant and a Python framework and can fork its own runs — without giving up type safety or your choice of model.

	Pydantic Deep	Claude Code	Aider	LangGraph	CrewAI
Terminal TUI assistant	✅	✅	✅	—	—
Python framework / library	✅	—	~	✅	✅
Live run forking + AI judge	✅	—	—	—	—
Multi-agent swarm + message bus	✅	~	—	✅	✅
Any model / any provider	✅	Anthropic	✅	✅	✅
Sandboxed Docker execution	✅	—	~	DIY	DIY
Persistent memory + skills	✅	✅	—	DIY	~
Type-safe structured output	✅	—	—	~	~
MCP servers	✅	✅	—	~	~
Self-hosted, open source	✅ MIT	—	✅	✅	✅

✅ first-class · ~ partial / via extensions · — not available · DIY you wire it yourself. Comparison reflects each project as of 2026-06; corrections welcome via PR.

---

What's New

• 2026-06-01  v0.3.24 — Live Run Forking — split an in-flight agent.run() into N parallel branches with copy-on-wri