Pydantic Deepagents
Open-source, self-hosted Claude Code - a terminal AI assistant and the Python framework behind it. Tool-calling, sandboxed execution, multi-agent teams, skills, checkpoints, unlimited context - on Pydantic AI, any model.
Install / Use
npx skills add vstorm-co/pydantic-deepagentsInstalls into whichever agent you are using.
Quality Score
Category
Development & EngineeringSupported Platforms
README
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-deep/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 | — | ✅ | ✅ | ✅ |
<sub>✅ first-class · ~ partial / via extensions · — not available · DIY you wire it yourself. Comparison reflects each project as of 2026-06; corrections welcome via PR.</sub>
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-write isolation, per-branch budgets, a test-runner hook, and four merge modes (manual/auto/auto_with_fallback/vote). Opt in withforking=True. - 2026-06-01 v0.3.23 — MCP client support (framework + CLI). Connect GitHub, Figma (OAuth), Context7, DeepWiki, or any custom server. Import servers straight from Claude Code. New interactive
/mcpcommand. Plus a full CLI presentation pass: clipboard image paste, real+/-diffs, tool icons, turn summaries. - 2026-06-01 v0.3.23 — Automatic fallback-model retry —
fallback_model=wraps your primary in aFallbackModelchain; fires on API errors but never on auth errors. Plus a batteries-included security hook preset (default_security_hook()) and three new output styles (markdown,json-only,bullet). - 2026-04-22 v0.3.17 — LiteParse document parsing (
include_liteparse=True) — PDFs, DOCX, XLSX, PPTX, and images with optional OCR, all local. - 2026-04-10 v0.3.5 — Headless runner (
pydantic-deep run), Docker sandbox with named workspaces, browser automation via Playwright.
Full history: CHANGELOG.md
The Agent Harness
Pydantic Deep Agents is an agent harness — the complete infrastructure that wraps an LLM and makes it a functional autonomous agent. The model provides intelligence; the harness provides planning, tools, memory, sandboxed execution, unlimited context, and — uniquely — the ability to fork.
<table> <tr> <td><b>⑂ Live run forking</b></td> <td>Split a run into N isolated branches, each trying a different approach. AI judge or test results pick the winner. <b>No other agent framework has this.</b></td> </tr> <tr> <td><b>🔧 Tool-calling</b></td> <td>File read/write/edit, shell execution, glob, grep, webRelated Skills
node-connect
385.5kDiagnose OpenClaw Android, iOS, or macOS node pairing, QR/setup code, route, auth, and connection failures.
python-debugpy
385.5kDebug Python with pdb, breakpoint(), post-mortem inspection, and debugpy remote attach.
skill-creator
385.5kCreate, edit, audit, tidy, validate, or restructure AgentSkills and SKILL.md files.
browser-automation
385.5kUse when controlling web pages with the OpenClaw browser tool, especially multi-step flows, login checks, tab management, or recovery from stale refs/timeouts.
