Using the TUI

Introduction

Colours, Markdown Streaming and Scrollback

fast-agent streams reasoning, assistant responses and tool calls to the console, rendering markdown while protecting the scrollback buffer.

ANSI colours are used throughout to match your existing preferences. OSC133 and prominent final response markers are used to assist scrollback navigation.

The apply_patch tool (supplied, and exposed by default to > GPT-5.2 models) has highlighting applied during streaming.

Tools can be labelled as generating python code for syntax highlighting (especially useful when integrating with Pydantic Monty)

Markdown element colours are themeable with logger.theme_file and fenced-code rendering uses logger.code_theme. Use LOGGER__THEME_FILE and LOGGER__CODE_THEME to set these from the environment.

Use /history detail to review the full contents.

Shell Integration

You can run a shell command with ! - for example ! git status. You can enter an interactive shell by typing ! Enter. Child shells get FAST_AGENT_SHELL_CHILD=1. Type exit to return to fast-agent.

File names and paths can be automatically completed with either Tab or Ctrl+Space.

The recording below shows fast-agent starting with a model, a normal prompt, and a shell command run from inside the TUI.

File Previews

When the internal read_text_file tool is used, by default 5 lines of the file are displayed. Adjust this with shell_execution.output_display_lines, SHELL_EXECUTION__OUTPUT_DISPLAY_LINES, or fast-agent config shell.

Image Viewer

Images received from the Assistant or tool calls are rendered to the console on the final turn. Local images that you attach to a user message are previewed in the user panel beneath the attachment link text.

Configure image rendering with logger.terminal_images or the matching nested environment variables:

logger:
  terminal_images:
    enabled: true
    backend: auto       # auto, textual-image, kitty, sixel, halfcell, unicode, none
    width: 80%
    height: auto
    render_assistant: true

For example, use LOGGER__TERMINAL_IMAGES__ENABLED=false to disable terminal image rendering or LOGGER__TERMINAL_IMAGES__BACKEND=kitty to choose a backend.

Paste and Attach Images / Documents

You can attach images and documents using /attach or by using the ^<uri|file> syntax. The indicator in the status bar shows a count of attachments, and is green if they are found, red if there is an error. Press F10 to clear all attachments.

You can paste images directly with Alt+V. In terminals that reserve that chord, Ctrl+Alt+V is also bound.

Local image attachments, including pasted clipboard images, are displayed inline after your message when terminal image rendering is enabled. Remote image URLs remain as links.

Model Feature Toggles

Use the function keys in the prompt to cycle model-specific runtime features:

Key	Action
`F6`	Cycle reasoning effort
`F7`	Cycle text verbosity
`F8`	Toggle or cycle web search
`F9`	Toggle or cycle web fetch

These toggles apply when the selected model/provider supports the feature.

Prompt Shortcuts

Key	Action
`Ctrl`+`Enter`	Submit in multiline mode
`Ctrl`+`Space`	Open completion menu
`Tab`	Complete path/command, or cycle completions
`Shift`+`Tab`	Cycle completions backwards; otherwise cycle service tier when available
`Ctrl`+`T`	Toggle multiline mode
`Ctrl`+`E`	Edit the current buffer in `$EDITOR`
`Ctrl`+`Y`	Copy the last assistant or shell output
`Ctrl`+`L`	Redraw the screen
`Ctrl`+`U`	Clear the input buffer
`Ctrl`+`C`	Cancel the current operation; press twice quickly to exit
`Ctrl`+`D`	End the prompt session

Changing Settings

Use fast-agent config to configure your preferences:

fast-agent config display edits console display, markdown rendering, streaming, and prompt mark settings.
fast-agent config shell edits shell execution and file preview settings.

You can also set any config value through environment variables by joining nested setting names with double underscores.

TUI environment variables

Symbol	Variable	Purpose
`FAST_AGENT_SHELL_CHILD_ENV`	`FAST_AGENT_SHELL_CHILD`	Set to `1` in child shells opened from the TUI with `!`.

Setting	Environment variable	Type	Default	Description
`logger.streaming`	`LOGGER__STREAMING`	`Literal['markdown', 'plain', 'none']`	`markdown`	Streaming renderer for assistant responses.
`logger.enable_prompt_marks`	`LOGGER__ENABLE_PROMPT_MARKS`	`bool`	`True`	Emit OSC 133 prompt marks for supported terminals.
`logger.progress_display`	`LOGGER__PROGRESS_DISPLAY`	`bool`	`True`	Enable or disable progress display.
`logger.show_chat`	`LOGGER__SHOW_CHAT`	`bool`	`True`	Show user and assistant messages on the console.
`logger.show_tools`	`LOGGER__SHOW_TOOLS`	`bool`	`True`	Show MCP server tool calls on the console.
`logger.truncate_tools`	`LOGGER__TRUNCATE_TOOLS`	`bool`	`True`	Truncate long tool call display.
`logger.theme_file`	`LOGGER__THEME_FILE`	`str \\| None`	`None`	Optional Rich theme file for console styles.
`logger.code_theme`	`LOGGER__CODE_THEME`	`str`	`native`	Pygments/Rich syntax theme for Markdown code rendering.
`logger.render_fences_with_syntax`	`LOGGER__RENDER_FENCES_WITH_SYNTAX`	`bool`	`True`	Render Markdown code fences with Rich Syntax.
`logger.code_word_wrap`	`LOGGER__CODE_WORD_WRAP`	`bool`	`True`	Wrap Syntax-rendered code blocks instead of cropping.
`logger.apply_patch_preview_max_lines`	`LOGGER__APPLY_PATCH_PREVIEW_MAX_LINES`	`int \\| None`	`120`	Maximum lines to show in apply_patch previews.
`logger.terminal_images.enabled`	`LOGGER__TERMINAL_IMAGES__ENABLED`	`bool`	`True`	Render image content in capable terminals.
`logger.terminal_images.backend`	`LOGGER__TERMINAL_IMAGES__BACKEND`	`Literal['auto', 'textual-image', 'kitty', 'sixel', 'halfcell', 'unicode', 'none']`	`auto`	Terminal image backend to use.
`logger.terminal_images.width`	`LOGGER__TERMINAL_IMAGES__WIDTH`	`TerminalImageSize`	`80%`	Image render width.
`logger.terminal_images.height`	`LOGGER__TERMINAL_IMAGES__HEIGHT`	`TerminalImageSize`	`auto`	Image render height.
`shell_execution.output_display_lines`	`SHELL_EXECUTION__OUTPUT_DISPLAY_LINES`	`int \\| None`	`5`	Maximum shell/read_text_file lines to display.
`shell_execution.show_bash`	`SHELL_EXECUTION__SHOW_BASH`	`bool`	`True`	Show shell command output on the console.
`shell_execution.interactive_use_pty`	`SHELL_EXECUTION__INTERACTIVE_USE_PTY`	`bool`	`True`	Use a PTY for interactive prompt shell commands.
`shell_execution.timeout_seconds`	`SHELL_EXECUTION__TIMEOUT_SECONDS`	`int`	`90`	Maximum seconds without command output before termination.
`shell_execution.warning_interval_seconds`	`SHELL_EXECUTION__WARNING_INTERVAL_SECONDS`	`int`	`30`	Show timeout warnings every N seconds.
`tui.completion_menu_reserved_lines`	`TUI__COMPLETION_MENU_RESERVED_LINES`	`int`	`6`	Prompt-toolkit lines reserved below the input for completion menus.

Detailed Configuration Reference

See the Configuration Reference for the full set of settings.