Skip to content
FrownCode
app.header.homeapp.header.docs

TUI

Using the FrownCode terminal user interface.

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

Running FrownCode starts the TUI for the current directory.

Terminal window
frown

Or you can start it for a specific working directory.

Terminal window
frown /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.

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 FrownCode TUI, you can type / followed by a command name to quickly execute actions. For example:

/help

Most commands also have keybind using ctrl+x as the leader key, where ctrl+x is the default leader key. Learn more.

Here are all available slash commands:

connect

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

/connect

compact

Compact the current session. Alias: /summarize

/compact

Keybind: ctrl+x c

details

Toggle tool execution details.

/details

Keybind: ctrl+x d

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 FrownCode. Aliases: /close, /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

btw

Send an in-between question or side instruction without changing the normal slash-command flow.

/btw also keep the current task, but make the UI denser

Use this when you want to inject a clarification, side note, or extra ask mid-session.

help

Show the help dialog.

/help

Keybind: ctrl+x h

init

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

/init

Keybind: ctrl+x i

models

List available models.

/models

Keybind: ctrl+x m

auto

Tune how Auto chooses a model.

/auto quality
/auto prefer provider openai anthropic
/auto avoid model mini

Supported forms:

  • /auto show
  • /auto reset
  • /auto balanced
  • /auto quality
  • /auto speed
  • /auto cheap
  • /auto reasoning on
  • /auto reasoning off
  • /auto prefer provider ...
  • /auto avoid provider ...
  • /auto prefer model ...
  • /auto avoid model ...

These rules are shared with the desktop app and affect the Auto model option everywhere.

auto-rules

Open the dedicated TUI dialog for configuring Auto model routing.

/auto-rules

You can also open it from the model picker through Auto Rules....

new

Start a new session. Alias: /clear

/new

Keybind: ctrl+x n

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

sessions

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

/sessions

Keybind: ctrl+x l

share

Share current session. Learn more.

/share

Keybind: ctrl+x s

themes

List available themes.

/themes

Keybind: ctrl+x t

caveman

Configure built-in Caveman response mode. FrownCode enables it by default.

/caveman ultra

Available values:

  • on
  • off
  • lite
  • full
  • ultra

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

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. Learn more.

/unshare

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://frown.ammar.click/tui.json",
  "theme": "frowncode",
  "keybinds": {
    "leader": "ctrl+x"
  },
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto",
  "mouse": true
}

This is separate from frowncode.json, which configures server/runtime behavior.

Options

  • theme - Sets your UI theme. Learn more.
  • keybinds - Customizes keyboard shortcuts. Learn more.
  • 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.
  • mouse - Enable or disable mouse capture in the TUI (default: true). When disabled, the terminal’s native mouse selection/scrolling behavior is preserved.

Use FROWNCODE_TUI_CONFIG to load a custom TUI config path.

Frown defaults

FrownCode ships with a few opinionated defaults compared to the original base:

  • purple-first terminal styling
  • Caveman mode enabled by default
  • /close as a direct exit alias
  • /btw for side questions or mid-task nudges
  • shared Auto model routing with visible pick reasons
  • dedicated Auto Rules... dialog in the TUI model picker
  • earlier automatic context compaction near 85% usage

If you keep the model on Auto, FrownCode can choose from your connected providers based on:

  • balanced, quality, speed, or cheap mode
  • reasoning requirement
  • preferred providers
  • avoided providers
  • preferred model patterns
  • avoided model patterns
  • media support required by the current prompt

Compaction can be tuned in frowncode.json:

frowncode.json
{
  "compaction": {
    "auto": true,
    "threshold": 0.85,
    "reserved": 20000
  }
}

Customization

You can customize various aspects of the TUI view using the command palette (ctrl+x h or /help). 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