TUI
Using the Lunos terminal user interface.
Lunos provides an interactive terminal interface or TUI for working on your projects with an LLM.
Running Lunos starts the TUI for the current directory.
lunosOr you can start it for a specific working directory.
lunos /path/to/projectOnce you’re in the TUI, you can prompt it with a message.
Give me a quick summary of the codebase.File references
You can reference files in your messages using @. This does a fuzzy file search in the current working directory.
How is auth handled in @packages/functions/src/api/index.ts?The content of the file is added to the conversation automatically.
Configured references also appear in @ autocomplete. Type @alias to add the reference root as context, or type @alias/ to autocomplete files inside that reference.
Compare our setup with @docs/README.mdBash commands
Start a message with ! to run a shell command.
!ls -laThe output of the command is added to the conversation as a tool result.
Clearing the prompt
Press Esc twice to clear what you’ve typed and start again. The first Esc shows “esc again to clear” under the prompt; a second within a second clears the text, pasted blocks and @ references.
- Nothing is lost: the toast names the undo key (
input_undo,ctrl+-by default, plusctrl+zwhere the terminal doesn’t use it to suspend), which brings the prompt back as it was, and↑finds it in prompt history. - While the agent is working,
EscEscstops it as before, and what you’ve typed stays. - An
Escthat closes autocomplete, leaves shell mode or clears a selection doesn’t count as the first press. - It works the same in
/claudeand/codexsessions; the prompt is cleared in Lunos and nothing is sent to the tool. - Turn it off with
"double_escape_clear": false, or change the window withdouble_escape_ms.ctrl+c(input_clear) still clears the prompt at once.
Commands
When using the Lunos TUI, you can type / followed by a command name to quickly execute actions. For example:
/helpMost commands also have keyboard shortcuts using ctrl+x as the default leader key. Learn more.
Here are all available slash commands:
providers
Manage providers. Lists your configured providers with their status, auth method and jurisdiction. From there you can Add provider (log in with an API key or OAuth), Log out, or Set as default for model picker. The old name still works for now and shows a rename hint.
/providerscompact
Compact the current session. Alias: /summarize
/compactKeybind: ctrl+x c
details
Toggle tool execution details.
/detailseditor
Open external editor for composing messages. Uses the editor set in your EDITOR environment variable. Learn more.
/editorKeybind: ctrl+x e
exit
Exit Lunos. Aliases: /quit, /q
/exitKeybind: ctrl+x q
export
Export current conversation to Markdown and open in your default editor. Uses the editor set in your EDITOR environment variable. Learn more.
/exportKeybind: ctrl+x x
help
Show the help dialog.
/helpinit
Guided setup for creating or updating AGENTS.md. Learn more.
/initclaude
Give Claude Code a task from the prompt: /claude <task> starts a new Claude Code session with it,
in its own view. /claude on its own lets you pick a new session or continue a recent one in this
project. /codex does the same for Codex CLI (/codex /review runs its review). Listed while
external sessions are on; greyed out with the reason when the tool isn’t installed, isn’t signed in,
or is blocked by policy. See Claude Code and Codex CLI from Lunos.
/claude Fix the failing test/codex /reviewmarketplace
Browse and install plugins, skills, hooks and MCP servers from your marketplaces, one tab per kind (tab / shift+tab or a click switches; counts follow the search). Add a tab name (plugins, skills, hooks, mcp) to open that tab, installed to see what is installed with available updates first, or any other words to search every tab. Without words it opens on the tab you used last. Alias: /discover
/marketplace/marketplace mcp/marketplace playwrightmodels
List available models.
/modelsKeybind: ctrl+x m
new
Start a new session. Alias: /clear
/newKeybind: ctrl+x n
plugins
List installed plugins and turn them on or off.
/pluginsredo
Redo a previously undone message. Only available after using /undo.
Internally, this uses Git to manage the file changes. So your project needs to be a Git repository.
/redoKeybind: ctrl+x r
restart
Restart Lunos and come back to the same session, with whatever you had typed but not sent still in
the prompt. Use it after /update to run the new version, to pick up config changes, or to recover
from a stuck MCP server or LSP. Also in the command palette as Restart Lunos.
/restart/restart --fresh starts a new session instead (palette: Restart Lunos in a new session).
Lunos stops its MCP servers, LSP servers, memory sidecar and local server, restores the terminal,
and starts again with the same executable, arguments, working directory and environment, plus
--session <id>. The new process shows Restarted — Lunos X.Y.Z (X.Y.Z → A.B.C after an
update).
- While the agent is working (mid-turn, or background jobs running) Lunos asks first: wait
for the current turn, then restart; stop and restart, cancelling the running work (listed in
the banner afterwards;
/undoreverts file changes it made); or cancel. It never restarts silently while a tool may be writing files. While it waits,/restartagain cancels the restart. - With
lunos attachonly the TUI client restarts. The server keeps running, along with any turn it was working on. - On Windows the new Lunos starts in the same console window, and the old process stays behind, idle, until it exits (Windows can’t replace a running process the way Linux and macOS do).
- If the new process fails to start (for example because of a broken config file), Lunos prints the error and the exact command to start it by hand. It never retries.
Keybind: none by default; set app_restart in tui.json.
settings
Open the settings screen: every configuration option in one place. Alias: /config
/settings/settings key=value changes one setting without opening the screen, for example
/settings share=disabled. See Settings below.
status
Open the settings screen on its Status tab: version, the config files loaded, model, residency, memory, keys locked by your organisation, and MCP servers, LSP servers, formatters and plugins.
/statussessions
Every session on this machine, across all your projects: its state (running, waiting for approval,
idle, finished, failed), project, agent, model, last activity and cost, in your own groups. The
groups are the same ones the desktop app’s Sessions window and the web UI’s /sessions page show.
/sessionsType to search by name, project, state or group. Enter opens the selected session (a session
waiting for approval opens at its prompt) or collapses and expands a group. ctrl+o moves a session
to a group or to another project, ctrl+g creates a group, ctrl+r renames a session
or group, ctrl+d (twice) deletes a group without touching its sessions, ctrl+s stops a running
session and ctrl+f cycles the state filter.
projects
The project this folder counts in, and your named projects. A repository is a project with no setup;
a named project counts several repositories or directories as one, for example “Axsion web” for
axsion-web, axsion-api and infra. Named projects are kept on this computer only.
/projectsNew project… creates one, starting with this folder when it isn’t in one yet. Enter on a project
opens it: Add a folder… takes a path (~/…, /… or relative to this folder), Enter on a folder
removes it after asking, and Archive… puts the project away (its folders count in their
repositories’ projects again; Bring it back undoes it). The same commands are in the shell as
lunos project, and the named projects are listed in Settings › Projects.
With a budget, the line under the prompt shows the next turn’s estimate against
what’s left, for example est. €0.08–0.30 · €12.40 left of €50.00 (Oct), and the sidebar shows each
budget’s share used and forecast, updated as the turn runs. Settings › Projects › Budgets holds what
happens at the limit, the thresholds and the currency.
monitor
The Agent Monitor: every session on this computer beside a prompt that starts
new sessions or sends to the ones you tag with @ and their number. Also opened by ← on an empty
prompt and by <leader>o.
/monitorresume
List and switch between this project’s sessions, pin them and use the quick-switch slots.
Aliases: /continue
/resumeKeybind: ctrl+x l
share
Share current session. Off in Lunos unless you enable share in config.
/sharethemes
List available themes.
/themesKeybind: ctrl+x t
thinking
Toggle the visibility of thinking/reasoning blocks in the conversation. When enabled, you can see the model’s reasoning process for models that support extended thinking.
/thinkingtips
List every tip by category. Type to search; each tip is marked seen or new. Tips also show on the home screen and, once a turn has run for 3 seconds, as one line under the working indicator: a different one each time, and none repeats until you’ve seen them all. Which tips you’ve seen is kept on your computer only.
/tipstips_next shows another tip (unbound by default). Hide tips from the command palette, or turn
them off with "tips": false in tui.json.
undo
Undo last message in the conversation. Removes the most recent user message, all subsequent responses, and any file changes.
Internally, this uses Git to manage the file changes. So your project needs to be a Git repository.
/undoKeybind: ctrl+x u
unshare
Unshare current session.
/unsharewhatsnew
Show what changed since your previous version: behaviour changes and security entries first, then
what’s new and a count of fixes, taken from the release notes built into Lunos (no network). The
same panel opens by itself once, on the first start after an update. Turn that off with
"whats_new": false in tui.json; /whatsnew keeps working.
/whatsnewupdate
Update Lunos to the latest version. Also available as /upgrade, its old name.
/updateWhen a new version is published, the bottom-right corner of every screen shows
There is a new version: X.Y.Z — please run lunos update (New version: X.Y.Z · lunos update in
terminals narrower than 100 columns) until you update. While /update runs, that corner shows the step
and the elapsed time instead, and you can keep using the prompt. After updating, run /restart to
use the new version: it starts the newly installed Lunos, not the old binary, back in the same
session. See lunos update for when the check runs and how to turn it off.
Settings
/settings (or /config, or lunos settings from the shell) opens one dialog with three tabs,
Status | Settings | Usage. Tab and Shift+Tab switch tabs, Esc closes. /status opens the same
dialog on the Status tab.
The Settings tab opens on a list of sections, each with a short summary of what’s set and badges for settings changed from the default, locked by your organisation (🔒) and saved changes waiting for a restart (↻). Enter opens a section in its own window; where it has distinct parts, they’re sub-tabs (Tab / Shift+Tab or a click switches):
| Section | Sub-tabs |
|---|---|
| Models & agents | Models · Agents · Providers · External sessions |
| Projects | Projects (your named projects, kept on this computer) · Budgets |
| Permissions | Rules · Tools · Sandbox |
| Residency & privacy | Residency · Audit · Sharing |
| Memory | Overview (status, guided setup, analytics) · Settings · Advanced |
| Marketplace & plugins | Marketplaces · Plugins · Policy |
| Appearance | Theme · Layout |
| Tools | LSP · Formatters · MCP · Commands · Skills · Hooks · Shell · References |
| Updates, Advanced | one window each |
The title shows where you are (Settings › Memory › Advanced); ← goes back a level. Typing on the
home searches every setting, each result with where it lives, and Enter opens it there. Inside a
section, typing searches that section. /settings memory, /settings tools lsp or
/settings models external open a section or sub-tab directly.
Every option in opencode.json and tui.json is in exactly one section, generated from the config
schema, so new options appear without a TUI update. Each row shows the current value and where it
comes from:
| Badge | Meaning |
|---|---|
default | Not set anywhere; the built-in default applies |
user | Your user config (~/.config/opencode/opencode.json[c], or tui.json for the TUI) |
project | The project’s config (opencode.json or .opencode/opencode.json[c]) |
env | An environment variable or OPENCODE_CONFIG* wins over the files |
managed 🔒 | Set by your organisation’s managed config; it can’t be changed here |
remote | Loaded from a well-known or console organisation config |
Start typing to filter by name, key or description (resid shows the residency settings). The
highlighted row’s description, the file it comes from, and any lock, environment override or
restart note show below the list.
| Key | Action |
|---|---|
| Enter | Change the setting (see below) |
| Space | Toggle an on/off setting, or move an option setting to its next value |
| Ctrl+S | Switch where changes are saved: your user config (default) or this project’s |
| Tab | Next tab (inside a section: next sub-tab) |
| ← | Back one level, to the row you came from (in a text field: from the start of it) |
| Esc | Close the whole settings window from any screen in it; what you were typing is lost |
How Enter changes a setting depends on its type:
- On/off: toggles.
- A fixed set of values (
share,autoupdate,logLevel…): pick from a list. - Model and theme: open the usual model and theme pickers; the choice is saved to the config.
- Default agent: pick one of the main agents (shown with what they do), make a new one (it becomes the default once both its name and description are entered), or Clear to use Lunos’s default. New sessions start with it. A default that names a subagent, a hidden agent or one that’s turned off is marked ⚠.
- Recommended: the models the pickers list under Recommended (ctrl+l), each with why. Unset, it’s Lunos’s curated list, marked “Lunos default”. Add model… opens the model picker and asks for an optional reason (up to 50 characters); Enter on a model edits its reason or removes it; Reset to Lunos defaults removes the key from the scope you’re saving to. The first change writes the whole list to that scope. The pickers show the new list at once, without a restart.
- Reasoning variant (
subagent.variant, an agent’s Variant): pick from the variants of the model it applies to (the subagent’s or agent’s model, or the main model it inherits), or Inherit; Clear removes the key. A saved variant that model doesn’t have is markednot available for <model>, and requests use the model’s default effort. - Text, numbers and lists: an inline prompt. Lists are comma-separated (
eu, us). - MCP servers and providers: open the
/mcpsand/providersdialogs. - Structured settings made of simple fields (
subagent,compaction,sandbox,memory…): open a screen of their own fields, with the same controls. The Subagent screen has Run in background, Model, Variant, “Let the main agent choose a model per task” and Allowed models. - Other structured settings (
permission,lsp,hooks…): open the config file in$EDITOR, or show its path when no editor is set.
Every change is checked against the config schema before it’s written, and an invalid value is
refused with the allowed values listed; nothing is written. Changes are saved to the user config
(.opencode/opencode.json for the project scope, or tui.json for TUI settings such as the
theme), and comments and formatting in the file are kept. Most changes apply at once; settings that
need a restart (plugins, MCP servers, memory, LSP, formatters, server, TUI options other than the
theme) are marked ↻ and offer to run /restart after saving.
- Locked settings. Keys your organisation locks in managed config (
$locked) show 🔒 and can’t be changed, from this screen,/settings key=valueorlunos settings set. - Environment overrides. When an environment variable decides a value (for example
LUNOS_DISABLE_MEMORYorOPENCODE_DISABLE_AUTOUPDATE), the row says so: editing the file won’t take effect until the variable is removed. - Secrets such as API keys are never shown: they’re masked, and managed in
/providers. Values written as{env:NAME}or{file:path}show the reference, not what it resolves to.
The Usage tab shows tokens and cost for the current session and for the last 30 days, from the
same data as lunos stats.
Editor setup
Both the /editor and /export commands use the editor specified in your EDITOR environment variable.
# Example for nano or vimexport EDITOR=nanoexport EDITOR=vim
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.# include --waitexport EDITOR="code --wait"To make it permanent, add this to your shell profile;
~/.bashrc, ~/.zshrc, etc.
set EDITOR=notepad
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.# include --waitset EDITOR=code --waitTo make it permanent, use System Properties > Environment Variables.
$env:EDITOR = "notepad"
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.# include --wait$env:EDITOR = "code --wait"To make it permanent, add this to your PowerShell profile.
Popular editor options include:
code- Visual Studio Codecursor- Cursorwindsurf- Windsurfnvim- Neovim editorvim- Vim editornano- Nano editornotepad- Windows Notepadsubl- Sublime Text
Some editors need command-line arguments to run in blocking mode. The --wait flag makes the editor process block until closed.
Configure
You can customize TUI behavior through tui.json (or tui.jsonc).
{ "$schema": "https://lunos.tech/tui.json", "theme": "lunos", "leader_timeout": 2000, "keybinds": { "leader": "ctrl+x", "command_list": "ctrl+p" }, "scroll_speed": 3, "scroll_acceleration": { "enabled": false }, "diff_style": "auto", "cursor": { "style": "block", "blinking": true }, "mouse": true, "attention": { "enabled": true, "notifications": true, "sound": true, "volume": 0.4, "sound_pack": "lunos.default", "sounds": { "error": "./sounds/error.mp3" } }}This is separate from opencode.json, which configures server/runtime behavior.
keybinds is merged with built-in defaults, so you only need to configure the shortcuts you want to change.
Options
theme- Sets your UI theme. Learn more.keybinds- Customizes keyboard shortcuts. Learn more.leader_timeout- Controls how long Lunos waits after the leader key. Defaults to2000.scroll_acceleration.enabled- Enable macOS-style scroll acceleration for smooth, natural scrolling. When enabled, scroll speed increases with rapid scrolling gestures and stays precise for slower movements. This setting takes precedence overscroll_speedand overrides it when enabled.scroll_speed- Controls how fast the TUI scrolls when using scroll commands (minimum:0.001, supports decimal values). Defaults to3. Note: This is ignored ifscroll_acceleration.enabledis set totrue.diff_style- Controls diff rendering."auto"adapts to terminal width,"stacked"always shows a single-column layout.external_accent-falsekeeps your theme’s colours in Claude Code and Codex sessions; the▸ Claude Codelabel andLunos · Claude Codebadge stay (default:true).double_escape_clear-falseturns off clearing the prompt withEscEsc(default:true).double_escape_ms- Milliseconds in which the secondEscclears the prompt (default:1000).left_opens_monitor-falsestops ← on an empty prompt from opening the Agent Monitor (default:true)./monitorand<leader>ostill open it.tips-falseturns off the tips on the home screen and under the working indicator (default:true)./tipsstill lists them.whats_new-falsestops the “What’s new” panel on the first start after an update (default:true)./whatsnewandlunos changelogstill work.reduced_motion-trueturns off every animation (the home screen’s moon reflection, spinners, placeholder cycling), and the in-app “Disable animations” toggle can’t turn them back on. When unset, animations are off by default ifNO_COLORis set orTERM=dumb, and the toggle decides.
For a high-contrast display, set "theme": "high-contrast" (see Themes).
cursor- Controls the terminal cursor in TUI input fields.styledefaults to"block", can be"underline","line", or"default";blinkingdefaults totrue. Whenstyleis"default", the terminal default cursor is restored, soblinkinghas no effect.mouse- Enable or disable mouse capture in the TUI (default:true). When disabled, the terminal’s native mouse selection/scrolling behavior is preserved.attention- Configures TUI desktop notifications and sounds. Disabled by default.
Use OPENCODE_TUI_CONFIG to load a custom TUI config path.
Attention
The TUI can request attention for questions, permissions, session errors, and completed sessions. Enable it with attention.enabled; built-in events play sounds when triggered, and non-subagent events request desktop notifications only when the terminal is blurred.
enabled- Enable all attention notifications and sounds. Defaults tofalse.notifications- Allow terminal-mediated desktop notifications when attention is enabled. Defaults totrue.sound- Allow attention sounds when attention is enabled. Defaults totrue.volume- Default sound volume from0to1. Defaults to0.4.sound_pack- Sound pack ID to use. Defaults tolunos.default.sounds- Override sound files fordefault,question,permission,error,done, orsubagent_done. Paths can be absolute,file://URLs, or relative totui.json.
Customization
You can customize various aspects of the TUI view using the command palette (ctrl+p). These settings persist across restarts.
Username display
Toggle whether your username appears in chat messages. Access this through:
- Command palette: Search for “username” or “hide username”
- The setting persists automatically and will be remembered across TUI sessions