Skip to content

Settings & themes

Tune the CLI to fit how you work — model, thinking effort, themes, and which capabilities are switched on. Change things live from a modal, or commit them to a config file that travels with your project.

The fastest way: /settings

Type /settings in the chat and a compact overlay appears. Arrow keys move, space toggles, enter edits. Every change is written to disk and applied immediately — no restart.

Text Only
◆ settings
 ▸ Model      anthropic:claude-sonnet-4-6
   Thinking   high
   Theme      default

   ◉  Skills
   ◉  Memory
   ◉  Subagents
   ◉  Plan mode
   ◉  Todos
   ◉  Web search
   ◉  Web fetch
   ◉  Tool search (defer tools)
   ◉  Browser
   ○  Teams
   ◉  Context discovery
   ◉  Show cost
   ◉  Show tokens

↑↓ move   space toggle   enter edit   esc close

The top three rows are values you edit; the rest are toggles you flip:

  • Model — opens the model picker (same one /model uses). The agent is rebuilt around your choice on the spot.
  • Thinking — cycles high → medium → low in place. This is the extended-thinking budget the model reasons with.
  • Theme — cycles through the built-in themes and recolors the UI live as you press enter.
  • Toggles — Skills, Memory, Subagents, Plan mode, Todos, Web search, Web fetch, Tool search, Browser, Teams, Context discovery, Show cost, Show tokens. Each is a capability or HUD element that gets enabled or disabled the moment you toggle it.

Changes are persistent

The modal writes straight to config.toml. What you toggle today is still set next time you launch the CLI in the same project.

Where settings live: config.toml

The CLI keeps project-scoped settings in .pydantic-deep/config.toml, resolved relative to your working directory. Precedence runs environment variables > config file > defaults, so a config file lets a project pin its own model and capabilities without touching your global environment.

TOML
# .pydantic-deep/config.toml
model = "anthropic:claude-sonnet-4-6"
theme = "ocean"
thinking_effort = "high"
temperature = 0.2

include_skills = true
include_subagents = true
web_search = true
show_cost = true
show_tokens = true

You rarely write this by hand — /settings and the slash commands below maintain it for you — but it's plain TOML you can read, diff, and commit.

Model & provider

model is any Pydantic AI model string: anthropic:…, openai:…, google-gla:…, openrouter:…. The provider prefix is required; the CLI warns you on launch if it's missing.

TOML
model = "openai:gpt-4o"
fallback_model = "openrouter:anthropic/claude-haiku-4-5"

fallback_model is used automatically when the primary model fails on a rate limit or 5xx. Set both from the /model picker.

Local models

Two ways to run against a local model:

  • Ollama — pick it in /provider, or set a model string with the ollama: prefix (e.g. model = "ollama:llama3.3"). The CLI talks to Ollama on its default localhost:11434; set OLLAMA_BASE_URL (e.g. http://gpu-box:11434/v1) when it listens elsewhere.
  • OpenAI-compatible servers (llama.cpp / LM Studio / vLLM / text-generation-webui) — these expose an OpenAI-style HTTP endpoint but need a base_url, which a plain model string can't carry. Run /provider, choose OpenAI-compatible, and enter the server URL. The CLI stores it as:
TOML
model = "openai-compatible:qwen2.5"   # name after the prefix is the served model
base_url = "http://localhost:8080/v1"

The same entry reaches a hosted gateway that speaks the OpenAI API - a model router or an LLM proxy - with no provider of its own in the CLI: enter the gateway's endpoint as the URL (for example https://gateway.example.com/v1), the model as the gateway names it after the prefix, and its key when asked.

base_url is only consulted when model carries the openai-compatible: prefix, so switching to any other model via /model leaves it untouched. If the endpoint needs an API key (e.g. a remote LM Studio or a keyed vLLM deployment), it's stored in the keystore under OPENAI_COMPATIBLE_API_KEY — never in config.toml — so the project tree never carries the secret. Most local servers ignore the key, so you can leave it blank; when you do set one, it shows up in /keys and pydantic-deep keys list like any other credential. Your OPENAI_API_KEY is never sent to a local endpoint, even when it's set.

/model lists what your local servers serve, under Local (discovered): the models Ollama has pulled (its /api/tags) and, once a base_url is set, what the OpenAI-compatible server answers at {base_url}/models - sent with the keystore key when one is set. Discovery runs in the background when the picker opens and gives up after two seconds, so a server that is down simply adds nothing; only model names are listed, not their size or whether they handle tools. A model a server doesn't list can still be typed in by hand.

The prefix is a CLI-level marker, not something pydantic-ai understands, so everything that spins up its own small model off the session model — the LLM reminder generator, the /goal evaluator, /improve, and a fallback_model — resolves it the same way. Pointing all of those at your local server is the default; nothing quietly falls back to a cloud model.

Tool-calling needs a capable model

Deep agents lean on tool-calling and structured output. A local model only handles this well when it's served with a proper chat/tool template — small models without one will fail or loop. This is a model limitation, not a CLI one.

Override per launch

PYDANTIC_DEEP_MODEL, PYDANTIC_DEEP_THEME, PYDANTIC_DEEP_WORKING_DIR, and PYDANTIC_DEEP_CHARSET override the file for a single run — handy for a one-off model swap without editing config.

Thinking & temperature

TOML
thinking_effort = "high"   # high | medium | low
temperature = 0.2          # omit to use the model's default

thinking_effort controls the extended-thinking budget; leave it on high for hard work, drop it for quick, cheap turns. temperature is optional — leave it unset and the model's own default applies.

Sandbox

TOML
sandbox = "local"               # local | docker
sandbox_image = "python:3.12-slim"

local runs the agent's shell against your filesystem; docker isolates execution inside a container built from sandbox_image. The Docker path needs the docker extra.

local needs Linux or macOS: Pydantic AI runs local commands on POSIX only. On Windows, use docker, or run the CLI under WSL.

Slash commands that write config

The /settings modal covers the common toggles. A few settings have their own dedicated commands:

  • /model — pick the primary (and fallback) model.
  • /theme — switch themes (see below).
  • /fork-config — configure live run forking: branch count, per-branch models and budgets, and the merge strategy. See Sessions, forking & MCP.

All of them persist to the same config.toml.

/theme and the built-in themes

Run /theme to switch palettes. Five cohesive dark themes ship with the CLI:

Name Look
default Warm amber on near-black (the brand theme)
emerald Cool emerald/teal
ocean Cool blue/cyan
rose Warm rose/magenta
minimal Near-monochrome, pure minimalist

The theme recolors instantly and the choice is saved to theme in your config. The CLI always applies one of its own themes — it never falls back to Textual's stock palette.

Set it from anywhere

Pick a theme with /theme, cycle it inside /settings, write theme = "rose" in config.toml, or export PYDANTIC_DEEP_THEME=rose. They all land in the same place.

Recap

  • /settings is the fastest path — arrow-key overlay that toggles capabilities and edits model, thinking, and theme, applying every change live and persisting it.
  • Settings live in .pydantic-deep/config.toml in your working directory; precedence is env vars > file > defaults.
  • model takes any provider-prefixed Pydantic AI string; fallback_model kicks in on failures; thinking_effort and temperature tune how the model reasons.
  • /theme switches between five built-in themes — default, emerald, ocean, rose, minimal — recoloring the UI instantly.

Next, let's pick up where you left off and connect external tools.