# Pydantic Deep Agents

> Open-source terminal AI assistant and Python framework for building autonomous agents with filesystem, shell, memory, sub-agents, and run forking on Pydantic AI.

Pydantic Deep Agents is an MIT-licensed project from Vstorm that ships both a terminal AI assistant and a Python framework built on Pydantic AI. A single `create_deep_agent()` call gives a model a filesystem, shell, planning, web search, persistent memory, sub-agents, and automatic context management. It works with Claude, GPT, Gemini, local models via Ollama, and other models Pydantic AI supports.

## What It Is

The project is an agent harness: the model supplies the reasoning, and the harness supplies tools, memory, sandboxed execution, and long-conversation handling. It can be used in two ways. The first is a Claude Code-style terminal UI (`pydantic-deep`) that runs on a model of your choice. The second is a Python library, installed with `pip install pydantic-deep`, for building your own assistant, research agent, or coding tool. Any async, type-hinted Python function can be added as a custom tool, with the agent's typed dependencies injected.

## How the Agent Works

Built-in capabilities include file read/write/edit, grep and glob, shell execution, web search and fetch, and browser automation through Playwright. Planning uses a todo list, with an optional plan mode in which a planner subagent asks clarifying questions before execution. Sub-agents handle delegated tasks, and agent teams share TODO lists and a message bus. Skills load on demand from SKILL.md files. Memory persists across sessions in MEMORY.md. Long conversations are summarized, and large tool outputs are evicted to files.

## Live Run Forking

The README presents live run forking as its signature feature. An in-flight run splits into parallel branches, each with a copy-on-write filesystem overlay, its own steering message, and its own budget cap. The branches are then merged in one of four modes: manual, auto, auto_with_fallback, or vote. An AI judge can weigh quality, test results, and consistency. Forking is enabled with `forking=True` or via `/fork` and `/merge` in the CLI.

## Safety, Control, and Integrations

Docker sandboxing with named workspaces, per-tool approval dialogs, and human-in-the-loop workflows are documented. Lifecycle hooks include a security preset that blocks destructive commands. Cost tracking enforces token and USD budgets, and fallback models retry on API errors. MCP servers such as GitHub, Figma, and Context7 can be connected, and LiteParse parses PDFs, Office documents, and images locally. The repo also includes a DeepResearch reference web app and an ACP adapter for Zed.

## Features
- Terminal TUI assistant
- create_deep_agent() Python framework
- Live run forking with AI judge
- Filesystem, shell, grep and glob tools
- Web search and fetch
- Browser automation via Playwright
- Docker sandbox execution
- Sub-agents and agent teams
- Plan mode
- Persistent memory (MEMORY.md)
- Automatic context summarization
- Skills from SKILL.md files
- MCP client support
- Lifecycle hooks and security preset
- Cost tracking and budgets
- Fallback models
- Checkpoints and session rewind
- Structured output via Pydantic models
- Document parsing with LiteParse
- Headless runner for CI/CD

## Integrations
Pydantic AI, Anthropic Claude, OpenAI, Google Gemini, OpenRouter, Ollama, Docker, Playwright, MCP servers, GitHub, Figma, Context7, DeepWiki, Tavily, Brave, Zed (ACP), Kubernetes, Daytona

## Platforms
WINDOWS, MACOS, LINUX, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
0.3.50

## Links
- Website: https://vstorm-co.github.io/pydantic-deepagents/
- Documentation: https://vstorm-co.github.io/pydantic-deepagents/
- Repository: https://github.com/vstorm-co/pydantic-deepagents
- EveryDev.ai: https://www.everydev.ai/tools/pydantic-deep-agents