Skip to content

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.

Terminal window
lunos

Or you can start it for a specific working directory.

Terminal window
lunos /path/to/project

Once 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.md

Bash commands

Start a message with ! to run a shell command.

!ls -la

The 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, plus ctrl+z where 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, Esc Esc stops it as before, and what you’ve typed stays.
  • An Esc that closes autocomplete, leaves shell mode or clears a selection doesn’t count as the first press.
  • It works the same in /claude and /codex sessions; 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 with double_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:

/help

Most 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.

/providers

compact

Compact the current session. Alias: /summarize

/compact

Keybind: ctrl+x c


details

Toggle tool execution details.

/details

editor

Open external editor for composing messages. Uses the editor set in your EDITOR environment variable. Learn more.

/editor

Keybind: ctrl+x e


exit

Exit Lunos. Aliases: /quit, /q

/exit

Keybind: 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.

/export

Keybind: ctrl+x x


help

Show the help dialog.

/help

init

Guided setup for creating or updating AGENTS.md. Learn more.

/init

claude

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 /review

marketplace

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 playwright

models

List available models.

/models

Keybind: ctrl+x m


new

Start a new session. Alias: /clear

/new

Keybind: ctrl+x n


plugins

List installed plugins and turn them on or off.

/plugins

redo

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.

/redo

Keybind: 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; /undo reverts file changes it made); or cancel. It never restarts silently while a tool may be writing files. While it waits, /restart again cancels the restart.
  • With lunos attach only 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.

/status

sessions

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.

/sessions

Type 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.

/projects

New 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.

/monitor

resume

List and switch between this project’s sessions, pin them and use the quick-switch slots. Aliases: /continue

/resume

Keybind: ctrl+x l


share

Share current session. Off in Lunos unless you enable share in config.

/share

themes

List available themes.

/themes

Keybind: 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.

/thinking

tips

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.

/tips

tips_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.

/undo

Keybind: ctrl+x u


unshare

Unshare current session.

/unshare

whatsnew

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.

/whatsnew

update

Update Lunos to the latest version. Also available as /upgrade, its old name.

/update

When 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):

SectionSub-tabs
Models & agentsModels · Agents · Providers · External sessions
ProjectsProjects (your named projects, kept on this computer) · Budgets
PermissionsRules · Tools · Sandbox
Residency & privacyResidency · Audit · Sharing
MemoryOverview (status, guided setup, analytics) · Settings · Advanced
Marketplace & pluginsMarketplaces · Plugins · Policy
AppearanceTheme · Layout
ToolsLSP · Formatters · MCP · Commands · Skills · Hooks · Shell · References
Updates, Advancedone 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:

BadgeMeaning
defaultNot set anywhere; the built-in default applies
userYour user config (~/.config/opencode/opencode.json[c], or tui.json for the TUI)
projectThe project’s config (opencode.json or .opencode/opencode.json[c])
envAn environment variable or OPENCODE_CONFIG* wins over the files
managed 🔒Set by your organisation’s managed config; it can’t be changed here
remoteLoaded 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.

KeyAction
EnterChange the setting (see below)
SpaceToggle an on/off setting, or move an option setting to its next value
Ctrl+SSwitch where changes are saved: your user config (default) or this project’s
TabNext 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)
EscClose 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 marked not 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 /mcps and /providers dialogs.
  • 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=value or lunos settings set.
  • Environment overrides. When an environment variable decides a value (for example LUNOS_DISABLE_MEMORY or OPENCODE_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.

Terminal window
# Example for nano or vim
export EDITOR=nano
export EDITOR=vim
# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
# include --wait
export EDITOR="code --wait"

To make it permanent, add this to your shell profile; ~/.bashrc, ~/.zshrc, etc.

Popular editor options include:

  • code - Visual Studio Code
  • cursor - Cursor
  • windsurf - Windsurf
  • nvim - Neovim editor
  • vim - Vim editor
  • nano - Nano editor
  • notepad - Windows Notepad
  • subl - 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).

tui.json
{
"$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 to 2000.
  • 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 over scroll_speed and overrides it when enabled.
  • scroll_speed - Controls how fast the TUI scrolls when using scroll commands (minimum: 0.001, supports decimal values). Defaults to 3. Note: This is ignored if scroll_acceleration.enabled is set to true.
  • diff_style - Controls diff rendering. "auto" adapts to terminal width, "stacked" always shows a single-column layout.
  • external_accent - false keeps your theme’s colours in Claude Code and Codex sessions; the ▸ Claude Code label and Lunos · Claude Code badge stay (default: true).
  • double_escape_clear - false turns off clearing the prompt with Esc Esc (default: true).
  • double_escape_ms - Milliseconds in which the second Esc clears the prompt (default: 1000).
  • left_opens_monitor - false stops ← on an empty prompt from opening the Agent Monitor (default: true). /monitor and <leader>o still open it.
  • tips - false turns off the tips on the home screen and under the working indicator (default: true). /tips still lists them.
  • whats_new - false stops the “What’s new” panel on the first start after an update (default: true). /whatsnew and lunos changelog still work.
  • reduced_motion - true turns 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 if NO_COLOR is set or TERM=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. style defaults to "block", can be "underline", "line", or "default"; blinking defaults to true. When style is "default", the terminal default cursor is restored, so blinking has 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 to false.
  • notifications - Allow terminal-mediated desktop notifications when attention is enabled. Defaults to true.
  • sound - Allow attention sounds when attention is enabled. Defaults to true.
  • volume - Default sound volume from 0 to 1. Defaults to 0.4.
  • sound_pack - Sound pack ID to use. Defaults to lunos.default.
  • sounds - Override sound files for default, question, permission, error, done, or subagent_done. Paths can be absolute, file:// URLs, or relative to tui.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