Session Commands Reference

Use this reference while operating a CLI session or implementing an ACP/WebSocket client. It lists every registered slash command, its arguments and output, and the transport differences.

Get started

octomind run

Type one command per input. Most commands split on whitespace; /schedule separately supports quoted key=value arguments. Do not paste shell comments after slash commands: they become arguments.

/help
/model
/role
/info

Command Summary

Transport support

Every command in the summary except /? reaches the shared dispatcher through CLI input, ACP prompts or _octomind/command, and WebSocket type: "command" messages. The table below lists exceptions to identical behavior; all remaining commands execute their shared handler on the server and return its typed output. The CLI renders that output as terminal text. ACP prompts send it as JSON text in an agent message; ACP extensions return success, output, and error. WebSocket returns status.data with command_type. A handled output may itself contain an error or success: false; inspect it, not just the transport envelope.

ACP discovery currently advertises removed session, workflow, and agents entries and omits some working commands. Use this inventory and the dispatcher, not discovery descriptions, as the command contract.

For an existing session whose ID is demo, these are complete command envelopes:

{"jsonrpc":"2.0","id":1,"method":"_octomind/command","params":{"session_id":"demo","command":"/context","args":["tool"]}}

{"type":"command","session_id":"demo","command":"context","args":["tool"]}

Replace demo with the ID returned by session creation. ACP includes the slash; WebSocket adds it. See ACP Protocol and WebSocket Server for connection and session creation.

Configure the current session

/model [MODEL]

Show or change the current model. Without argument, displays the current model. With argument, switches to the specified model in provider:model format. The change is runtime + saved to the session file — it does not modify your global config.

/model openai:gpt-5.6-sol
/model anthropic:claude-sonnet-4-6
/model octohub:auto

/role [ROLE]

Show or change the current role. Without argument, displays the current role.

The argument is either:

• a plain role name defined in your config's [[roles]] (validated up front; an unknown name is rejected with Invalid role), or
• a tap agent tag in domain:spec form (e.g. developer:general), which resolves the manifest, INPUT/ENV placeholders, and dependency scripts.

On success the session is saved; on failure the previous role and complete resolved model profile are restored.

/role developer:general
/role assistant:concierge
/role assistant

The default config ships the roles assistant, task_refiner, task_researcher, and reduce. There is no built-in developer role — developer:general above is a tap agent tag.

/effort [LEVEL]

Show or change the reasoning effort level. Without argument, displays the current level. With argument, sets the effort to one of: low, medium, high, xhigh, max. The change is saved to the session file (not global config) and is ignored by non-thinking models.

/effort high
/effort max

/loglevel [LEVEL]

Without an argument, show the current level and valid options. With an argument, change the log level. Options: none, info, debug. This is runtime-only — it is never written to disk.

/loglevel debug

Debug output favors one compact event per provider response, usage update, and tool dispatch. Tool parameters are serialized on one line and capped at 200 tokens; routine animation transitions and full raw provider responses are not printed. Learning recall is the deliberate exception: its bounded final Active Memory Pack is printed exactly so injection correctness can be inspected.

Session Management

/help

Show 29 built-ins with descriptions plus custom /run commands. /usage and /login are valid commands but are absent from the terminal-rendered list.

Note: /? appears in autocomplete but is not wired into the command dispatcher — typing it falls through as user input in the CLI. Only /help shows help.

/help

/exit / /quit

Exit the current session. /quit is an alias of /exit.

/quit

/list [PAGE]

List saved session names, titles, creation times, models, token totals, costs, and current-session markers. Pages contain 15 sessions; the default is 1. Zero, invalid, or out-of-range pages return an error.

/list 1

/new [TITLE]

• /new (no argument) creates a new session with a generated name in the same format as octomind run: YYMMDD-basename-HHMM-uuid4short.
• /new <title...> creates a new session and sets the given title (same as /rename). The title may contain spaces (all arguments are joined).

This command does not display current session info — use /info for that.

/new Authentication review

/rename [TITLE]

Set the current session's display title. Arguments are joined with spaces. Running /rename with no title clears it; the underlying session name and log filename do not change.

/rename Authentication review
/rename

/clear

Clear the terminal screen.

/clear

Information & Monitoring

/status [agents [ID]|monitors|jobs]

The single process-activity surface for the current session. The old /agents and /monitor commands have been removed.

agents merges tap specialists with asynchronous agent_* calls. Tap runs carry live or persisted usage accounting; async agent_* cost is explicitly shown as not tracked rather than guessed. jobs is generic across MCP servers: a tool must return a standard ResourceLink; Octomind retains the originating server and treats the URI as opaque. The full jobs view performs one bounded resources/read call per active resource. Completion remains event-driven via resources/updated and is injected automatically.

All status state is process-local and session-scoped. A resumed process cannot reattach to work owned by the prior process.

/status
/status agents
/status monitors
/status jobs

/info

Display comprehensive session statistics:

• Token usage (input, output, cached, reasoning)
• Cost breakdown (per-request and cumulative)
• Cache savings (tokens and accounting estimate)
• Compression statistics (if compression has occurred)
• Learning packs, items/tokens shown, materially used memories, outcome credit, active-pack state, and maintenance activity. Cumulative learning usage is persisted with the named session and survives resume.
• Model information

/info

/report

Generate a detailed usage report for the session with per-request breakdown.

/report

/usage

Show spend windows, storage, and network usage for the signed-in Octomind account. This is account-level information; /info is the current session's local accounting. When not signed in, the command returns a normal unsigned state rather than failing.

/usage

/login

Start the Octomind browser-confirmed sign-in flow. In ACP-style clients it returns the verification URL and code immediately while polling in the background; an already signed-in process reports the account without starting another flow. Completion updates the stored OctoHub credential used by octohub:auto.

/login

/share

Upload the current session's JSONL log to the share endpoint and print the returned share URL pointing at the web viewer (octomind.run/r/<id>). The uploaded content is the saved JSONL log, including recorded messages, tool activity, and accounting.

The CLI does not open the URL automatically — clicking it is your choice.

/share

Output contains the server-returned url and share id; their values are assigned by the share service.

Environment overrides:

• OCTOMIND_SHARE_URL — point /share and /analyze at a different host (defaults to https://octomind.run). Use this only when pointing at a self-hosted instance or a local dev server.

/analyze

Open the current session in the web viewer without uploading anything. A tiny HTTP server is bound to 127.0.0.1 on a random port; the printed URL points at octomind.run/analyze?b=127.0.0.1:<port>&t=<token> so the browser fetches the JSONL directly from your machine.

The bridge:

• listens on loopback only — unreachable from other machines,
• gates session-data requests with a per-invocation 24-character token (reusable while that bridge lives) sent in the X-Bridge-Token header,
• aborts the previous bridge when /analyze is re-invoked (fresh port + fresh token each time),
• shuts down with the octomind process — there is no persistent state and no upload.

/analyze

Output includes the viewer url, the random loopback port, and a token in structured output. Open the printed URL on the same machine as Octomind.

Use /analyze for ephemeral, private review of an in-flight session; use /share when you want a share link to send to someone else.

Context Management

/context [FILTER]

View session context (message history). Filters:

• all — Show all messages
• assistant — Only assistant messages
• user — Only user messages
• tool — Only messages with role tool; assistant tool-call messages require assistant or all
• system — Only system messages
• large — Only messages whose content exceeds 1000 bytes

An unrecognized filter value silently falls back to all.

/context
/context tool
/context large

/done [INSTRUCTIONS]

Force-compress the conversation context bypassing all automatic threshold, cooldown, and cost guards, then (when [supervisor.learning].enabled) spawn fire-and-forget lesson extraction. Use it to manually reclaim context after finishing a unit of work.

• The forced compression preserves no injected skills, including env-loaded ones.
• Lesson extraction runs in the background and stores lessons for the current role + project — see Learning Guide.
• It does not touch the active plan or auto-commit; enabled lesson extraction may write grounded learning records asynchronously.

/done
/done Now review the error handling.

Media

/image [PATH]

Attach an image for AI analysis. With a path, attaches the image file at that path; without a path, attaches an image from the clipboard (no-op if the clipboard holds no image). Requires a vision-capable model.

/image screenshot.png
/image /path/to/diagram.jpg
/image

/video [PATH]

Attach a video for AI analysis. Requires a video-capable model. With no path, it returns unattached status after checking model support. Both media commands report attachment status, the path, and any error; attachment is sent with your next message.

/video demo.mp4

/copy [SCOPE]

Copy session text to the clipboard. With no argument it copies the last assistant response verbatim. A scope selects more of the session and renders it as markdown-labelled blocks in session order:

Tool calls, tool results, and system-managed injections are never copied. Returns success and byte length, or copied: false when the scope selects nothing or the host clipboard is unavailable. An unknown scope returns an error listing the valid ones.

/copy
/copy all

MCP & Tools

/mcp [ACTION]

Inspect MCP servers and their tools. The session /mcp command is read-only; it has exactly these six subcommands:

Any other subcommand returns Invalid MCP subcommand.

Runtime server management — adding, enabling, disabling, or removing servers — is done by the mcp MCP tool (which the model can call), not by this slash command.

/mcp full
/mcp health
/mcp validate

Commands

/run [COMMAND] [INPUT...]

Execute a custom command defined in the [[commands]] config section. Without argument, lists commands available to the current role. Optional trailing text is the input; otherwise it uses the most recent real user task message. Returns the command name, execution status, and layer result.

Before executing, /run runs the session and request spending checks. An interactive session-limit check can ask whether to continue; a declined check, exceeded request limit, or check error prevents execution.

/run reduce
/run reduce Summarize the current implementation decisions

Multi-step workflows are no longer a session command. Use the external CLI instead: octomind workflow <file.toml> — see Workflows.

/prompt [NAME]

Inject a prompt template defined in the [[prompts]] config section into the session inbox; it is delivered verbatim as a user message on the next loop iteration. Without argument, lists available prompts. There is currently no template variable substitution.

/prompt review
/prompt explain

/plan [ACTION]

Display the runtime-owned structured task plan.

Note: /plan is display-only. The specialist has no plan mutation tool. For complex work it emits sparse hidden signals alongside normal work; the external planner creates, advances, revises, and finalizes runtime plan state. Focused work stays plan-free.

/plan

/skill [NAME|PAGE|PATTERN]

Manage skills from taps. Skills are reusable instruction packs that inject domain knowledge into context.

/skill
/skill 1
/skill *review*

Use an exact listed skill name to toggle it, for example:

/skill code-review

This example requires code-review to appear in your skill list.

/schedule [SUBCOMMAND] [ARGS]

Direct control over the built-in schedule MCP tool — schedule a message to be injected as a user message at a future time or on the next idle. Same operations as the MCP tool, but driven from chat input. See Scheduled Tasks for the broader use case.

Key=value tokens accept shell-style quoting so multi-word values work: when="in 1h 30m", message='hello world'. Supported when formats: idle (fires on next idle — no running taps or background jobs), now (fires immediately), relative (in 5m, in 1h30m, in 90s), time-of-day (15:30, 3:30pm, 9am — tomorrow if past), or absolute (2030-03-30 15:30). every accepts idle (fires on every idle) or the same duration syntax as relative when (10m, 1h, 1h30m). When both when and every are omitted on add, when defaults to idle.

Examples:

/schedule add message="summarize what we just did"
/schedule add when="idle" message="run lint and report results"
/schedule add every="idle" message="remind me to commit"
/schedule add when="now" message="say the date" every="5m"
/schedule add when="in 5m" message="check the build"
/schedule add when="9am" message="standup reminder" every="1h" description="daily"
/schedule edit abc12345 when="in 1h"
/schedule remove abc12345

Replace abc12345 with an ID returned by /schedule list. The schedule response includes an ID or error message for each operation; entries live in the current process/session.

/learning [ACTION]

Browse and manage the lessons stored for the current role + project by the cross-session learning system. See Learning Guide for full details.

Any other subcommand returns an error listing list, show, delete, clear, and evolution.

/learning
/learning list 2
/learning list *commit*
/learning delete 3
/learning clear

Use the ID returned by /learning evolution list for lifecycle actions:

/learning list
/learning show 1
/learning evolution list
/learning evolution show EVOLUTION_ID
/learning evolution approve EVOLUTION_ID
/learning evolution reject EVOLUTION_ID
/learning evolution rollback EVOLUTION_ID

EVOLUTION_ID is a user-supplied existing record ID; choose the lifecycle action appropriate to that record.

Common questions

• Why is the wrong learning item selected? show and delete rebuild the unfiltered list. Run /learning list without a pattern immediately before selecting an index.
• Why is media not sent yet? Attachments are queued for the next user message; send text after attaching.
• Why does copy or analyze fail remotely? Clipboard and loopback access belong to the Octomind host. Use your client attachment/clipboard UI, or /share when uploading the log is intended.
• Why does /plan show not change a task? Plan arguments are ignored: this command only displays runtime state.

Source map

Inventory: commands.rs. Dispatch and output variants: commands/mod.rs; individual handlers live beside it. Transport adapters: main_loop.rs, acp/commands.rs, acp/agent.rs, websocket/server.rs.

See also

• CLI Reference
• Config Reference
• Environment Variables
• Learning Guide