| β Live run forking |
Split a run into N isolated branches, each trying a different approach. AI judge or test results pick the winner. No other agent framework has this. |
| π§ Tool-calling |
File read/write/edit, shell execution, glob, grep, web search, web fetch, browser automation β wired up and ready. |
| π€ Multi-agent / swarm |
Spawn subagents for parallel workstreams. Shared TODO lists with claiming. Peer-to-peer message bus. Full team coordination. |
| π§ Persistent memory |
MEMORY.md persists across sessions. Auto-injected into the system prompt. Each agent has isolated memory by default. |
| βΎοΈ Unlimited context |
Auto-summarization when approaching the token budget. LLM-based or zero-cost sliding window. Never hits a context wall. |
| π³ Sandboxed execution |
Docker sandbox with named workspaces. Installed packages persist between sessions. Project dir mounted at /workspace. |
| ποΈ Plan Mode |
Dedicated planner subagent asks clarifying questions and structures the work before execution begins. Headless-compatible. |
| π Checkpoints |
Save conversation state at any point. Rewind to any checkpoint. Fork sessions to explore alternative approaches. |
| π Skills system |
Domain-specific knowledge loaded on demand from SKILL.md files. Built-in: code-review, refactor, test-writer, git-workflow, and more. |
| π Document parsing |
Parse PDFs, DOCX, XLSX, PPTX, and images with optional OCR via LiteParse. Runs locally β no cloud services required. |
| π MCP |
Connect any Model Context Protocol server β GitHub, Figma (OAuth), Context7, DeepWiki, or custom. Import straight from Claude Code. |
| β‘ Lifecycle hooks + security preset |
Claude Code-style PRE/POST_TOOL_USE hooks. Shell or Python handlers. default_security_hook() blocks destructive commands out of the box. |
| π Structured output |
Type-safe Pydantic model responses via output_type. No JSON parsing. No dict["key"]. Full IDE autocomplete. |
| π Fallback models |
Primary model fails? fallback_model= hops to the next in the chain β on API errors, never on auth errors. |
| π Stuck loop detection |
Detects repeated identical tool calls, A-B-A-B alternating patterns, and no-op calls. Warns the model or stops the run. |
| π° Cost tracking |
Real-time token and USD cost tracking per run and cumulative. Hard budget limits with BudgetExceededError. |
| β¨ Self-improving |
/improve analyzes past sessions and proposes updates to MEMORY.md, SOUL.md, and AGENTS.md. |
| π·οΈ 100% type-safe |
Pyright strict + MyPy strict. 100% test coverage. Every public API is fully typed β safe to use in production. |
Built natively on **[pydantic-ai](https://github.com/pydantic/pydantic-ai)** β uses the Capabilities API directly, inherits all pydantic-ai streaming, multi-model support, and Pydantic validation automatically.
---
## π₯οΈ CLI β Terminal AI Assistant
A Claude Code-style terminal AI assistant that works with **any model and any provider** β and forks.
### Install (macOS & Linux)
```bash
curl -fsSL https://raw.githubusercontent.com/vstorm-co/pydantic-deepagents/main/install.sh | bash
```
No Python setup required β the script installs uv and the CLI automatically. Then:
```bash
export ANTHROPIC_API_KEY=sk-ant-...
pydantic-deep
```
> **Windows / manual:** `pip install "pydantic-deep[cli]"` Β· **Update:** `pydantic-deep update`
### Model & Provider Support
Works with any model that supports tool-calling:
| Provider | Example models |
|----------|----------------|
| **Anthropic** | `anthropic:claude-opus-4-6`, `claude-sonnet-4-6` |
| **OpenAI** | `openai:gpt-5.4`, `gpt-4.1` |
| **OpenRouter** | `openrouter:anthropic/claude-opus-4-6` (200+ models) |
| **Google Gemini** | `google-gla:gemini-2.5-pro` |
| **Ollama (local)** | `ollama:qwen3`, `ollama:llama3.3` |
| **Any OpenAI-compatible** | Custom base URL via env |
Switch model anytime: `pydantic-deep config set model openai:gpt-5.4` or `/model` in the TUI.
### What you get in the TUI
| | Feature |
|:-:|---------|
| β | **Live run forking** β split a run into branches, stream them side by side, merge the winner |
| π¬ | Streaming chat with tool call visualization, icons, and real `+/-` diffs |
| π | File read / write / edit, shell execution, glob, grep |
| π€ | Task planning, plan mode, and subagent delegation |
| π§ | Persistent memory and self-improvement across sessions |
| βΎοΈ | Context compression for unlimited conversations |
| π | Checkpoints β save, rewind, and fork any session |
| π | MCP servers via `/mcp` β GitHub, Figma (OAuth), and more; import from Claude Code |
| π | Web search & fetch built-in Β· π₯οΈ browser automation via Playwright (`--browser`) |
| π³ | Docker sandbox β sandboxed execution with named workspaces |
| π | Extended thinking β `minimal` / `low` / `medium` / `high` / `xhigh` |
| π | Clipboard image paste (`Ctrl+V` / `/paste`) β multimodal prompts |
| π° | Real-time cost and token tracking per session |
| π‘οΈ | Tool approval dialogs β approve, auto-approve, or deny per tool call |
| @ | `@filename` file references Β· `!command` shell passthrough |
| β¨ | `/fork`, `/merge`, `/improve`, `/skills`, `/mcp`, `/model`, `/theme`, `/compact`, and more |
### Usage
```bash
# Interactive TUI (default)
pydantic-deep
pydantic-deep tui --model openrouter:anthropic/claude-opus-4-6
# Headless deep agent β benchmarks, CI/CD, scripted automation
pydantic-deep run "Fix the failing test in test_auth.py"
pydantic-deep run --task-file task.md --json
# Docker sandbox β sandboxed execution, project dir mounted at /workspace
pydantic-deep tui --sandbox docker
pydantic-deep tui --workspace ml-env # named workspace, packages persist
# Browser automation (requires pydantic-deep[browser])
pydantic-deep tui --browser
# Config & skills
pydantic-deep config set model anthropic:claude-sonnet-4-6
pydantic-deep skills list
pydantic-deep update # update to latest version
```
> See [CLI docs](docs/cli/index.md) for the full reference.
---
## π Framework β Build Your Own Agent
```bash
pip install pydantic-deep
```
One function call gives you a production deep agent with planning, tool-calling, multi-agent delegation, persistent memory, unlimited context, forking, and cost tracking. Everything is a toggle:
```python
from pydantic_deep import LocalWorkspace, create_deep_agent, create_default_deps
agent = create_deep_agent(
model="anthropic:claude-sonnet-4-6",
workspace=LocalWorkspace("."), # where it works: memory (default), disk, Docker, β¦
forking=True, # β split a run into parallel branches + AI judge
include_todo=True, # Task planning with subtasks and dependencies
include_subagents=True, # Multi-agent swarm β delegate to subagents
include_skills=True, # Domain-specific skills from SKILL.md files
include_memory=True, # Persistent memory across sessions
include_plan=True, # Structured planning before execution
include_teams=True, # Agent teams with shared TODO lists + message bus
include_liteparse=True, # Document parsing β PDF, DOCX, XLSX + OCR
web_search=True, # Tool-calling: web search
thinking="high", # Extended thinking / reasoning effort
context_manager=True, # Unlimited context via auto-summarization
cost_tracking=True, # Token/USD budget enforcement
fallback_model="openai:gpt-5.4", # auto-retry if the primary model fails
include_checkpoints=True, # Save, rewind, and fork conversations
)
deps = create_default_deps()
result = await agent.run("Build a REST API for user auth", deps=deps)
```
### Structured Output
Type-safe responses with Pydantic models β no JSON parsing, no `dict["key"]`:
```python
from pydantic import BaseModel
class CodeReview(BaseModel):
summary: str
issues: list[str]
score: int
agent = create_deep_agent(output_type=CodeReview)
result = await agent.run("Review the auth module", deps=deps)
print(result.output.score) # fully typed
```
### Multi-Agent Swarm
Spawn isolated subagents for parallel workstreams. Each subagent is a full deep agent with its own tool-calling, memory, and context:
```python
agent = create_deep_agent(
subagents=[
{
"name": "researcher",
"description": "Researches topics using web search",
"instructions": "Search the web, synthesize findings, cite sources.",
},
{
"name": "code-reviewer",
"description": "Reviews code for quality, security, and performance",
"instructions": "Check for security issues, N+1 queries, missing tests...",
},
],
)
# Main agent delegates: task(description="Review auth.py", subagent_type="code-reviewer")
```
### Claude Code-Style Lifecycle Hooks + Security Preset
```python
from pydantic_deep import create_deep_agent, default_security_hook, Hook, HookEvent
agent = create_deep_agent(
hooks=[
*default_security_hook(), # blocks destructive shell, path traversal, secret leaks
Hook(
event=HookEvent.PRE_TOOL_USE,
command="echo 'Tool: $TOOL_NAME args: $TOOL_INPUT' >> /tmp/audit.log",
),
],
)
```
### MCP Servers
Connect GitHub, Figma (OAuth), Context7, DeepWiki, or any custom server β auth handled for you:
```python
from pydantic_deep import create_deep_agent, build_mcp_server, MCPServerConfig
deepwiki = build_mcp_server(
MCPServerConfig(name="deepwiki", transport="http", url="https://mcp.deepwiki.com/mcp")
)
agent = create_deep_agent(mcp_servers=[deepwiki]) # curated defaults via builtin_mcp_servers()
```
### Context Files
Pydantic Deep Agents auto-discovers and injects project-specific context into every conversation:
| File | Purpose | Who Sees It |
|------|---------|-------------|
| `AGENTS.md` | Project conventions, architecture, instructions | Main agent + all subagents |
| `CLAUDE.md` | Claude Code project instructions | Main agent + all subagents |
| `SOUL.md` | Agent personality, style, communication preferences | Main agent only |
| `.cursorrules` | Cursor editor conventions | Main agent only |
| `MEMORY.md` | Persistent memory β read/write/update tools | Per-agent (isolated) |
Compatible with Claude Code, Cursor, GitHub Copilot, and other agent frameworks. `AGENTS.md` follows the [agents.md spec](https://agents.md/).
> See the full [API reference](https://vstorm-co.github.io/pydantic-deepagents/api/toolsets/) for all options.
---
## π¬ DeepResearch β Reference App
A full-featured research deep agent with web UI β built entirely on Pydantic Deep Agents.
### Need help shipping AI agents in production?
We're Vstorm β an Applied Agentic AI Engineering Consultancy
with 30+ production agent implementations. Pydantic Deep Agents is what we build them with.
Made with **care** by
Vstorm
