features slash commands

Slash commands

Active contributors: Mario Zechner, kt, Armin Ronacher

Purpose

Slash commands are the /command interactions available in the terminal UI and the web chat. They cover session control (/new, /session, /fork), configuration (/model, /effort, /settings, /login), context management (/context, /compact, /system-prompt), and agent orchestration (/goal, /autonomous, /heartbeat). A single parser in packages/coding-agent defines the built-in catalog, and each interface (TUI, web) contributes its own autocomplete and dispatch, with extension, prompt, and skill sources contributing commands.

How it works

Core parsing

packages/coding-agent/src/core/slash-commands.ts is the single source of truth for command syntax. parseSlashCommand splits a /cmd args string into a name and trimmed args; resolveBuiltinSlashCommandName maps aliases to canonical names; isBuiltinSlashCommandName and builtinSlashCommandTakesArgument drive autocomplete. parseSessionSlashCommand recognizes the session-level commands (compact, refine, goal, autonomous) that must stay in the normal message transport so the backend executes them.

The built-in catalog (CANONICAL_BUILTIN_SLASH_COMMANDS and the aliases in BUILTIN_SLASH_COMMAND_ALIASES) covers: /model, /effort, /settings, /new, /session, /login, /logout, /name, /context, /system-prompt, /logs, /traces, /export, /fork, /clone, /tree, /share, /import, /btw, /fast, /scoped-models, /reload, /mcp, /heartbeat, /heartbeats, /changelog, /update, /hotkeys, /copy, /refine, /compact, /goal, /autonomous, /rlm-max-depth, /fullscreen, and /quit. Aliases include clear->new, usage->context, thinking->effort, rename->name, and side->btw.

Command sources

SlashCommandSource is "extension" | "prompt" | "skill". The web catalog in web/server/src/handlers/chat-commands.ts (handleChatCommandsGet) merges built-ins with skill commands (as skill:<name>, when skill commands are enabled), prompt commands, and extension commands, returning the merged list plus load diagnostics to GET /api/chat/commands.

Web autocomplete and execution

The web client keeps a parallel dispatcher in web/app/src/lib/pi/slash-commands.ts. WEB_BUILTIN_SLASH_COMMANDS mirrors the built-ins, resolveSlashCommandAlias mirrors the server alias map, and resolveLocalSlashAction maps a command plus args to a LocalSlashAction. Local-UI commands (opening the model picker, settings, or a new session) run entirely in the browser; bridge actions (/name, /context, /system-prompt, /export, /tree, /fork, /clone) call POST /api/chat/command; and session commands (/compact, /refine, /goal, /autonomous) intentionally return null so the composer sends the raw slash command through the normal chat transport.

use-local-slash-actions.ts (web/app/src/lib/pi/use-local-slash-actions.ts) implements applyLocalSlashAction and renders results as local transcript messages. buildSlashCommands merges the client dispatcher builtins with the API catalog and active skill/prompt resources into the composer's suggestion list.

The server side of bridge commands is handleChatCommandPost in web/server/src/handlers/chat-command.ts, reached from web/app/src/routes/api/chat/command.ts. It handles session, name, context, system-prompt, export, reload, tree, fork, and clone through PrimeBridge.

TUI autocomplete

The TUI uses CombinedAutocompleteProvider in packages/tui/src/autocomplete.ts, which handles both slash-command completion and file-path completion. getSlashCommandContext (packages/tui/src/slash-command-context.ts) decides whether the cursor is in a command-name or command-argument position; name completion fuzzy-matches the command list (including aliases, argument hints, and source tags) and inserts a trailing space, while argument completion defers to each command's getArgumentCompletions.

The command dispatch chain lives in the TUI mode (packages/coding-agent/src/modes/interactive/interactive-mode.ts), which resolves the parsed command against the built-in catalog and the loaded extension, prompt, and skill commands, then executes or sends it to the session.

graph TD
    TUI["TUI composer"]
    WEB["Web composer"]
    P["parseSlashCommand (coding-agent)"]
    BUILTIN["BUILTIN_SLASH_COMMANDS catalog"]
    LOC["resolveLocalSlashAction (web client)"]
    CMD["POST /api/chat/command"]
    SESSION["AgentSession command executor"]
    CAT["GET /api/chat/commands (web/server)"]
    EXT["extensions / prompts / skills"]

    TUI --> P
    WEB --> LOC
    P --> BUILTIN
    LOC --> CMD
    CMD --> SESSION
    WEB --> CAT
    CAT --> EXT
    LOC -. session commands .-> WEB

Loading

Integration points

• The web autocomplete dispatcher lives in web/app/src/lib/pi/slash-commands.ts and web/app/src/lib/pi/use-local-slash-actions.ts; the route shells are in web/app/src/routes/api/chat/command.ts and commands.ts.
• The web command catalog is built by web/server/src/handlers/chat-commands.ts.
• The TUI autocomplete provider is packages/tui/src/autocomplete.ts with packages/tui/src/slash-command-context.ts.
• The canonical parser and catalog are in packages/coding-agent/src/core/slash-commands.ts; execution lives in packages/coding-agent/src/modes/interactive/interactive-mode.ts.

Entry points for modification

• Add or edit a built-in command: packages/coding-agent/src/core/slash-commands.ts (canonical list and aliases) plus the web mirror in web/app/src/lib/pi/slash-commands.ts and the server catalog in web/server/src/handlers/chat-commands.ts.
• Add a bridge command for the web: extend resolveLocalSlashAction and the switch in handleChatCommandPost (web/server/src/handlers/chat-command.ts).
• Extend TUI argument completion: add a getArgumentCompletions to a command in packages/tui/src/autocomplete.ts.

Key source files

File	Purpose
packages/coding-agent/src/core/slash-commands.ts	Canonical parser, built-in catalog, aliases, session-command detection
packages/coding-agent/src/modes/interactive/interactive-mode.ts	TUI dispatch of parsed commands
web/app/src/lib/pi/slash-commands.ts	Web built-in list, resolveLocalSlashAction, buildSlashCommands
web/app/src/lib/pi/use-local-slash-actions.ts	Web action execution and transcript echoing
web/app/src/routes/api/chat/command.ts	Web POST /api/chat/command route
web/app/src/routes/api/chat/commands.ts	Web GET /api/chat/commands route
web/server/src/handlers/chat-command.ts	handleChatCommandPost, server-side command execution
web/server/src/handlers/chat-commands.ts	handleChatCommandsGet, merged builtin/skill/prompt/extension catalog
packages/tui/src/autocomplete.ts	CombinedAutocompleteProvider for slash and file completion
packages/tui/src/slash-command-context.ts	TUI slash-command name/argument context detection

Related pages

• The packages behind these features, LLM provider abstraction and streaming, Web app
• Streaming flows - the transport that carries session-level commands (/compact, /refine, /goal, /autonomous)
• Sessions and branching - the /new, /resume, /tree, /fork, and /clone commands
• Features lens index, Glossary
• HTTP endpoint reference - the command routes