pydantic-deepagents: a self-hosted Claude Code and the Python harness under it

The two products sharing one repository

The README opens by calling the project two things in one repo, and that framing is accurate rather than marketing. The first is a terminal assistant: a TUI that plans, edits files, runs commands, searches the web, keeps memory across sessions, spawns sub-agents and connects to MCP servers. The second is the Python framework behind that assistant, exposed as create_deep_agent(), which hands a model a filesystem, a shell, planning, memory, sub-agents, sandboxed execution, MCP and what the README calls unlimited context. Both run on Pydantic AI and both are MIT-licensed. The audience splits accordingly. If you want a coding assistant you can point at a local or non-Anthropic model, you install the CLI and never write Python. If you are building a research agent or an internal coding tool and you do not want to re-implement filesystem access, shell execution and sub-agent orchestration, you import the package. The overlap matters: the README states the framework is the exact same harness behind the CLI, so behaviour you observe in the terminal is meant to be reproducible from Python. That claim is worth treating as a design intent to verify rather than a guarantee, since the CLI adds a TUI layer the framework call does not include.

What create_deep_agent() actually hands the model

The framework entry point is a single function. The README example is short: import create_deep_agent from pydantic_deep, call it with model set to an anthropic model string, then await agent.run() with a prompt. Everything else is assembled by the factory. According to the README, that assembly includes a filesystem, a shell, planning, memory, sub-agents, sandboxed execution, MCP connectivity and unlimited context. The model string is a Pydantic AI model identifier, which is where the any model claim comes from: Claude, GPT, Gemini and local models are all listed as supported. Type safety is the other stated property, described as 100 percent type-safe, which follows from building on Pydantic AI rather than wrapping raw HTTP calls. The practical consequence is that you get a deep agent without writing tool definitions for file operations or shell commands. The trade-off is that the factory's defaults are the contract. The README does not enumerate every default in the excerpt available here, so if you need to know exactly which tools are registered and with what permissions, you have to read the source or the linked documentation rather than the README alone.

Live Run Forking and the copy-on-write overlay

This is the feature the repository leads with, and the mechanism is more concrete than the slogan. When an agent reaches a decision point, the run branches into parallel alternatives. The README diagram shows three branches from one shared history: use a decorator, use a context manager, extract a base class. Each branch carries a steering message, its own budget_usd cap, and a fully isolated copy-on-write filesystem overlay where reads fall through to the parent and writes stay local. That isolation is what makes the comparison meaningful. Branch B's failed edits cannot contaminate branch A's working tree, and the shared history means you are not paying to re-derive context in each branch. A coordinator then resolves the fork using one of four acceptance modes: manual, auto, auto_with_fallback (the default), or vote. The winning branch's history becomes the parent run's continuation. The confidence formula is stated explicitly when a test command is configured: quality_spread times 0.4, plus test_pass_ratio times 0.4, plus internal_consistency times 0.2. That weighting is a design choice worth noticing. Tests and judged quality carry equal weight at 0.4 each, so a branch that passes every test but reads badly can still lose to a branch that passes slightly fewer and scores higher on the judge. If your acceptance criteria are test-driven, the default weighting may not match your intent.

Installing the CLI versus installing the library

The two paths are genuinely separate. For the assistant, the README gives a curl command against install.sh on the main branch, piped to bash, followed by running pydantic-deep. The script is described as installing uv and the CLI for you, so no Python setup is required on the target machine. The manual route for Windows or anyone who prefers explicit package management is pip install with the cli extra: pip install "pydantic-deep[cli]". Note that the distribution name on PyPI is pydantic-deep, not pydantic-deepagents, which is the repository name. For the framework, the command is pip install pydantic-deep with no extra. Python 3.10 or later is required per the badge. Once inside the TUI, forking is driven by slash commands: /fork splits the current run into N parallel branches, >>A and >>B steer individual branches, /merge resolves the fork through a manual picker, an AI judge, or a vote, and /fork-config sets branch count, budgets, per-branch models and merge strategy. In the framework, forking is opt-in through a flag: create_deep_agent with forking=True registers fork_run, inspect_branches, merge_or_select, diff_branches, fork_cost and terminate_branch. Passing a LiveForkCapability object instead lets you supply test_command and test_timeout_s, which is what activates the exit-code-driven scoring described above.

Where the forking model breaks down

Forking costs money by construction. Each branch has its own budget_usd cap, and the caps are per branch, not shared, so a three-branch fork with generous caps can spend three times what a single run would. The README presents the cap as a control, and it is, but the control is per branch, which means your total exposure scales with branch count. That is the first limitation. The second is the judge itself. The confidence formula includes internal_consistency at 0.2, which means the scoring depends on a model's assessment of its own outputs. The README does not explain how internal_consistency is computed in the excerpt available, and that opacity matters if you intend to run forking unattended. The third is the default acceptance mode. auto_with_fallback is the default, and the name implies a fallback path when the preferred resolution fails, but the README excerpt does not specify what the fallback is or when it triggers. If you are running forking in CI with no human watching, that unspecified behaviour is the thing to pin down before trusting it. Finally, forking is the wrong tool for work with a single correct answer. If the task is to fix a typo or apply a known migration, branching into three approaches burns budget to compare options that were never in doubt.

How it differs from LangGraph and CrewAI

The README states directly that Claude Code, Aider, LangGraph and CrewAI cannot do Live Run Forking, and names it as the reason to use pydantic-deep. Taking that at face value, the difference is architectural rather than cosmetic. LangGraph and CrewAI are frameworks for composing agents into graphs and crews; you define the topology, the nodes and the edges, and you decide where control flows. pydantic-deepagents inverts that. create_deep_agent() gives you a preassembled agent with filesystem, shell, planning, memory and sub-agents already wired, and the branching is a runtime capability the agent invokes on itself through fork_run rather than a graph structure you author. The copy-on-write overlay is the part that would be hardest to replicate in a graph framework, because it requires the execution environment to support cheap filesystem snapshots per branch. If you already have a LangGraph application with carefully tuned nodes, this project is not a drop-in replacement and the forking feature does not transfer. If you are starting fresh and the branching behaviour is what you want, building it on a graph framework means implementing the overlay yourself. The honest comparison is that these solve different problems: graph frameworks give you control over composition, and this gives you a working agent plus one capability that depends on the harness underneath.

Release cadence, licence and what to check first

The three most recent releases are 0.3.41 and 0.3.42 on 2026-08-01 and 0.3.43 on 2026-08-05. Two releases on the same day, then another four days later. For a project at version 0.3.x, that cadence is the clearest signal in the supplied material: the API is still being shaped, and pinning a version is reasonable if you are building on the framework rather than just running the CLI. The last push to the default branch is 2026-08-22, which is after the most recent release, so development is active. The licence is MIT, which permits commercial and closed-source use and modification, but this is not legal advice and you should read the LICENSE file in the repository yourself, particularly if you redistribute the CLI. The README links a SECURITY.md and a security policy badge, and the topics list includes docker-sandbox, which suggests sandboxed execution is a first-class concern rather than an afterthought. The repository also carries an OpenSSF Best Practices badge. None of that substitutes for reading how the sandbox is configured, because a coding agent with shell access is a meaningful privilege boundary. Before adopting, check the sandbox defaults, confirm which models you can actually reach through Pydantic AI in your environment, and decide whether you want forking enabled by default or only in specific workflows.

Editorial conclusion

Adopt the CLI if you want a Claude-Code-style terminal assistant that runs against a model you choose, and adopt the framework if you need sub-agents, sandboxed execution or MCP inside an existing Pydantic AI codebase. Skip it if you need a stable API surface right now: 0.3.41, 0.3.42 and 0.3.43 all landed within August 2026, which tells you the interfaces are still moving. Before wiring it into anything you depend on, verify three things against your own checkout: that create_deep_agent() accepts your model string through Pydantic AI, that the copy-on-write overlay behaves correctly against your repository layout, and what the default auto_with_fallback acceptance mode does when every branch fails its test command.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. vstorm-co/pydantic-deepagents on GitHub