Skip to content

index.md

Latest commit

 

History

History
115 lines (80 loc) · 5.51 KB

index.md

File metadata and controls

115 lines (80 loc) · 5.51 KB
Raw

CLI — the terminal assistant

pydantic-deep ships its own terminal assistant: a Claude-Code-style coding agent that lives in your shell, built entirely on top of the framework you've been reading about. You run it, it reads and writes your files, runs commands, searches the web, and remembers what you're working on — all inside a rich terminal UI.

It's the same agent you'd assemble with [create_deep_agent][pydantic_deep.create_deep_agent], wrapped in a Textual interface. Nothing is hidden behind a SaaS — it's your code, your machine, your model key.

Install

pip install "pydantic-deep[cli]"

That's the whole install. The [cli] extra pulls in Textual and the TUI dependencies on top of the core framework.

!!! tip "One-line installer" On macOS and Linux you can also run the bootstrap script, which installs uv for you and then does the rest:

```bash
curl -fsSL https://raw.githubusercontent.com/vstorm-co/pydantic-deep/main/install.sh | bash
```

Launch it

From any project directory, just run the command:

$ cd my-project
$ pydantic-deep

The TUI opens. On the very first run it walks you through picking a provider and pasting an API key, then drops you into a chat. Type a request and watch the agent plan, edit files, and run commands live:

$ pydantic-deep

> Find the failing test in tests/ and fix it

  ● write_todos    drafting a 3-step plan
  ● grep           "def test_" in tests/
  ● read           tests/test_auth.py
  ● edit           src/auth.py  (+4 -1)
  ● execute        pytest tests/test_auth.py  ✓ 1 passed

  Fixed it — the token check compared against the wrong field. Tests pass now.

You wrote one sentence. The planning, file editing, shell, and todo tracking all came for free — that's the framework doing the work.

A tour of what it can do

The assistant is the framework's features made interactive. Here's the breadth:

  • Chat with a real coding agent. Streaming responses, visible thinking, and every tool call rendered as it happens — no black box.
  • Files and the shell. It reads, writes, edits, globs, and greps your project, and runs commands. Prefix a line with ! to run a shell command yourself (!git status), or drop @path/to/file into a prompt to pull a file's contents in.
  • Subagents. Big tasks get delegated to focused subagents that work in parallel, so the main thread stays clean.
  • MCP servers. Connect Model Context Protocol servers to give the agent extra tools — databases, issue trackers, your own services. Manage them live with /mcp.
  • Sessions. Every conversation auto-saves. Resume any past one with /load, or manage them from the shell with pydantic-deep threads list.
  • Live forking. Branch a running conversation to explore an alternative without losing your place — /fork to split, /merge to bring a branch back. See Sessions, forking & MCP.
  • Attachments and images. Paste an image straight into the prompt (/paste) and the agent sees it; reference files with @.
  • Themes. Four built-in color themes — switch instantly with /theme ocean.
  • Memory that sticks. /remember saves a note across sessions; /improve reviews past sessions and proposes updates to your AGENTS.md, SOUL.md, and MEMORY.md.

!!! note "Headless too" The same agent runs non-interactively for CI, benchmarks, and scripts:

```bash
pydantic-deep run "Fix the failing test in tests/test_auth.py" --json
```

It prints the result (and usage stats with `--json`) and exits. See
[Commands](commands.md) for the full `run` reference.

!!! tip "Sandbox it" Add --sandbox docker to either pydantic-deep or pydantic-deep run and every file and shell operation executes inside a container, with your working directory mounted at /workspace. Your code stays on disk; side effects stay in the box.

Configure it

Settings live in .pydantic-deep/config.toml in your project, and the same defaults drive both the TUI and headless runs. Change them from inside the app with /settings, or from the shell:

pydantic-deep config set model anthropic:claude-sonnet-4-6

API keys are stored separately in .pydantic-deep/keys.toml, managed through the /provider command. CLI flags always win over config-file values. Full details in Settings & themes.

Recap

  • The CLI is a self-hosted, Claude-Code-style terminal assistant built on the very same create_deep_agent you've been learning.
  • Install it with pip install "pydantic-deep[cli]" and launch it by running pydantic-deep in any project.
  • Out of the box it gives you streaming chat, file and shell tools, subagents, MCP, auto-saved sessions, live forking, image attachments, themes, and persistent memory.
  • Run the same agent headlessly with pydantic-deep run, and sandbox either mode with --sandbox docker.

Where to go next