Pydantic Deep Agents
A self-hosted terminal assistant and Python harness for tool-calling agents on supported models.
- Source repo
- vstorm-co/pydantic-deepagents
- Stars
- ★ 1.1k
- Last updated
- 1mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 68/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude APIClaude Code (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Python team that wants a local terminal coding assistant to inspect a repository, edit files, and run tests.
- Not a fit if
- Teams unwilling to pay extra model costs for parallel fork branches
- Enterprises needing an official production topology and long-term support policy
- Source review
- 68/100 · Some gaps
What does this agent do, and when should you use it?
Pydantic Deep Agents combines a terminal TUI assistant with a Python agent framework built on Pydantic AI. It can run interactively, headlessly through pydantic-deep run for scripts and CI/CD, or as an agent created with create_deep_agent(). Configurable capabilities include filesystem and shell tools, planning, subagents, teams, memory, context compression, checkpoints, MCP, cost controls, and typed output. Execution can use local or Docker-backed environments; Docker supports named workspaces and mounts the project at /workspace. Its Live Run Forking feature branches an in-progress run into isolated alternatives and resolves them through manual, automatic, fallback, or vote-based selection.
An agent created with create_deep_agent() can work on a task using ls, read_file, write_file, edit_file, glob, grep, and execute against its workspace, with optional web search, web fetch, and Playwright browser automation. include_todo, include_plan, include_subagents, and include_teams enable task organization and delegation; MEMORY.md can persist memory, while context_manager summarizes or slides context as it approaches its budget. With forking=True, the agent receives fork_run, inspect_branches, merge_or_select, terminate_branch, diff_branches, and fork_cost; branches use copy-on-write BranchOverlay isolation, and LiveForkCapability(test_command="pytest -q") can use test exit codes in selection. Results are presented as streaming chats, tool calls, and diffs in the Textual TUI, returned as Pydantic-typed values through output_type, or emitted for automation with pydantic-deep run --json.
- A Python team that wants a local terminal coding assistant to inspect a repository, edit files, and run tests.
- An engineering lead running tasks such as fixing a failing test_auth.py test from CI/CD or a script.
- A Python developer adding filesystem, shell, planning, and budget-governed agent behavior to an internal developer tool with create_deep_agent().
- A refactoring team that wants to run pytest -q across competing implementations before selecting a branch.
- An application team coordinating parallel research or code-review work through subagents, shared TODOs, and a message bus.
- An engineering group that needs MCP connections to GitHub, Figma, Context7, DeepWiki, or a custom server.
How do you install or deploy this agent?
On macOS or Linux, run: curl -fsSL https://raw.githubusercontent.com/vstorm-co/pydantic-deep/main/install.sh | bash. For Windows or manual CLI installation, run: pip install "pydantic-deep[cli]"; for framework use, run: pip install pydantic-deep. The README states a Python 3.10+ requirement. Before using the documented Anthropic example, set credentials with: export ANTHROPIC_API_KEY=sk-ant-....
How do you use this agent?
Start the interactive terminal assistant with: pydantic-deep. To choose a model: pydantic-deep tui --model openrouter:anthropic/claude-opus-4-6. For headless use: pydantic-deep run "Fix the failing test in test_auth.py"; add --json for JSON output. In Python: 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"). Use pydantic-deep tui --sandbox docker for the Docker sandbox; browser automation requires pydantic-deep[browser] and pydantic-deep tui --browser.
What are this agent's strengths and limitations?
- It provides an interactive terminal TUI, a headless runner, and the create_deep_agent() library API in one project, spanning direct use and embedded applications.
- Live Run Forking supplies copy-on-write isolated branches, branch budgets, a test-command hook, and four merge modes for comparing verifiable approaches.
- It is built on Pydantic AI and explicitly documents paths for Anthropic, OpenAI, OpenRouter, Gemini, Ollama, and OpenAI-compatible endpoints.
- output_type can return Pydantic models rather than requiring callers to parse JSON, alongside token/USD tracking and budget enforcement.
- Named Docker workspaces, MCP, lifecycle hooks, and default_security_hook() address controlled execution and external-tool integration.
- Its core behavior requires a model that supports tool calling, while model APIs, network access, and credentials are the deployer's responsibility.
- The supplied material explicitly requires Python 3.10+; Docker sandboxing and Playwright browser automation add Docker and browser-related dependencies.
- Live Run Forking executes parallel branches and can assign each a budget, so adoption requires planning for additional model-call and test-execution cost.
- The default security hook is documented to block destructive shell commands, path traversal, and secret leaks, but its fit with an organization's security policy must be validated.
- The material provides installation and usage examples but does not specify a production deployment topology, long-term support policy, or a complete provider-authentication matrix.
How does this agent compare with similar options?
The README compares the project with Claude Code, Aider, LangGraph, and CrewAI, positioning it as a combination of terminal assistant, Python framework, model choice, and Live Run Forking. Claude Code has a terminal experience and MCP in that comparison, while the README presents run branching and a Python framework as Pydantic Deep differentiators; LangGraph and CrewAI are positioned more as frameworks. Choose based on the need for a TUI, branch resolution, and Pydantic AI integration rather than treating cross-project feature markings as independently verified.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Pydantic Deep Agents This agent | 68 · Some gaps | CLIFree + model costs | ★ 1.1k | 1mo ago | Python | OpenAI API · Claude API |
| Marvin – A Python Framework for AI Workflows | 45 · Major gaps | Library / SDKFree + model costs | ★ 6.2k | 9d ago | Python | OpenAI API |
| Agents Towards Production | Insufficient evidence | Library / SDKFree + model costs | ★ 22k | 4d ago | Jupyter Notebook | — |
| gptme Terminal Agent | 66 · Some gaps | CLIFree + model costs | ★ 4.5k | today | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: tool approval dialogs (approve/auto-approve/deny), default security hook blocks destructive commands, Docker sandbox isolation, budget limits, type-safe inputs. Deductions: data flow transparency insufficient, no detailed logging/audit of tool calls; source attribution only via author field, publisher identity unverified.
Evidence shows: extensive test coverage, CI includes lint, typecheck, tests, security scan, dependency version constraints. Deductions: no specific failure message examples, dependency availability not verified (static review).
Evidence shows: targets developers and end-users, provides CLI and framework usage, supports multiple models and providers, broad scenarios. Deductions: capability boundaries not precisely described, trigger conditions (e.g., forking) not detailed.
Evidence shows: README well-structured, install instructions detailed, MIT license clear, CHANGELOG and versioning present. Deductions: known limitations not explicitly listed, maintenance responsibility unclear (publisher unverified).
Evidence shows: type-safe outputs, structured output, high marginal value (unique features like forking). Deductions: cost-benefit not quantified, actual runtime performance not verified.
Evidence shows: README claims partially correspond to code and tests, test files verify some functionality. Deductions: insufficient cross-source corroboration, relies solely on single repository evidence.
- Publisher identity unverified, treat source with caution.
- Data flow transparency insufficient, tool call audit logs not explicit.
- Known limitations not listed, potential issues may be hidden.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Fixed - **Context compression used a different provider when model was a Model instance.** Only a model string was inherited, so an agent built on, say, an OpenAIChatModel for an OpenAI-compatible gateway summarized with DEFAULT_SUMMARIZATION_MODEL - a provider the deployment may have no key for. summarization_model now defaults to the primary model either way, and accepts a Model instance itself.View on GitHub ↗ -
Release notes excerpt
Added - The CLI's /model picker lists local models under "Local (discovered)": the models Ollama has pulled, and what an OpenAI-compatible server (llama.cpp, LM Studio, vLLM) serves at {base_url}/models. Discovery runs in the background with a two-second timeout; a server that is down adds nothing. ([#216](https://github.com/vstorm-co/pydantic-deepagents/issues/216)) - Messages from outside the terminal into a live CLI session. pydantic-deep tui --listen accepts messages on a loopback HTTP endpoint …View on GitHub ↗ -
Release notes excerpt
Added - memory_namespace= on create_deep_agent and DeepAgentSpec: a segment between memory_dir and the agent's name, fixed or resolved per run (a user id, say), for several users sharing one workspace. The model never sees it. Each /-separated part is letters, digits, _, - and .; a fixed one that is not is refused when the agent is built. - build_memory_capability(), which builds the Memory capability the way create_deep_agent does. Changed - Memory is the pydantic-ai-harness Memory capability. Each agent keeps a …View on GitHub ↗