snowpea manual

snowpea is an open-source, multi-vendor coding agent that runs on your own machine. A Python core runs as a local daemon and owns everything stateful — sessions, tools, permissions, memory, schedules, messenger bindings. Clients attach to it over a documented WebSocket JSON-RPC protocol: an Ink terminal UI today, an Electron IDE in v0.2, and whatever you build on the TypeScript SDK.

Other languages: 한국어 · 日本語 · 简体中文 · Español · all pages

Where to start

If you have just installed snowpea, read Install, then Setup, then Modes. That is enough to work with it every day. Everything after that is optional surface.

Page	Read it when
Install	installing, upgrading, or an install step failed
Setup	choosing a vendor, adding an API key, logging in through the browser, picking search and browser providers
Modes	the agent asks too much, or not enough
Tools and context budget	turns cost too many tokens, or you want to tune repeat guards and context caps
Terminal UI	the keys, the panels, attachments, voice, and what the screen is telling you
Commands	you want the full list of slash commands and CLI subcommands
Attachments and voice	sending images and files in a prompt, speaking to the agent and having it speak back
Plugins	installing or writing skills, agents, commands, hooks and MCP servers
Agents and delegation	delegating work, the built-in explore and reviewer agents, reviews
Language servers	diagnostics after an edit, and the lsp_* tools
Scheduler	you want work to happen while you are away
Gateway	you want to talk to the agent from Telegram, Discord or Slack
Backends	the code lives in a container or on another host
Headless	scripting snowpea, or wiring it into CI
Protocol	building a client against the daemon

The shape of the thing

snowpea              → starts the daemon if needed, attaches the terminal UI
snowpea -c "..."     → one headless turn, no UI, deterministic exit code
snowpea <subcommand> → inspect or configure without opening a session

The daemon is lazy. It starts on the first client, and shuts itself down after an idle period — but only when there is nothing to keep alive: no open sessions, no enabled jobs, no gateway bindings, no named agents. snowpea daemon status tells you which of those is holding it open.

snowpea daemon status

Where things live

Path	What
$SNOWPEA_HOME (default ~/.snowpea)	everything global
$SNOWPEA_HOME/settings.json	providers, search and browser choice, tool categories, timeouts
$SNOWPEA_HOME/credentials.json	bot tokens and secrets, mode 0600
$SNOWPEA_HOME/daemon.json	port, pid, token, start time, protocol version
$SNOWPEA_HOME/state.db	sessions, events, memory, jobs, team tasks, named agents
$SNOWPEA_HOME/logs/	daemon.log, approvals.jsonl
$SNOWPEA_HOME/plugins/, skills/, agents/, commands/	installed and hand-written extensions
<project>/.snowpea/settings.json	default mode, allowlist, backend for this repository
<project>/.snowpea/{skills,agents,commands}/	project-local extensions
<project>/.claude/{skills,agents,commands}/	read for Claude Code compatibility

SNOWPEA_HOME is honoured everywhere, so a second, isolated installation is one environment variable away:

SNOWPEA_HOME=/tmp/snowpea-scratch snowpea daemon status

Getting help

/help inside the UI lists every command the core currently has, including the ones your plugins added. From a shell, snowpea commands list prints the same registry, and snowpea tools list prints the tools with their permission tag and whether they are active.

snowpea commands list
snowpea tools list --json

Bugs and questions belong in GitHub issues. If you want to change the code, Contributing and Architecture are the two documents to read first.