Configuration
TUI

TUI

TUI (Terminal User Interface) Mode provides a modern, visually rich terminal interface for AI pair programming.

Activation

The TUI is the default in recent versions of Cecli and on older versions it can be started explicitly in the terminal with:

cecli ... --tui

Configuration

The TUI can be configured directly in the relevant config.json file or with JSON in the command line arguments:

Minimal Configuration

tui: true

Complete Configuration Example

The base theme is pretty nice but if you want different colors and key bindings, you can specify them in the configuration files (~/.cecli/conf.yml or .cecli.conf.yml):

tui: true
tui-config:
  colors:
    primary: "#00ff5f"
    secondary: "#888888"
    accent: "#00ff87"
    foreground: "#ffffff"
    background: "#1e1e1e"
    success: "#00aa00"
    warning: "#ffd700"
    error: "#ff3333"
    surface: "transparent"
    panel: "transparent"
    input-cursor-foreground: "#00ff87"
  other:
    dark: true
    input-cursor-text-style: "underline"
    use_terminal_background: false
  key_bindings:
    newline: "shift+enter"
    submit: "enter"
    completion: "tab"
    stop: "escape"
    editor: "ctrl+o"
    history: "ctrl+r"
    cycle_forward: "tab"
    cycle_backward: "shift+tab"
    input_start: "ctrl+home"
    input_end: "ctrl+end"
    output_up: "shift+pageup"
    output_down: "shift+pagedown"
    focus: "ctrl+f"
    cancel: "ctrl+c"
    clear: "ctrl+l"
    quit: "ctrl+q"
    next_agent: "alt+ctrl+right"
    prev_agent: "alt+ctrl+left"
    main_agent: "alt+ctrl+up"

Key Command Configuration

The TUI provides customizable key bindings for all major actions. The default key bindings are:

Action	Default Key	Description
New Line	`shift+enter`	Insert a new line in the input area (internally maps to `ctrl+j` if your editor hates `shift+enter`)
Submit	`enter`	Submit the current input
Cancel	`ctrl+c`	Stop and stash current input prompt
Stop	`escape`	Interrupt the current LLM response or task
Editor	`ctrl+o`	Open up default terminal text editor for input
Search History	`ctrl+r`	Search through history for previous commands (requires fzf to be installed)
Cycle Forward	`tab`	Cycle forward through completion suggestions
Cycle Backward	`shift+tab`	Cycle backward through completion suggestions
Input Start	`ctrl+home`	Move cursor to start of first line
Input End	`ctrl+end`	Move cursor to end of last line
Output Up	`pageup`	Scroll the output area up one page
Output Down	`pagedown`	Scroll the output area down one page
Focus	`ctrl+f`	Focus the input area
Clear	`ctrl+l`	Clear the output area
Quit	`ctrl+q`	Exit the TUI
Next Agent	`alt+ctrl+right`	Switch to the next agent (sub-agent or primary), wrapping around
Previous Agent	`alt+ctrl+left`	Switch to the previous agent (sub-agent or primary), wrapping around
Main Agent	`alt+ctrl+up`	Switch back to the main (primary) agent

Customizing Key Bindings

You can customize any key binding by adding a key_bindings section to your tui-config. For example, to change the quit key to ctrl+x:

tui-config:
  key_bindings:
    quit: "ctrl+x"

All key bindings use Textual’s key syntax:

Single keys: enter, escape, tab
Modifier combinations: ctrl+c, shift+tab, etc.

Warning: key bindings may not work if they conflict with the textual library defaults at:

Textual Documentation

Benefits

Improved Productivity: Reduced context switching with all information visible at once
Better Organization: Clear separation of concerns between input, output, and status
Enhanced Readability: Proper formatting and syntax highlighting for code discussions
Real-time Feedback: Immediate visual feedback for all operations
Modern Interface: Familiar UI patterns that reduce cognitive load
Accessibility: Full keyboard navigation without requiring mouse interaction

Integration with Other Modes

TUI Mode works seamlessly with other cecli features:

Agent Mode: Visual feedback for tool calls and autonomous operations
Skills: Clean display of skill outputs and interactions
MCP Servers: Integrated display of MCP tool outputs
Git Operations: Real-time git status updates in the footer

Troubleshooting

Common Issues

TUI not starting: Ensure your terminal supports True Color (24-bit color)
Display issues: Try resizing your terminal window
Performance problems: Reduce terminal refresh rate or disable animations
Input lag: Check for conflicts with terminal multiplexers (tmux, screen)

Terminal Requirements

True Color Support: Required for proper color rendering
Minimum Size: 80x24 terminal size recommended
Unicode Support: Required for proper symbol display
Modern Terminal: Recommended: Kitty, WezTerm, iTerm2, or Windows Terminal

Last updated:

TUI