TUI

hordecode provides an interactive terminal interface or TUI for working on your projects with an LLM.

Running hordecode starts the TUI for the current directory.

horde

Or you can start it for a specific working directory.

horde /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.

Tip

You can also use @ to reference files in your messages.

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.

---

Commands

When using the hordecode 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:

---

connect

Add a provider to hordecode. Allows you to select from available providers and add their API keys.

/connect

---

advisor

Turn the advisor on or off, pick its model from the connected providers, set the sensitivity (low, default or high) and choose whether all notes are shown or only concerns and blockers. Changes apply without a restart.

/advisor

The on/off switch applies to the running process only and is never written to your config. Model, sensitivity and notes are saved to your global config. To have the advisor on in every session, set experimental.advisor.enabled and a model in config.

Each review appears in the conversation as an Advisor row that lists the notes by severity, or says “reviewed this step, no notes”. When the advisor model is unavailable, or the call fails or takes longer than 60 seconds, the row says “review failed” with the reason and the agent continues without notes. The row is shown to you only; the agent sees the notes once, in that step. While the advisor is on, the prompt footer shows advisor.

---

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

---

models

List available models.

/models

Keybind: ctrl+x m

---

new

Start a new session. Alias: /clear

/new

Keybind: ctrl+x n

---

redo

Redo a previously undone message. Only available after using /undo.

Tip

Any file changes will also be restored.

Internally, this uses Git to manage the file changes. So your project needs to be a Git repository.

/redo

Keybind: ctrl+x r

---

sessions

List and switch between sessions. Aliases: /resume, /continue

/sessions

Keybind: ctrl+x l

---

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.

Note

This command only controls whether thinking blocks are displayed - it does not enable or disable the model’s reasoning capabilities. To toggle actual reasoning capabilities, use ctrl+t to cycle through model variants.

/thinking

---

undo

Undo last message in the conversation. Removes the most recent user message, all subsequent responses, and any file changes.

Tip

Any file changes made will also be reverted.

Internally, this uses Git to manage the file changes. So your project needs to be a Git repository.

/undo

Keybind: ctrl+x u

---

Palette entries

These hordecode entries are opened from the command palette (ctrl+p).

Hordecode features

Under System. Edits the experimental switches and the memory.embedding setting together, and asks for a restart when you save. An environment variable that is set still wins over the config, and the dialog shows it next to that row. Use the arrow keys to move, Space to toggle and Enter to save.

Guardrail profile

Under Agent. Switches between careful, normal and auto. Learn more.

View status

Keybind: ctrl+x s

Lists the OpenTelemetry endpoints the server exports to, without credentials or query strings, or “No OpenTelemetry export”. Learn more.

Config keys that hordecode does not know are announced once after startup with a warning toast. Learn more.

---

Sidebar

The right-hand column shows a stack of panels about the current session. Click a panel title to collapse or expand it. Panels that have nothing to show stay hidden until they do.

Telemetry

The Telemetry panel is headed by a count of replies: the assistant messages that have completed in this session.

• Context - Tokens used against the model’s context limit, with a five-cell bar and a percentage. The value is muted normally, turns warning at 70% and error at 90%.
• Tokens - Input, output and reasoning tokens for the session.
• Cache - Prompt-cache hit rate: cached reads divided by input plus cached reads.
• Tools - Total tool calls, how many succeeded or errored, and calls per reply.
• Speed - Output tokens per second and average request latency.
• TTL - Prompt-cache state for Anthropic models, shown once a request has used the cache: warm with the time left, or cold with the tokens (and the estimated cost) the next turn re-caches.
• Usage - Session cost and total tokens.

The panel refreshes every 250 ms while a reply is streaming.

Activity

The Activity panel counts Prompts: the user messages in the session. It has three views, shown as [Overview], [Tools] or [Tokens]. Click the view switcher, or run Activity: next tab from the command palette (default keybind ctrl+x v, configurable as sidebar_activity_next), to cycle them.

Overview shows Uptime, Prompts, Model, Tools, Spent, and a Live timer while a tool is running. When a tool runs long, a Warning row appears:

Time running	Warning row	Color
5 minutes or more	5m+ op	warning
30 minutes or more	30m+ op	warning
2 hours or more	2h+ op!	error

Tools aggregates calls by tool name and shows calls x average/maximum duration, with the error count in red. Tokens shows the total and a row per agent with io, rsn and cr values.

Subagents

The Subagents panel lists the current session’s subagent rows and its one-level children, with the header N active, M done.

Glyph	Status	Color
*	pending or running	accent
v	completed	muted
x	failed	error
-	cancelled	muted
?	unknown	muted

Each row reads agent -- description. A finished row leaves the panel 60 seconds after its last status change. The panel collapses when it holds more than two rows.

Tasks

The Tasks panel shows active tasks first, in the order in_progress, open, blocked, then the three most recent completed tasks. Select N more done to expand the rest, or fewer done to collapse them again.

Marker	Meaning
blank	open
spinner inside [ ]	in progress, while the session or one of its subagents is busy or retrying
•	in progress, while the session tree is idle
✓	done
⏸	blocked

The spinner runs only while work is actually happening: the session’s own status is busy or retrying, or one of its one-level subagent sessions is. When the tree goes idle the spinner becomes a static dot. Task rows are indented by their id depth, so T1.2 sits under T1.

Modified Files

The Modified Files panel appears when the session has changed files. Each row shows the file path truncated to fit 36 columns, with additions in the diff-added color and deletions in the diff-removed color. The panel collapses when it holds more than two files.

Context and other panels

A compact ctx N% line shows context pressure. Its color steps through success below 50%, info from 50% to 69%, warning from 70% to 84%, and error at 85% and above.

The sidebar also shows Directory (path:branch), Instructions (N files), MCP (N/M active, K err), Loops (N armed, M loop), LSP (N active), Goal (the judge’s verdict and round) and Todo (when the session has no task board).

---

Editor setup

Both the /editor and /export commands use the editor specified in your EDITOR environment variable.

Linux/macOS

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

Windows (CMD)

set EDITOR=notepad

# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
# include --wait
set EDITOR=code --wait

To make it permanent, use System Properties > Environment Variables.

Windows (PowerShell)

$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 Code
• cursor - Cursor
• windsurf - Windsurf
• nvim - Neovim editor
• vim - Vim editor
• nano - Nano editor
• notepad - Windows Notepad
• subl - Sublime Text

Note

Some editors like VS Code need to be started with the --wait flag.

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://hordecode.com/tui.json",
  "theme": "hordecode",
  "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": "hordecode.default",
    "sounds": {
      "error": "./sounds/error.mp3"
    }
  }
}

This is separate from hordecode.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 hordecode 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.
• 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 HORDECODE_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 hordecode.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