Chat Commands

Chat commands are slash commands you can use in any channel (WebChat, Telegram, Slack, Teams, WhatsApp, TUI) to control Octipus.

Available Commands

All Channels (Root agent Commands)

Command	Description
`/help`	Show available commands
`/docs <query>`	Search the product documentation (setup, channels, providers, configuration) — returns matching sections directly, no LLM call
`/status`	Check session status, running agents
`/stop`	Stop all running agents in the session
`/clear`	Clear conversation context and start fresh
`/model [name]`	Switch to a specific model for the session
`/models`	List available models
`/plan [on	off]`
`/capture <text>`	Append a timestamped line to today’s daily note; `[[wikilinks]]` and `#tags` in the text are wired into the knowledge graph immediately
`/cost`	Show token usage and cost for the session
`/sessions`	List your recent sessions (the TUI’s `/resume <n
`/history`	Replay the current session’s last 50 user/assistant messages
`/cancel`	Abort an active multi-step command
`/eval`	Run evaluation scenarios or compare models

Persona

Persona controls (name, tone, narration, self-facts, presets) are accessible via the web UI at /persona, or via the /persona gateway command in the TUI (see TUI / Gateway Commands — not available from web/channel clients). Once set, your chosen persona applies across all channels.

Available persona controls (in the /persona page or via the /persona gateway command):

Control	Options	Description
Name	Text	Rename the root agent (default: `Octipus`)
Tone	`dry`, `playful`, `neutral`, `professional`, `terse`, `verbose`	Personality of the root agent’s responses
Narration	`off`, `minimal`, `chatty`	Volume of live swarm narration during agent execution
Facts	Free-form text	Add custom self-facts (“always use bullets”; persists across sessions)
Preset	Dropdown	Switch preset persona (keeps custom name)
Arm voice	`/persona arm <role> <preset\|off>`	Give ONE specialist arm a different voice from the host (see below)
Reset	Button	Restore Octipus default

Six presets ship by default: octopus (default, dry octopus-machine), terse-engineer, mentor, nautilus (maritime), concierge, verbose-academic. Each is a YAML file under personas/ you can edit or copy as a new preset.

Per-arm voices. The persona above is the root agent’s. A single arm can speak differently — a blunt review under a playful host — by binding a preset to it:

/persona arm review terse-engineer   # review now speaks as terse-engineer
/persona arms                        # list every arm that has its own voice
/persona arm review off              # back to no persona for that arm

Shadowing is opt-in per arm, and an unbound arm carries no persona block at all — which is what every specialist did before this existed, and why turning it on for one arm costs nothing anywhere else. The preset supplies the voice; your chosen name, pronouns and self-facts carry over, because an arm is the same assistant speaking differently, not a second assistant you never named. The root agent itself is set with /persona use, not /persona arm.

Full spec in docs/plans/ux-personality-revamp.md.

TUI / Gateway Commands (Additional)

These commands are available in the TUI and gateway clients (not web/channel clients).

Command	Aliases	Description
`/work-plan`	—	Show the visible plan, evidence, and feedback
`/plan-feedback <change>`	—	Save feedback on the current plan
`/abort`	`/stop`, `/cancel`	Stop running agents (gateway version; `/stop` is root agent version)
`/status`	`/s`	Show session status and agents (gateway version)
`/cost`	—	Show cumulative token usage and cost
`/compact`	—	Compact session context (summarize old messages); optional: `/compact <focus instructions>`
`/clear`	`/cls`, `/reset`	Reset root agent context and clear TUI display
`/diff`	—	Show `git diff --stat` for workspace changes
`/changes`	—	Review git changes in the workspace — `/changes` for the list, `/changes <path>` for a file diff
`/help`	`/h`, `/?`	List available commands
`/reload-extensions`	`/reload`	Re-discover and reload user extensions from `.octipus/extensions/` (admins only)
`/persona`	—	Configure the root agent persona — name, tone, narration, free-form facts
`/version`	`/v`	Show Octipus version and build info

Channel-Specific

Command	Where	Description
`/start`	Telegram, WhatsApp	Initialize bot connection
`/link`	Telegram, Slack, WhatsApp	Get a 6-character code to link your channel account to your web account

Role delegation

The root agent handles the conversation and may delegate focused work to a specialist role with spawn_child. Role selection happens per delegated task; there is no user-facing /expert or /experts command and no persistent expert catalog to switch between. Use /persona for the root agent’s voice and /skills for session skill selection.

Searching the Docs (`/docs`)

/docs <query> searches Octipus’s own product documentation — which is auto-indexed into the knowledge base at boot (see docs/RAG.md → Product docs auto-index at boot) — and returns the top matching sections directly:

/docs how do I set up Telegram
/docs add a model provider
/docs configure Slack

It is a deterministic lookup (no LLM call), so it works even when no chat model is configured. Each hit shows the section heading, a short snippet, and the source file. To get a synthesized answer instead of raw sections, just ask in plain language (“how do I connect Telegram?”) — knowledge-tool agents are instructed to consult the same docs and cite them.

Permission Prompts

When an agent needs to use a tool that requires approval, you’ll see a permission prompt:

Telegram/Slack/WhatsApp:

🔒 Permission required: the agent wants to use "shell".
Command: docker compose up -d
Reply "yes" to allow or "no" to deny.

TUI:

⚠ Permission: shell → docker compose up -d  (y/n)

Type yes/y to approve or no/n to deny. If denied, the agent is stopped and the root agent asks what to do next.

Channel Feedback (Emoji Reactions)

On external channels (Telegram, Slack, WhatsApp), Octipus provides real-time emoji reactions on your message:

Phase	Emoji	Meaning
Received	👀	Message received
Working	💻🔍✍️⏰🔒🐳🎨📊🧪🧠	Role-specific (coding, research, etc.)
Tool use	📖💻🔍🐳💬⏰🔌🔧	Tool-specific during execution
Permission	⏳	Waiting for user approval
Soft stall	😐	15s without progress
Hard stall	😬	45s without progress
Done	✅	Success
Failed	❌	Error

A typing indicator is also sent while the agent works (refreshes every 4 seconds on Telegram).

How Commands Work

Commands go through the root agent command registry (src/core/commands/), not directly to agents. They execute immediately without an LLM call.

User sends "Review the API documentation and propose corrections"
    |
    v
Channel receives message -> starts with "/"
    |
    v
Root agent handles the request and chooses whether to call `spawn_child`
    |
    v
The child receives its selected role, model topic, tools, and deliverable
    |
    v
Response: root agent answer with the delegated result

The TUI has an additional set of commands via the gateway command registry (src/core/gateway/commands.ts) which include /cost, /diff, /compact, and other local operations.

Troubleshooting

Command not recognized

Ensure you include the / prefix (e.g., /help not help)
Commands are case-insensitive for the command name, case-sensitive for arguments
Unknown commands return an error message listing available commands

`/clear` didn’t help

/clear resets session context including active plans
In TUI, /clear also clears the terminal screen and scrollback
For a completely fresh start, create a new session in the web UI

See Visible work plans for progress and feedback in the web workspace and TUI.

Edit this page in the repository.