Chat with your agent

There are three ways to hold a conversation with your Revka agent: the CLI (revka agent), the Operator Chat Assistant in the web dashboard, and any connected messaging channel (Telegram, Discord, Slack, Matrix, and the rest). They share the same agent loop, memory, and tools — the difference is where you type. This guide covers each surface, plus the two things you will reach for constantly: switching models mid-conversation and steering a response while it is still being generated.

If you have not started a host process yet, see Run the dashboard for the gateway and to Connect a messaging channel for remote chat. For how a single turn is processed, see The agent loop.

Chat from the CLI

revka agent is the most direct way to talk to your agent. It runs against your configured provider and model with no daemon required.

Interactive vs single-shot

• Interactive — run revka agent with no message to drop into a REPL. It prints 🦀 Revka Interactive Mode, keeps conversation history across turns, and stays open until you exit.
• Single-shot — pass -m/--message to send one message, print the reply, and exit. This is the form to use in scripts and pipelines.

Interactive

revka agent
> Summarize today's logs
> /think:high Now draft a remediation plan
> /exit

Single-shot

revka agent -m "Summarize today's logs"
revka agent --provider anthropic --model claude-sonnet-4-20250514 -m "Status?"

The key flags:

Flag	Meaning
-m, --message <TEXT>	Send one message and exit (single-shot mode)
--session-state-file <PATH>	JSON file to persist and restore conversation state
-p, --provider <ID>	Override the configured default provider for this run
--model <MODEL_ID>	Override the configured default model for this run
-t, --temperature <0.0-2.0>	Override temperature (must parse as a float in [0.0, 2.0])
--peripheral <board:path>	Attach a hardware peripheral (repeatable), e.g. nucleo-f401re:/dev/ttyACM0

You can also set defaults through the environment instead of flags — REVKA_PROVIDER, REVKA_MODEL, REVKA_TEMPERATURE, and REVKA_API_KEY all shadow their config keys. See the CLI overview & environment for the full list.

Note

Config hot-reload is not supported while revka agent is running — restart the command to pick up config.toml changes. (The long-running daemon and channels do hot-reload provider, model, and temperature; see Switch models from a channel.)

Interactive commands

Inside an interactive session, lines beginning with / are handled locally:

Command	Effect
/help	List the available interactive commands
/clear, /new	Clear the conversation and delete session memory (after a y/N confirm). Core long-term memories are preserved
/think:<level>	Set reasoning depth for the next turn: off, minimal, low, medium, high, max
/quit, /exit	Leave interactive mode

/think:<level> can also prefix a normal message, e.g. /think:high Now draft a remediation plan raises reasoning depth for just that turn.

Persisting state with --session-state-file

By default an interactive session lives only in memory. Pass --session-state-file <PATH> to make it durable:

revka agent --session-state-file ./session.json

• On start, if the file exists, Revka loads its history and continues where you left off; the system prompt is re-inserted if missing. If the file does not exist, the session starts fresh.
• The file is rewritten after meaningful turns and after /new, as pretty-printed JSON holding the full message list.
• The same path drives a memory session id (cli:<path>), so the conversation also threads through Kumiho memory.

This is what lets you resume a long-running CLI conversation, share a transcript between runs, or feed prior context into a scripted single-shot call. The same file is what the heartbeat uses when [heartbeat].load_session_context = true, so a scheduled task can read the recent conversation just as if you had sent the message yourself.

The terminal channel

For a zero-dependency chat loop that runs through the channel subsystem (rather than the agent REPL), enable the CLI channel in config and start it:

[channels_config]
cli = true

revka channel start

Type /quit or /exit to leave. This is the simplest smoke test for an agent before you wire up any remote channel.

Switch models in natural language

You do not have to remember model IDs. In an interactive revka agent session — or any chat surface that reaches the agent loop — you can describe the routing you want in plain language, and the agent applies it through its built-in model_routing_config tool:

> set conversation to kimi and coding to gpt-5.3-codex

The tool configures the default model, per-scenario routing, and delegate agents from that instruction. Because it edits routing the same way the config does, the change persists for the agent rather than lasting only the current turn. To pin a model deterministically instead, use the --provider/--model flags above, the revka models set command, or the per-message channel commands below. For the full routing model see Config: provider, agent & routing and Routing, reliability & tuning.

Switch models from a channel

When you are chatting through Telegram, Discord, Slack, or Matrix, you can switch provider and model per session with in-chat commands — no restart, no config edit. These four channels support runtime model switching; /new works on every channel.

Command	Effect
/models	List the available providers
/models <provider>	Switch the provider for this sender’s session
/model	Show the current model
/model <model-id>	Switch the model for this session (context is preserved)
/model <hint>	Switch by a natural-language hint instead of an exact ID
/new	Clear conversation history and start fresh

Switching the model keeps your conversation context; only /new clears history. A trailing bot suffix is tolerated, so /models@yourbot works in group chats. Provider names accept aliases, and an unknown provider returns a hint to run /models.

Separately, the channel runtime watches config.toml and hot-reloads default_provider, default_model, default_temperature, the provider api_key/api_url, and reliability.* without a restart — so an edit on the Config page or on disk takes effect on the next message. See revka channel & integrations and the Channels overview for more.

The Operator Chat Assistant

The dashboard ships a floating Operator Chat Assistant available from every page (open it with the assistant button in the header). It has three tab types:

• Chat — a live operator session over WebSocket, with Markdown rendering, file attachments, inline tool-call activity cards, and an expandable trace per assistant message.
• Terminal — an embedded terminal whose built-in commands each call a gateway endpoint and render the JSON result: status, cost, agents, config, sessions, health, integrations, plus clear and help.
• Code — an agent-driven coding session that renders output as structured code blocks.

Chat tabs talk to the gateway over a WebSocket session:

ws[s]://<host>/ws/operator?session_id=<id>

Sessions are persisted, so tabs can be renamed (double-click the title), archived, and restored. The supporting REST endpoints all require a bearer token from device pairing:

Action	Method + path	Auth
List sessions	GET /api/sessions	Bearer
Load a transcript	GET /api/sessions/{id}/messages	Bearer
Rename a session	PUT /api/sessions/{id} body { "name": "..." }	Bearer
Archive / delete a session	DELETE /api/sessions/{id}	Bearer
Upload an attachment	POST /api/sessions/{id}/attachments (multipart, max 25 MiB)	Bearer

Inside a chat tab, type / to open the slash-command palette. Built-in commands include /theme <name>, /new, and /archive. You can also pick one of the named colour schemes per assistant instance and choose a layout mode (pop-out column, split, or bottom strip). The full reference is on the Operator chat assistant page.

Steer a response mid-turn

Steering lets you nudge a response while the agent is still generating it, instead of waiting for it to finish and sending a correction. It works over the chat WebSocket (/ws/chat and /ws/operator).

During an active turn, send a steer message:

{ "type": "steer", "content": "Prefer the smaller fix" }

The gateway accepts the note and replies with an operator_status event:

{ "type": "operator_status", "phase": "steering", "detail": "Steering note accepted; it will apply at the next Operator boundary." }

A few rules to know:

• The note applies at the next Operator boundary, not instantly mid-token. If the turn is already past that boundary, you get a status saying the current response is past the steering point.
• The steering text is appended to the session transcript as a user note, so it is part of the conversation history.
• Empty steering content is rejected (EMPTY_CONTENT), and steering with no active turn returns No active Operator turn to steer (NO_ACTIVE_TURN).

On messaging channels, the equivalent of steering is interrupt-on-new-message: when enabled, sending a second message before the first reply finishes cancels the in-flight generation for that sender. Turn it on per channel:

[channels_config.telegram]
interrupt_on_new_message = true

This flag is available on Telegram, Slack, Discord, Mattermost, and Matrix. Used together with the /model and /new commands above, it gives you full live control of a remote conversation. To hard-stop everything across all surfaces, use emergency stop (revka estop).

Next steps

revka agent Full flag reference for interactive and single-shot agent sessions.

Operator chat assistant Chat, terminal, and code tabs, slash commands, and layout modes.

Connect a messaging channel Wire up Telegram, Discord, Slack, and more to chat from anywhere.

Sessions & conversation state How Revka threads memory and state across turns and surfaces.