Commands

There are two command surfaces. Slash commands run inside a session and are owned by the core, so the same /ralph behaves identically in the TUI, in snowpea -c, in a scheduled job and in a Telegram message. CLI subcommands inspect and configure the daemon without opening a session at all.

snowpea commands list
snowpea commands list --json

That prints the live registry, including commands contributed by installed plugins. /help inside the UI prints the same thing.

Slash commands

Session and mode

Command	What it does
/help	list every available command
/tools	list registered tools with category, permission and state
/compact [instructions]	summarise the conversation so far and continue with the summary
/plan, /accept, /auto [request]	switch mode; with a request after it, run that request in the new mode right away (/plan design the game); /plan clear abandons the current plan (see Plans)
/mode [plan|accept|auto|save|show]	show, switch, or save the project default
/busy [steer|queue]	show or set busy-turn follow-ups: steer (default) folds queued prompts into the running turn before its next model call; queue keeps the legacy “run later as a separate turn” behavior
/memory [list|search <q>|forget <id>] [--project|--global|--all]	show, search or forget long-term memories; scope defaults to --all, which is what the agent itself recalls from
/approvals	list unattended approvals waiting for an answer
/allow <regex> [--global]	promote a repeated prompt to a silent allow
/allowlist [remove <id>]	show or prune the allowlist
/backend [local|docker|ssh] [json]	show or change where tools execute
/delegate <agent> <task>	delegate one task to a named agent, inside a normal turn: the turn calls delegate_task for you, waits, and answers with the outcome
$<agent> <task>	shorthand for /delegate <agent> <task>; the daemon parses the prefix, so it behaves the same from any client, not only the terminal UI
/delegation	show whether delegation mode is on; /delegation on makes the agent hand implementation, tests and verification to its team for this session (persisted), /delegation off has it do the work itself, /delegation auto follows agents.delegateByDefault. See Delegation mode

Terminal UI

These are answered by the terminal UI itself rather than by the core, so they do not appear in snowpea commands list and only work in a session you are sitting in front of. Terminal UI covers what each one does on screen.

Command	What it does
/resume	reopen the session this directory was last in, and replay it
/model, /models	list every supported model from every configured vendor and pick one; /model <vendor:model> pins this session (persisted, survives a restart); /model inherit clears the pin; /model default <id> sets models.default
/effort	show how hard the model may think and which rule decided it; /effort low|medium|high|max pins this session (persisted); /effort auto clears the pin. See Reasoning effort
/attach <path>	attach a file to the next prompt
/voice	arm voice input; Ctrl+Space then records
/rec	start or stop recording, same as Ctrl+Space
/tts on|off	speak each reply as it finishes
/update	take the offered upgrade, same as U

Work

Command	What it does
/ralph <task>	PRD loop: stories with acceptance criteria, implement, verify, review until APPROVE
/ultrawork <task>	split into independent parts, run them on concurrent subagents, merge the reports
/review [what]	review the uncommitted diff with a read-only reviewer agent and report the verdict
/setup [providers|search|browser|audio|all]	re-run a wizard screen here, keys entered masked; providers also adds or edits local / OpenAI-compatible servers (name, URL, model, optional key), as many as you like
/login <vendor> [method]	sign in to a vendor: browser flow, device flow, or a masked key
/init [--force]	fast, rough AGENTS.md for the project root, in one turn; merges into an existing file unless --force
/deepinit [path]	explore then write hierarchical AGENTS.md (map → write per directory, then root)
/team "<task>"	the active team's members run it by role: plan, implement, test, review
/team <name> "<task>"	the same, on a named project or global team, just this once
/team <N> "<task>"	compatibility spelling for /workers <N> "<task>"; replies with a note that /workers N is current
/workers <N> "<task>"	N identical workers, one git worktree each, branches merged as tasks finish
/team create <name> <agent...>	create a project team from existing agents and activate it
/team use <name> / /team use none	switch the active project team, or clear it
/team list	every team, where it came from, and the stage each member fills
/deep-interview <idea>	Socratic interview that scores ambiguity and refuses to hand off until the spec holds
/deep-research <topic>	multi-source web research fanned out over subagents, answered with citations
/ralplan <task>	consensus planning — planner, architect and critic argue before any code is written

/ralph keeps its state in <project>/.snowpea/ralph/ as prd.json and progress.md, so you can read (and edit) what it thinks it is doing. /ralph alone, or a bare "carry on" (/ralph 실행해줘, /ralph continue, /ralph --resume), resumes an unfinished prd.json instead of planning a new task — use that form in a schedule; a new task keeps the unfinished PRD as prd-<time>.json. It stops at ralph.max_iterations (10) if it cannot converge. If the model gives no usable PRD even after one stricter retry, /ralph says so and runs the task as a single story. Besides its text progress lines, /ralph (and /ultrawork) emits a command.progress session event with every story's pass/fail/pending status after planning and after each iteration, plus an outcome on the last one, so a client can draw the plan without parsing text. /ultrawork and /deepinit fan out under agents.max_concurrent (3 by default). The last three are SKILL.md files under core/snowpea_core/builtin_skills/, loaded by the same loader your own skills use — read them, copy them, change them.

/init is /deepinit's fast sibling: one main-agent turn, no subagents, at most a handful of tool calls, in the spirit of Claude Code's own /init. It also creates <project>/.snowpea/settings.json with defaultMode: "accept" when the project has no settings file yet — but never touches one that already exists. In plan mode it only reports what it would write.

Plans

A project has at most one current plan: <project>/.snowpea/plans/current.md (the plan as written) and current.json beside it (id, title, source, status, a hash of the markdown, and steps S1… each pending/in_progress/done/blocked). It is written by the plan_save tool — /ralplan and /deep-interview call it with their final plan or spec, and plan mode calls it when the plan is done. If a /ralplan or /deep-interview turn ends without plan_save, the newest plan-shaped message of that turn (a heading over a numbered list) is saved instead. A plan-mode pass that only wrote a .md/.markdown/.txt file has the newest such file registered as the current plan when the session leaves plan mode; entering plan mode starts a fresh pass. Saving a new plan keeps the old one as .snowpea/plans/archive/<time>-<slug>.{md,json}. Editing current.md by hand is fine: steps that were read from the markdown are re-read, and each keeps the status of the step with the same title. Only the main agent may save or mark the plan; a delegated child is refused.

/ralph, /team, /ultrawork and /workers <N> run the current plan when they get no argument, a carry-on or execute-only phrase, or the plan's own title. Filler words are ignored, so 실행해줘, 구현해줘, 그냥 구현해줘, 나머지 구현해줘, 다음 단계 진행해줘, 이어서 해줘, 계속 진행해줘, ㄱㄱ, go ahead, implement it and run the plan all count; S3 진행해줘 runs step S3 alone. /ralph uses this same phrase list to resume an unfinished prd.json. The planner is given the plan and its step statuses and makes one story or task per pending step (done steps are skipped), each carrying plan_step and the plan's id. When a story passes, its step is marked done, and a failure leaves it in_progress with the reason. Marks only land while that same plan is still current and active: a plan replaced mid-run is never touched, and a finished plan is never reopened. A real task given while a plan is active is planned as typed, with the plan as background. /ralph resumes an unfinished prd.json first when it belongs to the current plan, or when the plan is older than it, and keeps the progress its stories already have. Each command says which plan it runs, with its age and source. Every save, step change and clear emits a plan.updated session event. The main agent sees one Current plan: <title> (saved 3d ago by ralplan) — 2/7 steps done; next: S3 … line every turn, so "just implement it" after a compaction still finds the plan; it marks steps with plan_update_step.

Plan-first gate. A request of three words or fewer with nothing concrete in it is not run straight away when there is no current plan (and, for /ralph, no unfinished PRD). Examples: /ralph 개선해줘, /team "improve performance". Anything that names a path, file name, symbol, ALL-CAPS name, version, URL, list or quoted text counts as concrete, and so does a Latin word inside Korean (pytest 실패 고쳐줘). This applies to /ralph, /team (including /team N), /workers and /ultrawork. When someone can answer, the command asks whether to plan the request with /ralplan first (queued as its own turn), run it as typed, or cancel. Someone can answer when the session has an interactive client, or when it is a messenger chat whose binding has an approver user. A headless client or an unanswered question runs it as typed. Unattended runs (schedules, named-agent jobs) are never asked. --force, --now or a leading ! (/ralph !개선해줘) skips the gate, and planning.gate: "off" turns it off.

To replace the plan, save a new one (/plan, /ralplan, /deep-interview). To abandon it, run /plan clear, or have the agent call plan_save with clear: true; the plan is archived either way.

Generators

Command	What it does
/agent create "<description>"	write an agent definition into <project>/.snowpea/agents/<name>.md
/agent list	list agent definitions
/agent use <name|none>	run this session as that agent: its prompt, tools and round budget (none clears it)
/skill create <name> "<what it should do>" [--global] [--force]	generate a SKILL.md from a brief and write it into <project>/.snowpea/skills/<name>/ (or $SNOWPEA_HOME/skills/<name>/ with --global); refuses to overwrite an existing one without --force
/skill learn [name]	turn the session you just finished into <project>/.snowpea/skills/<name>/SKILL.md
/skill reload	re-scan skills, agents, commands and plugin MCP servers after editing a SKILL.md by hand (an install or /skill create reloads on its own)
/skill list	what is installed, by kind and source

A generated agent is a delegate_task target immediately, no reload needed.

MCP servers

Command	What it does
/mcp or /mcp list	table of every configured server: name, scope, transport, state, tool count
/mcp get <name>	one server in full, with its tools; env and headers show key names only
/mcp add <name> -- <command> [args…]	add a stdio server to <project>/.mcp.json (--global writes $SNOWPEA_HOME/.mcp.json)
/mcp add <name> --url <https://…>	add a remote server; --header K=V for its credentials
/mcp add-json <name> '<json>'	add a raw .mcp.json entry, verbatim
/mcp test <name>	start it, list its tools, report the spawn error if it fails
/mcp configure <name> [--tools a,b] [tool…]	register only these tools of the server; no names means all of them
/mcp enable|disable <name>	keep the entry but stop starting it, and back again
/mcp remove <name>	delete the entry and stop the server
/mcp reload [name]	restart one server, or re-read every declaration
/mcp catalog	the curated presets --preset accepts

--env K=V and --header K=V may repeat. Nothing is written until the server has answered tools/list once (--no-test skips that), the command line is always argv and never a shell string, and add, remove and update all take effect without restarting the daemon. Servers a plugin or mcp.servers in settings declares are listed but read-only.

Scheduling

Command	What it does
/schedule "<spec>" "<task>" [--channel X] [--mode M]	register a job
/schedule	list jobs, or cancel one

CLI subcommands

Inspecting

snowpea --version
snowpea tools list --json
snowpea commands list --json
snowpea agents --json
snowpea daemon status --json

tools list and commands list call one RPC method each and exit. They create no session and call no model, which makes them the right smoke test after an install or in CI. tools list also prints the backing provider for the tools that have one, so web_search shows the search provider that would actually answer.

Project init

snowpea init
snowpea init --force

Starts a session in the current directory (or wherever you run it from) and runs /init — see Work above — as one headless turn, the same path snowpea -c uses. See Headless for the exit codes.

Context

snowpea session context --json
snowpea session compact s-abc123 "keep the API design decisions"

session context prints one line per live session: tokens used, the model's context window, and the percentage between them. A window the daemon cannot determine prints as ? rather than a guess — every hosted vendor is in a static table, a local vLLM or Ollama server is asked once and cached, and providers.<vendor>.context_window in settings.json overrides both.

Compaction keeps a long session inside that window. /compact summarises everything so far into one "Session summary" system message, keeps the last few messages verbatim and continues from there; session compact is the same thing from the shell. It also happens on its own once a turn would pass context.autoCompactPercent of the window (85 by default), between turns and never in the middle of a tool loop. Set context.autoCompact to false to leave it to /compact alone.

Sessions

snowpea session list
snowpea session list --include-closed --workdir ~/src/api --json
snowpea session delete s-abc123
snowpea session clear --all

session list prints the live sessions, and with --include-closed the saved ones too — id, mode, creation time, working directory and the last prompt each saw. session delete and session clear remove saved sessions along with their attachments and speech files; a live session is never deleted, so close it first. Pick an id out of session list and continue it with snowpea -c "…" --resume <id>.

Checkpoints

Snowpea records per-turn checkpoints so a client can offer "restore to before this turn." Tool writes to ordinary files under the session workdir are captured before the first write in a turn, and shell-side changes are detected only when the workdir is a git repository. It does not track files outside the workdir, .git/, node_modules/, .snowpea/, __pycache__/, dist/, out/, or files larger than 5 MB. Deleting a saved session removes its checkpoints too.

Model profiles

snowpea model profiles --json
snowpea model default fast
snowpea model assign executor deep
snowpea model assign executor daily --project
snowpea model assign executor

model profiles prints the routing's own view — the project's models block merged over the global one, each row tagged [global] or [project], with the effective default marked — plus the per-agent assignments. model assign routes one agent to a profile and model default sets the fallback; both take --project to write <workdir>/.snowpea/settings.json instead, and both clear the setting when the profile id is omitted. The daemon refuses a profile id that does not exist.

See Setup for the five-rung precedence chain these settings feed.

Search

snowpea search test "snowpea agent github"
snowpea search test "snowpea agent github" --json

search test runs one real query with the configured provider and prints which provider answered, plus the reason each skipped provider dropped out — an API key that is missing, an instance URL that is not set, an HTTP error. It needs no daemon: it reads $SNOWPEA_HOME/settings.json directly. Exit code is 0 when some provider answered and 2 when none could.

Daemon

snowpea daemon status
snowpea daemon start
snowpea daemon stop

status prints the port, pid, uptime, the four keepalive counters — sessions, jobs, gateway bindings, named agents — and whether the daemon intends to exit, with the reason it will not.

Providers

snowpea provider list
snowpea provider login openai
snowpea setup --vendor deepseek --key sk-...

Several OpenAI-compatible servers can be configured side by side, each under its own name. add-local writes one, remove forgets it along with the model profiles that named it.

snowpea provider add-local hon2 --url http://hon2.example.com:8000/v1 --type vllm
snowpea provider models hon2
snowpea provider remove hon2

See Several local servers for the settings shape and the wizard flow.

Skills and plugins

snowpea skill list
snowpea skill search "pdf"
snowpea skill install oh-my-claudecode
snowpea skill install ./my-plugin
snowpea skill remove my-plugin

MCP servers

snowpea mcp list
snowpea mcp add notes -- python -m my_notes_server
snowpea mcp add remote --url https://example.internal/mcp --header Authorization=Bearer-xxx
snowpea mcp add github --preset github --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx
snowpea mcp get notes --json
snowpea mcp test notes
snowpea mcp configure notes --tools search,fetch
snowpea mcp disable notes
snowpea mcp remove notes
snowpea mcp reload
snowpea mcp catalog

--scope global (or just --global) writes $SNOWPEA_HOME/.mcp.json instead of the project's file. Everything after a bare -- is the child's argv and is never parsed, so flags may sit on either side of it. Every subcommand takes --json. See plugins for the file format.

Jobs

snowpea job schedule --at "0 9 * * *" --task "summarize yesterday's commits" --channel telegram:123456
snowpea job schedule --in 10m --task "check the build" --mode plan
snowpea job list --json
snowpea job run <job-id>
snowpea job cancel <job-id>

--at, --in, --every, --cron and --spec are the same option under five names; use whichever reads best for the schedule you are writing.

Gateway

snowpea gateway bind telegram TELEGRAM_BOT_TOKEN agent:scribe --user 987654
snowpea gateway list --json
snowpea gateway unbind <binding-id>

Voice engines

snowpea audio install faster-whisper
snowpea audio install piper
snowpea audio install edge-tts

Installs a local voice engine on the daemon's machine with uv tool install, pipx or pip install --user, whichever is there, and prints the log. Installing piper also fetches one default voice. A system package (espeak-ng, say, powershell) is not installed for you: the command exits 2 and prints what to run yourself. See setup.

Team and service

snowpea workers status
snowpea team status
snowpea team list
snowpea team create delivery architect executor verifier
snowpea team use delivery
snowpea team delete delivery
snowpea service install
snowpea service status
snowpea service uninstall

workers status (and team status, its older spelling) reports each task's state and retry count for a running /workers batch. team list, create, use and delete manage the reusable agent rosters instead: the same project teams /team create writes to <workdir>/.snowpea/settings.json, listed together with the global ones and with the active team marked. team delete removes project teams only. service registers the daemon to start at login — a systemd user unit on Linux, a launchd agent on macOS, a scheduled task on Windows. It is off by default, and you only need it if you want schedules and gateways to survive a reboot without anyone logging into a terminal.

Global options

Option	Meaning
--version	print the version and exit
--home DIR	override SNOWPEA_HOME for this invocation
--mode plan|accept|auto	mode for the session being started
-c, --prompt TEXT	run one headless turn and exit
--json	emit JSON Lines instead of prose
--cwd DIR	working directory of the session
--timeout SEC	abort the turn after SEC seconds
--provider VENDOR	vendor for this session
--resume SESSION_ID	continue a saved session instead of opening a new one
--approve-none	deny every approval instead of prompting

Running a slash command headlessly

Because the registry lives in the core, a slash command is a valid headless prompt:

snowpea -c "/ralph add a failing test then make it pass" --mode auto
snowpea -c "/deepinit" --json
snowpea -c "/init --force" --json

The CLI does not parse it. It hands the text to the core, which dispatches it exactly as the TUI would.

Next

Plugins — adding commands of your own.