Skip to content

TUI display ​

The TUI is somora's chat client for the terminal. This page explains what it shows, which lines you can switch on and off, and every slash command it knows. The switches only change what your terminal draws. The server sends and runs everything either way.

What you get ​

  • A quiet or a detailed view. Hide memory and tool lines with /show, or expand them to the full payload with /verbose.
  • The model's reasoning on demand. /verbose thinking on puts the thinking text above each reply.
  • A status line that tells the truth: agent, session, model, tokens spent, context fill, and what the session is working on.
  • Control over the queue. /queue lists what runs and what waits, /queue rm takes an entry back.
  • Everything by slash command: switch agent, session or model, export a session, reload the config, restart the service.

Try it ​

Start the client against a running server:

bash
somora tui

It opens the agent you used last, in its main session. somora tui --agent <name> --session <name> opens that conversation instead. An empty session greets you with the somora lettering. Type a message and press Enter. Then try the switches:

/show tools off
/verbose memory on
/help

Type / to see the commands, eight at a time. Tab completes the highlighted one.

The screen ​

The client fills the terminal. The bottom panel sits on the last rows: a separator, the status line, the command list while you type a /, the input, and a line of hints. Above it the chat shows the latest lines. The panel stays where it is when the command list opens or closes, when a reply ends, and when the window changes size.

A line moves into your terminal's own scrollback as soon as it leaves the top of the screen, so scrolling up in the terminal shows everything in order, each line once. Long replies, notices and messages move line by line. When the window gets smaller, the terminal itself pushes rows into the scrollback, and those rows can appear there twice.

The status line ​

PartMeaning
🐨 somora · <agent>:<session> · <model>Where you are, and the model that answered the last turn. Before the first turn: the model the session will use. For an external agent: external · <system> <version>.
→ <model> (next turn)The session's model was switched since the last turn, here, in another client or by an agent. The next turn uses it.
Σ↑ 12k+80k¢Input tokens the last turn spent, summed over all its requests. The green part with ¢ was read from the cache.
▣ 45k/200kHow full the context is. Yellow above 75 %, red above 90 %, magenta when it is over the window.
↓ 1.2k (300 🧠)Output tokens, with reasoning tokens in brackets. A ~ marks an estimate.
🧠 highThe thinking depth of the turn. thinking=high (dormant) means the model cannot reason, so the setting does nothing.
mem ✓ tools ✓The two /show switches. An off switch is red: mem ✗.
📝 wiki-review:<agent>A wiki review loop is active.
📁 <project>The project pinned to this session. ⚠ marks an archived one.
📬 2Two other agents have something unread.
⌛3 ▶1 🤖2 ↩1Work counters, see "The work queue". Absent when the session is idle.
↪ steer or ⏸ queueDuring a turn: what Enter does with a message you type now. steer hands it into the running turn, queue lets it wait for its own. Ctrl+T switches, see "Sending and keys".
●Green: connected. Red: not connected. During a turn a spinner with thinking or streaming takes its place.

The status line is always one row. When the window is too narrow for all of it, the least important parts are left out first: the somora name, the wiki review, the display switches, the thinking depth, the project, the token counts. Agent and session, the connection dot, the steer or queue mark and the work counters stay longest. A session's date prefix is left out: ada:notes instead of ada:20261122-133050_notes.

When you open a session, the status line shows the last turn's model and token counts from its history right away.

Lines in the chat ​

LineMeaning
userA message typed by a person, here or in another client.
<icon> <agent>The agent's reply, below its name.
↬ ada or ↬ ada/<session>A message from another agent. The session is named when it is not main.
◇ memory · 3 hits · top=0.82 · <refs>Notes recalled for this turn. At most three references are listed, then +N more.
▸ <tool> · <summary>A tool call.
↳ <summary>The tool's result. Results with nothing worth showing are left out.
↳ error · <message>The tool failed.
◌ codex · plan · <summary>An internal item of the engine, such as the plan list of the codex engine.
🧠 thinkingThe model's reasoning, only with /verbose thinking on.
[image] <file> or [video] <file> (4.0s)The reply produced a picture or a video. The terminal shows the file name.
i, !, ✗A notice from the client: info in gray, warning in yellow, error in red.
✗ config.yaml does not validate …config.yaml has a mistake. somora keeps running on the last valid version, the line lists the problems. See A broken config file.

Replies show their markdown. Headings are bold without their #, list items get a • or their number and keep their indent when a line wraps, quotes a │ bar, code blocks a frame ┌─ <language> with the code in yellow, and tables line up their columns (a row wider than the window is cut at the edge). Inside a line **bold**, *italic* and `code` are shown as such.

Turns nobody typed ​

A turn that somora or another part of the system started is one gray line, not a message:

LineWhat started the turn
🔔 sentinel · <trigger name>A sentinel trigger fired.
🤖 subagent · <task>A sub-agent delivered its result.
↩ agent answer · <agent>The answer to a question this agent asked another agent.
🌐 browser · <window> · handed backThe browser window was handed back to the agent. activity appears in place of handed back for other browser wakes.
🎙 voice · <text>A request from a voice call.
🖥 tmux · <tmux session>A watched terminal session needs attention.
🎬 video · <first line>A video render finished or failed.
⚙ system · <cause>somora itself speaks. After a restart the cause is restart.

The lettering ​

An empty session is greeted with the somora lettering, a tagline and a hint, once per run of the client. Below 60 columns a compact three-line version is used. Nothing is drawn below 22 columns or when the terminal locale is not UTF-8.

Sending and keys ​

KeyWhat it does
EnterSends the message or runs the slash command.
Alt+Enter, Ctrl+JStarts a new line. So does Shift+Enter on terminals that report it, and Enter after a \ at the end of a line.
Tab, Shift+TabFills in the highlighted slash command. Further presses step through the same list, forwards or backwards.
Up, DownInside a message of several lines: moves between its lines. On its first or last line, or in a one-line message: steps through what you sent before, up to 500 entries. Your unsent draft comes back at the end.
Ctrl+RSearches what you sent before, newest first. Typing narrows the search, Ctrl+R again finds an older match, Enter puts the match into the input without sending it, Esc gives your draft back.
Left, RightMoves by one character; with Ctrl or Alt by one word. An emoji counts as one character.
Home, End, Ctrl+A, Ctrl+EJumps to the start or end of the line.
Ctrl+W, Ctrl+U, Ctrl+KDeletes the word before the cursor, everything before it on the line, everything after it on the line.
Ctrl+G, Ctrl+P, Ctrl+OOpens a list to pick an agent, a session of this agent, or a model for this session, see "Pickers".
Ctrl+NJumps to the session with the newest unread reply, at this agent or another.
Ctrl+TDuring a turn: switches between steering a message into it and queueing it, for this session.
EscDuring a turn: stops the running turn and keeps your input. Otherwise: clears the input.
Ctrl+CClears the input. With an empty input it quits.

What you sent is kept across runs in ~/.somora/tui-history.json, the last 500 messages, readable only by you.

Pasted text never sends by itself, whatever line breaks it carries. A paste of more than 8 lines or 800 characters stands in the input as [paste #1 · 40 lines] and is sent in full. Text and Enter that arrive in one piece, as herdr pane run or a script's tmux send-keys type them, are sent.

When an agent asks you something, the question appears with numbered options. Type the number and press Enter, or 1,3 when several answers are allowed. A question that does not wait (a chat agent's ask_user, Codex's own questions) also takes anything else you write as the answer. A question that waits, such as an external agent's permission request, refuses a number it does not have. For an external agent, /model, /thinking and /sampling say that its own system sets them.

You can keep typing while the agent works. A message sent during a running turn goes one of two ways:

  • Queued: it waits for its own turn and shows · queued, or · queued · N ahead when others wait before it. It moves into the chat when it starts.
  • Steered: it goes into the running turn and shows · steered. The agent reads it at its next step, after the tools of the current round, and it moves into the chat at that point. See Steering for the engines that take it; on the others it is queued.

Which way Enter sends follows the agent's steering: setting in agent.yaml, as in the web client. Ctrl+T switches it for this session. The input says which way the next message goes while a turn runs.

Pickers ​

Ctrl+G lists the agents, Ctrl+P the current agent's sessions with their message count and last activity, Ctrl+O the configured models. * marks the one in use. Typing narrows the list: the letters only need to appear in order, so trn finds travel-notes. Up and Down move, Enter picks, Esc closes. Your draft stays in the input, and a pick does not enter the history.

The two switches ​

/show decides whether a line appears at all. /verbose decides how much detail it carries when it does. Think of /show as the master switch and /verbose as the zoom.

CommandEffect
/showLists the current state.
/show memory on|offShows or hides the ◇ memory lines.
/show tools on|offShows or hides tool calls, tool results and the ◌ engine lines. somora's own lines, model switched and context compacted, stay visible.
/verboseLists the current state.
/verbose tools on|offAdds the full input and output below each tool call and result. Engine lines expand to their full content.
/verbose memory on|offAdds the full recalled text below each memory line, as the model received it.
/verbose system onPrints the agent's system prompt once.
/verbose system offClears the flag. Blocks already printed stay.
/verbose thinking on|offShows the model's thinking text above each reply.

Good to know:

  • A switch applies to new lines. Lines already printed do not change.
  • /show memory off wins over /verbose memory on: a hidden line has no place for details. The same goes for tools.
  • Hiding is display only. The notes are still recalled and the tools still run.
  • When you switch to a session, its stored tool lines are replayed whatever /show tools says, in a short form that /verbose tools does not expand. Memory lines are not stored, so they do not come back.

One line is never hidden: the warning that a backup model answered. It starts with ⇄ model fallback:, names every model that failed with its reason, and then the model that answered. It is replayed when you open the session again.

Thinking text ​

/verbose thinking is off by default. When it is on:

  • While the model thinks and no reply text has arrived, the last six lines of its thinking show where the reply will appear. The first word of the reply replaces them.
  • After the turn a gray 🧠 thinking block sits above the reply. It shows at most 40 lines and ends with … (+N lines) for the rest.
  • (truncated) behind the label means the server cut the text at its size limit.
  • Switching to a session replays stored thinking blocks only when the switch is on at that moment.

The block exists only for engines and models that provide their reasoning. The thinking spinner in the status line and the reasoning token counter work whatever this switch says.

The web client has the same switch. There it is on by default and kept per session.

The work queue ​

The status line counts everything the session has to do, whoever started it: your messages, another agent's question, a sub-agent's result, a sentinel trigger, a request from a call.

CounterMeaning
⌛3Three entries are waiting.
▶1A turn is running.
🤖2Two things this session started elsewhere: sub-agents, or questions to other agents.
↩1One result is on its way back to this session.

/queue prints the list in four parts: Running, Waiting, Arriving and From here. Waiting entries are numbered. The entries under "From here" continue that numbering.

/queue rm <n> acts on the entry with that number:

EntryWhat happens
Your own waiting messageRemoved. Its text returns to the input so you can rewrite it.
Another agent's waiting questionRemoved. That agent is told it failed, with the reason.
A waiting sub-agent briefRemoved and reported as cancelled.
A waiting sentinel triggerRemoved and reported as skipped.
Running, under "From here"Stopped. A sub-agent stops with everything it started. For a question, the turn in the asked session is stopped.
Started in the meantimeNothing is removed. The notice says so. Esc stops a running turn.

The counters are fetched again on every queue event, when a turn starts or ends, after /queue rm and on a session switch. Nothing is polled while the session is idle.

Exporting a session ​

/export fetches the session from the server and writes a file where you started the client. The notice names the full path, the size and the format.

CommandResult
/exportA readable Markdown transcript in ./<agent>-<session>.md.
/export markdown [path]The same, to a path of your choice.
/export json [path]The raw event log, one JSON event per line. Default path ./<agent>-<session>.jsonl.

A path only works after the format word.

Slash commands ​

CommandWhat it does
/helpLists all commands.
/agentsLists the agents. * marks the current one.
/agent <name> [session]Switches to another agent, into its main session unless you name one.
/sessionsLists the current agent's sessions with message count and last activity, in your local time. 📬 marks unread, 📁 a pinned project.
/sessions archivedLists the archived sessions, newest first, with the time they were archived and their id.
/session <slug-or-id>Switches to another session of the current agent. An archived one is not opened: the client names the /unarchive that brings it back.
/unarchive <slug-or-id>Brings an archived session back as a normal session and switches to it. A session /reset archived comes back as <name>-archive. When several archives share the name, the client lists their ids: run it again with the id.
/new <slug>Creates a session and switches to it.
/mainReturns to the main session.
/compact [what to keep]Compacts this session now and the conversation goes on. The sentence is the focus of the summary. See Compact by hand.
/reset [YES]Without YES: explains what would happen. With YES: archives the current session and starts it fresh; an open question of the archived conversation goes away. /unarchive brings the archive back.
/modelsLists the configured models with alias, engine, context size and capabilities.
/model [<alias>|default]No argument: shows the model in effect and where it comes from. An alias or provider/id: sets it for this session. default or -: back to the agent's own model.
/show [memory|tools] [on|off]Line visibility, see "The two switches".
/verbose [tools|memory|system|thinking] [on|off]Detail level, see "The two switches".
/thinking [off|low|medium|high|default]No argument: shows the thinking depth in effect and its source: the session, the agent's default or the model's default. With nothing set it says model decides: nothing is sent, and reasoning models usually think. A level: sets it for this session. default or -: clears the session's own setting.
/reloadReads ~/.somora/config.yaml again without a restart. Reports what changed and what needs a restart.
/restart [YES]With YES: restarts the somora service. Every open stream drops and the client reconnects. Without YES: asks you to confirm.
/sampling [key=value …|default]No argument: shows the sampling parameters in effect. key=value pairs set them for this session, the value - removes a key. default or - clears the session's own setting.
/temp <0–2>|defaultShort for /sampling temperature=<n>. default or - removes only the temperature.
/export [json|markdown] [path]Writes the session to a file, see "Exporting a session".
/queue [rm <n>]Lists the session's work, or removes entry n, see "The work queue".
/projekt [<slug>|unlink]No argument: shows the project pinned to this session. A slug pins it, from the next turn on. unlink, off, clear or - removes the pin.
/project [<slug>|unlink]The same command under its English name.
/projectsLists the available projects.
/quitLeaves the client.
/exitThe same.

Keys for /sampling: temperature, top_p, top_k, min_p, frequency_penalty, presence_penalty, repetition_penalty, seed, stop. Only the openai-compatible engine applies them. On other engines the notice says the setting is dormant.

The three project commands appear only when projects.enabled is true in config.yaml.

/restart works when somora runs as a background service: the systemd user unit on Linux or the LaunchAgent on macOS. A server started by hand refuses, because nothing would bring it back.

When you look away ​

The terminal's title shows the agent and session with a mark: ⏳ ada:main while a turn runs, ⚠ when the agent asks you something, ✓ after a reply until you type again. tmux shows it as the pane title. The title you had before comes back when the client ends, on terminals that keep a title stack.

The terminal bell rings when the agent asks you something and when a turn that ran 10 seconds or longer ends. tmux marks the window, and many terminals and window managers flash or badge it.

Inside herdr ​

herdr is a terminal workspace for coding agents. Run somora tui in one of its panes and herdr knows the pane as a somora agent:

The TUI showsherdr sees
A turn running, or work waiting in the queueworking
A question from the agentblocked
Nothing to doidle
No connection to the server, or still loadingunknown

herdr names the pane <agent> · Somora. With it, the TUI hands herdr the command that reopens the same conversation, somora tui --agent <name> --session <name>, so the pane comes back where it was after herdr restarts. Leaving the TUI frees the pane again.

Nothing needs to be set up. The TUI notices herdr from the variables herdr sets in its panes and does nothing outside herdr. herdr cannot send the TUI a prompt with herdr agent prompt yet. That command only takes the agents herdr knows itself.

The other direction, somora watching coding agents in tmux with herdr's rules, is in tmux.

Settings ​

The start values of the switches live in ~/.somora/config.yaml:

yaml
tui:
  show:
    memory: true
    tools: true
  verbose:
    tools: false
    memory: false
    system: false
    thinking: false
SettingDefaultMeaning
tui.show.memorytrueMemory lines are visible.
tui.show.toolstrueTool calls, tool results and engine lines are visible.
tui.verbose.toolsfalseFull input and output below each tool line.
tui.verbose.memoryfalseFull recalled text below each memory line.
tui.verbose.systemfalseStart value of the system flag that /verbose lists. It does not print the system prompt at start.
tui.verbose.thinkingfalseThinking text above each reply.

The client does not read the file for these. It asks the server once at start with GET /tui-config. If the server does not answer, the defaults above apply. A switch you flip with /show or /verbose lasts until you quit.

Where the client connects ​

By default the client talks to http://127.0.0.1:18737. When server.tls is set in config.yaml, it uses HTTPS and the host from server.tls.publicHost. Environment variables override this:

VariableMeaning
SOMORA_BASEThe full address, for example https://nova.tail1234.ts.net:18737. Wins over the others.
SOMORA_HOSTThe host name.
SOMORA_PORTThe port. Default 18737.
SOMORA_TLS1 forces HTTPS, 0 forces HTTP.
SOMORA_KEYThe server's key. On the server itself the client reads ~/.somora/server.key; on another machine set this to what somora key prints there.

The agent you used last is remembered in ~/.somora/tui-state.json. Without one, the client starts on the first agent in alphabetical order.

What the server sends ​

The detail for /verbose is always in the live events. The client only decides whether to draw it. That is why a switch works at once, without a reconnect, and why any other client can offer the same switch without a new route.

EventAlways drawn fromDrawn only when verbose
tooltool, summarydetails: the payload as formatted JSON
memorycount, topScore, refsfullText: the recalled block as the model received it
thinkingnothingtext (the full text so far) and truncated

The server formats the payloads. A client shows strings and needs no knowledge of any tool.

Routes the client uses for the features on this page:

RouteUsed for
GET /tui-configThe start values of the switches.
GET /agents/:agent/system-prompt/verbose system on.
GET /agents/:agent/sessions/:session/workThe counters and the /queue list.
DELETE /chat/queue/:id/queue rm on a waiting entry.
POST /spawn-cancel/queue rm on a running sub-agent.
POST /chat/abortEsc, and /queue rm on a running question.
GET /agents/:agent/sessions/:session/export?format=…/export, with format being json or markdown.
GET /agents/:agent/sessions?include_archived=true/sessions archived, /unarchive with a name.
POST /agents/:agent/sessions/:session/unarchive/unarchive.
GET /config/statusThe config.yaml does not validate line.
POST /config/reload/reload.
POST /server/restart/restart YES.

Troubleshooting ​

No memory or tool lines appear. Look at the status line. A red mem ✗ or tools ✗ means the switch is off. Turn it on with /show memory on or /show tools on.

/verbose tools on did not expand the lines above. Switches apply to new lines only. The next tool call shows its payload.

No thinking block although the switch is on. The engine or model does not provide its reasoning, or thinkingContent.capture is false in config.yaml.

/projekt says the feature is disabled. Set projects.enabled: true in config.yaml.

/restart YES is refused. somora was started by hand and not as a service. Restart it the way you started it.

/queue says the server did not answer. The server is older than the client and has no work route. Update the server.

stream closed by server or stream error notices. The live connection dropped. The client reconnects by itself, first after half a second, then with growing pauses up to ten seconds.

After it is back it reads the session again. A reply that finished meanwhile appears in full, turns that started meanwhile follow, and a line says how many tool calls of that turn are not repeated. /export has them. An open question shows again with its options.

A notice ending in giving up means the agent or session no longer exists: switch with /agent or /session. A notice that the server refused the key means SOMORA_KEY is missing or wrong, see "Where the client connects".

No lettering in an empty session. The terminal is narrower than 22 columns, the locale is not UTF-8, or the lettering was already shown in this run.

See also ​

  • Thinking: thinking depth, and which engines show their reasoning
  • Sampling: the parameters behind /sampling and /temp
  • Projects: what a pinned project does
  • Memory: what the memory lines recall
  • Setup: engine internals such as the codex plan list, and HTTPS
  • Web client and Mobile app: the other clients
  • API: GET /tui-config, the work, export and queue routes