Chabeau - Terminal Chat Interface

Chabeau is a full-screen terminal chat interface that connects to various AI APIs for real-time conversations. Chabeau brings the convenience of modern chat UIs to the terminal with a focus on speed, ergonomics, and sensible defaults. It is not a coding agent, but preliminary support for the Model Context Protocol is in development. This makes it possible to connect Chabeau with various local and remote services as well.

Table of Contents

• Features
• Getting Started
  • Install
  • Authenticate
  • Launch
• Working with Providers and Models
• Configuration
• MCP Servers
• Character Cards
• Personas
• Presets
• Appearance and Rendering
• Keyboard and Workflow Tips
• Architecture Overview
• Development
• License

Features

See it in action

• Message retry
• Presets
• Themes
• User message editing
• Assistant response editing
• Character cards
• In-place refinement
• Syntax highlighting
• Code block selection
• Complex tables

Full feature list

• Full-screen terminal UI with real-time streaming responses
• Markdown rendering in the chat area (headings, lists, quotes, tables, callouts, horizontal rules, superscript/subscript, inline/fenced code) with clickable OSC 8 hyperlinks
• Modal pickers and inspectors temporarily suspend hyperlink rendering to keep the screen clean
• Built-in support for many common providers (OpenAI, OpenRouter, Poe, Anthropic, Venice AI, Groq, Mistral, Cerebras)
• Support for quick custom configuration of new OpenAI-compatible providers
• Interactive dialogs for selecting models and providers
• Character card support (v2 format) with in-app picker and defaults per provider/model
• Persona system for defining reusable user identities with variable substitution support
• Reusable preset instructions with picker and CLI toggles for quick context switching
• Extensible theming system that degrades gracefully to terminals with limited color support
• Secure API key storage in system keyring with config-based provider management
• Multi-line input (IME-friendly) with compose mode that can expand to half the terminal for longer responses
• Message retry and message editing
• On-demand refinements of the last assistant response with /refine <prompt>
• Slash command registry with inline help for faster command discovery
• Conversation logging with pause/resume; quick /dump of contents to a file
• Syntax highlighting for fenced code blocks (Python, Bash, JavaScript, and more)
• Inline block selection (Ctrl+B) to copy or save fenced code blocks
• User message selection (Ctrl+P) to revisit and copy prior prompts
• Assistant message editing (Ctrl+X) to revise or truncate assistant responses without resending, with compose-mode shortcuts available while refining replies
• Prettified API error output with Markdown summaries for easier troubleshooting

For features under consideration, see WISHLIST.md.

Getting Started

Install

cargo install chabeau

Configure Providers

chabeau provider list
chabeau provider add

Launch

chabeau         # Uses defaults; opens pickers when needed

Inside the TUI, use /provider and /model to switch, and /help to see a full breakdown of commands and keyboard shortcuts.

Working with Providers and Models

chabeau                              # Start chat with defaults (pickers on demand)
chabeau --provider openai            # Use specific provider
chabeau --model gpt-5                # Use specific model
chabeau --log conversation.log       # Enable logging immediately on startup

Discover available options:

chabeau -p                           # List providers and auth status
chabeau -m                           # List available models
chabeau -p openrouter -m             # List models for specific provider

Manage providers from the CLI:

chabeau provider list
chabeau provider add                 # Built-in token or custom provider
chabeau provider add poe             # Shortcut for built-in provider token
chabeau provider add my-provider     # Shortcut for custom provider id
chabeau provider edit <provider-id>
chabeau provider remove <provider-id>  # Remove custom provider, or built-in token

Most users only need provider add; it can either attach a token to a built-in provider or create a custom provider and prompt for a token. Use chabeau provider token ... commands later when rotating or removing credentials.

Environment variables are used only if no providers are configured, or when you pass --env.

export OPENAI_API_KEY="your-api-key-here"
export OPENAI_BASE_URL="https://api.openai.com/v1"  # Optional
chabeau --env     # Force using env vars even if providers are configured

Quick, Single-Turn Chats

For quick, one-off questions without launching the full TUI, use the say command:

chabeau say "What is the capital of France?"

This command sends a single-turn message to the configured model, streams the response directly to your terminal, and exits. It respects your markdown settings, emits OSC8 hyperlinks when your terminal supports them, and uses a monochrome theme for clean, readable output.

MCP is disabled in chabeau say mode.

When you omit the prompt argument, chabeau say will read from piped or redirected stdin (trimming trailing whitespace) before showing the usage message, so cat prompt.txt | chabeau say works as expected.

When stdout is redirected to a file or piped into another program, Chabeau automatically falls back to a plain-text streaming mode. This mode skips OSC8 hyperlinks and cursor control so captured output stays free of escape codes.

If you have multiple providers configured but no default set, Chabeau will prompt you to specify a provider with the -p flag. The -p and other global flags can be placed before or after the prompt.

Environment variable values can make their way into shell histories or other places they shouldn't, so using the keyring is generally advisable.

Configuration

Chabeau stores its configuration in config.toml.

• Linux: ~/.config/chabeau/config.toml
• macOS: ~/Library/Application Support/org.permacommons.chabeau/config.toml

Generally, you can rely on the UI: when you use interactive commands like /model, /provider, /theme, or /character, press Alt+Enter (or Ctrl+J) to persist the selection.

chabeau set / chabeau unset

chabeau set handles scalar values and selection defaults — anything that's a single value or a provider/model mapping. Run chabeau set with no arguments to print the current configuration and see which values are explicitly set versus inherited defaults.

chabeau set                                              # Show all settings
chabeau set default-provider openai                      # Provider selection
chabeau set theme dracula                                # Theme selection
chabeau set default-model openai gpt-4o                  # Default model per provider
chabeau set default-character openai gpt-4 hypatia       # Default character per provider/model
chabeau set default-persona anthropic claude-3 developer  # Default persona per provider/model
chabeau set default-preset openai gpt-4o short           # Default preset per provider/model
chabeau set markdown off                                 # Toggle markdown rendering
chabeau set syntax off                                   # Toggle syntax highlighting
chabeau set builtin-presets off                          # Toggle built-in presets
chabeau set refine-prefix "REVISE:"                      # Custom refine trigger
chabeau set refine-instructions "Custom instructions"    # Custom refine system prompt
chabeau set mcp agpedia off                              # Enable/disable an MCP server
chabeau set mcp agpedia yolo on                          # Toggle auto-approve for a server

Every set key has a matching unset to clear the value:

chabeau unset default-provider
chabeau unset default-model openai                       # Provider-keyed: pass the provider
chabeau unset default-character "openai gpt-4"           # Provider/model-keyed: quote both
chabeau unset markdown                                   # Reverts to default (on)
chabeau unset mcp agpedia                                # Reverts to default (on)
chabeau unset mcp "agpedia yolo"                         # Reverts to default (off)

Editing config.toml by hand

The following structured definitions need to be edited in config.toml directly:

• Custom themes — multi-field color/style definitions under [[custom_themes]]
• Personas — id, display name, and bio under [[personas]]
• Presets — id, pre, and post instructions under [[presets]]

You can also edit the following in config.toml, but you don't strictly need to:

• Custom providers — can be configured via chabeau provider subcommands
• MCP servers — can be configured via chabeau mcp subcommands

Copy examples/config.toml.sample to your config directory for a starting point.

Both the CLI and TUI run mutations through the same configuration orchestrator. Chabeau caches the parsed file based on its last-modified timestamp, skipping redundant reloads when nothing has changed, and persists updates atomically so a failed write never clobbers your existing config.toml.

MCP Servers

Chabeau lets you connect MCP servers (HTTP or stdio) and use their tools/resources from the TUI.

• Manage servers from the CLI: chabeau mcp list, chabeau mcp add, chabeau mcp add -a, chabeau mcp edit <server-id>, and chabeau mcp remove <server-id>.
• chabeau mcp add runs in basic mode and prompts only for required settings; use -a/--advanced to configure optional fields during add.
• HTTP servers can use bearer tokens with chabeau mcp token list [server-id], chabeau mcp token add <server-id>, and chabeau mcp token remove <server-id>.
• chabeau mcp add probes OAuth discovery for HTTP/HTTPS servers and starts browser auth when available. You can also run chabeau mcp oauth list [server-id], chabeau mcp oauth add <server-id>, and chabeau mcp oauth remove <server-id> directly. Use chabeau mcp oauth add <server-id> -a to provide an OAuth client id manually.
• Stdio servers run a local command with optional args and env.
• In the TUI, /mcp lists servers and /mcp <server-id> shows server info. Toggle with /mcp <server-id> on|off (or chabeau set mcp <server-id> on|off). To also clear session runtime MCP state, use /mcp <server-id> forget instead.
• If a tool requires approval, Chabeau prompts you; use /yolo <server-id> on|off (or chabeau set mcp <server-id> yolo on|off) for per-server auto-approve.
• --disable-mcp turns MCP off for a session. --debug-mcp writes verbose MCP logs to mcp.log.

Character Cards

Chabeau supports character cards in the v2 format, letting you chat with AI personas that define tone, background, and greeting. Cards can be JSON or PNG files (with embedded metadata).

Import and Manage Cards

chabeau import path/to/character.json       # Import JSON card
chabeau import path/to/character.png        # Import PNG with embedded metadata
chabeau import character.json --force       # Overwrite existing card

Cards are stored in the Chabeau configuration directory. Use chabeau -c to print the directory name and any cards Chabeau discovers.

Use Characters in Chat

chabeau -c hypatia                          # Start with character by name
chabeau -c hypatia.json                     # Start with character by filename

In the TUI, /character opens the character picker (↑↓ to navigate, Ctrl+O to inspect full definitions, Enter to select, Alt+Enter to set as default). You can also run /character <name> for quick switches.

Defaults and Directories

Set defaults for provider/model combinations via Alt+Enter (or Ctrl+J) in the picker, or on the CLI:

chabeau set default-character openai gpt-4 hypatia
chabeau unset default-character openai gpt-4

To use a separate cards directory, set the CHABEAU_CARDS_DIR environment variable before launching Chabeau.

Example cards live in examples/hypatia.json and examples/darwin.json.

Troubleshooting

• "Character not found": ensure the card is in ~/.config/chabeau/cards/ (or its equivalent on macOS or Windows) or provide the full path.
• "Invalid card format": verify the JSON structure matches the v2 spec with required fields (name, description, personality, scenario, first_mes, mes_example).
• "PNG missing metadata": PNG files must contain a chara tEXt chunk with base64-encoded JSON.
• Cards not appearing in picker: check file permissions and ensure files have .json or .png extensions.

Format Reference

Character cards follow the v2 specification.

Personas

Personas allow you to define different user identities for conversations, each with their own name and optional biographical context. Unlike character cards (which define AI personas), personas define who you are in the conversation.

Configure Personas

Add personas to your config.toml:

[[personas]]
id = "developer"
name = "Alex"
bio = "You are talking to Alex, a senior software developer with expertise in Rust and distributed systems."

[[personas]]
id = "student"
name = "Sam"
bio = "Sam is a computer science student learning about AI and machine learning."

[[personas]]
id = "casual"
name = "Jordan"
# bio is optional - persona will just change the display name

Assign defaults per provider/model from the CLI or in config.toml:

chabeau set default-persona openai gpt-4o developer

[default-personas.openai]
"gpt-4o" = "developer"

Use Personas in Chat

chabeau --persona developer                 # Start with a specific persona

In the TUI, /persona opens the persona picker (↑↓ to navigate, Ctrl+O to read the persona text, Enter to select, Alt+Enter to set as default). You can also run /persona <id> for quick switches, or select "[Turn off persona]" to return to anonymous mode.

When a persona is active:

• Your messages are labeled with the persona's name instead of "You"
• The persona's bio (if provided) is prepended to the system prompt

Variable Substitutions

Both personas and character cards support {{user}} and {{char}} variable substitutions:

• {{user}} is replaced with the active persona's display name (or "Anon" if no persona is active)
• {{char}} is replaced with the character's name (or "Assistant" if no character is active)

Persona vs Character Integration

Personas and character cards work together seamlessly:

• Character cards define the AI's personality, background, and behavior
• Personas define your identity and context in the conversation
• Both support {{user}} and {{char}} variable substitutions
• The persona's bio is added to the system prompt before the character's instructions

Presets

Presets let you inject reusable system instructions into the first and last system messages that Chabeau sends to the model. They are ideal for lightweight tone or formatting tweaks that you want to toggle quickly.

Chabeau ships with three built-in presets (short, roleplay, and casual) so you can experiment without editing your config. Set builtin_presets = false in config.toml to hide them from /preset, /preset <id>, and the --preset flag. If you define a preset with the same ID, your version overrides the built-in automatically.

Configure Presets

Add presets to your config.toml:

[[presets]]
id = "focus"
pre = """
You are collaborating with {{user}}. Keep responses focused and direct.
"""
post = """
Before finishing, list any follow-up actions.
"""

[[presets]]
id = "roleplay"
pre = """
- Engage in roleplay with the user.
- Two paragraphs per turn max.
- Don't be shy to perform actions. Format these in italics, like this: *{{char}} frowns at {{user}}.*
- Be creative! Feel free to take the roleplay into new directions.
"""

• pre text is wrapped in blank lines and prepended to the very first system message.
• post text is wrapped in blank lines and appended to the final system message. If no system message exists at either position, Chabeau creates one automatically.
• Presets support the same {{user}} and {{char}} substitutions as personas and character cards.

Assign defaults per provider/model from the CLI or in config.toml:

chabeau set default-preset openai gpt-4o focus

[default-presets.openai]
"gpt-4o" = "focus"

Use Presets in Chat

Launch with an ID like --preset focus, or pick interactively with /preset. Use Ctrl+O in the picker to review the preset instructions. The picker includes a "Turn off preset" option to clear the active preset.

The status bar shows the current preset when one is active so you can confirm the context you're using at a glance.

Appearance and Rendering

Themes

Chabeau ships with built-in themes and supports custom ones. Use /theme in the TUI to preview and Alt+Enter (or Ctrl+J) to persist the choice. On the CLI, run:

chabeau set theme dark   # Set a theme
chabeau themes           # List themes (built-in and custom)
chabeau unset theme      # Revert to default detection

When no explicit theme is set, Chabeau tries to infer a sensible default from your OS preference (e.g., macOS, Windows, GNOME). If no hint is available, it defaults to the dark theme.

Custom themes belong in config.toml under [[custom_themes]]. See src/builtins/themes.toml for color references and examples/config.toml.sample for structure.

Themes can also set a cursor_color to change the terminal cursor via OSC 12 when the theme is applied.

Input uses a steady bar cursor inside the chat box so the insertion point stays easy to see while typing.

App messages—Chabeau’s own informational banners, warnings, and errors—use dedicated theme knobs so they’re easy to distinguish from assistant replies. Customize them with the app_info_*, app_warning_*, and app_error_* keys in your theme to control the prefix text, prefix styling, and message styling independently.

Markdown and Syntax Highlighting

Toggle these features at runtime:

• /markdown on|off|toggle
• /syntax on|off|toggle

Chabeau persists these preferences to the config file automatically. Syntax colors adapt to the active theme and use the theme’s code block background for consistent contrast.

When markdown is enabled, image ALT text is rendered as an OSC hyperlink pointing to the underlying image URL so you can open assets directly from the transcript.

Color Support

Chabeau detects terminal color depth and adapts themes accordingly:

• Truecolor: if COLORTERM contains truecolor or 24bit, Chabeau uses 24-bit RGB.
• 256 colors: if TERM contains 256color, RGB colors are quantized to the xterm-256 palette.
• ANSI 16: otherwise, colors map to the nearest 16 ANSI colors.

Force a mode when needed with CHABEAU_COLOR=truecolor|256|16.

Keyboard and Workflow Tips

Interface Controls

See the built-in help for a full list of keyboard controls. A few highlights:

• Alt+Enter (or Ctrl+J) to start a new line; Enter sends. Arrow keys always act on the focused area.
• Compose mode (F4) flips the newline/send defaults; focus behavior stays the same.
• Home/End and Ctrl+A/Ctrl+E jump to the start or end of the visible line in the focused pane, even when text is soft-wrapped.
• PgUp/PgDn scroll the focused area — the transcript or the multi-line input — by a page at a time.
• Ctrl+N repeats your most recent /refine prompt on the latest assistant reply.
• Tab switches focus between the transcript and input unless the current input starts with /. When it does, Tab autocompletes slash commands. The active region shows a ›; the inactive one shows a ·.
• Ctrl+O opens the inspect view for picker items—providers include their ID, base URL, and auth mode; themes show their ID and every color override; character cards expand to the full v2 definition.
• Ctrl+D on an empty input prints the transcript and exits; Ctrl+C exits immediately.

Mousewheel

Chabeau avoids capturing the mouse so selection operations (copy/paste) work as expected. Some terminals treat mousewheel events as cursor key input, so scrolling moves the conversation. Others reveal terminal history; in that case, use the cursor keys or PgUp/PgDn instead.

External Editor

Set the EDITOR environment variable to compose longer responses in your favorite editor:

export EDITOR=nano          # or vim, code, etc.
export EDITOR="code --wait" # VS Code with wait

Once set, press Ctrl+T in the TUI to launch the external editor.

Architecture Overview

See ARCHITECTURE.md for a high-level walkthrough aligned with the current repository state.

Chabeau uses a modular design with focused components:

• main.rs – Entry point
• api/ – API data structures and model-related helpers
  • mod.rs – API data structures
  • models.rs – Model fetching and sorting functionality
• auth/ – Authentication and provider management
  • mod.rs – Authentication manager implementation
  • ui.rs – Interactive prompts and input helpers for auth flows
• builtins/ – Build-time assets embedded into the binary
  • help.md – In-app keyboard shortcut and command reference
  • models.toml – Supported provider definitions
  • presets.toml – Built-in system instruction presets
  • themes.toml – Built-in UI themes
• character/ – Character card support (v2 format)
  • cache.rs – In-memory caching with invalidation
  • card.rs – Character card data structures and v2 spec parsing
  • import.rs – Import command and validation logic
  • loader.rs – Card file loading (JSON and PNG with metadata extraction)
  • mod.rs – Module exports and public API
  • png_text.rs – PNG tEXt chunk reader/writer
  • service.rs – Shared character cache and resolution helpers for the TUI and CLI
• cli/ – Command-line interface parsing and handling
  • character_list.rs – Character card listing functionality
  • mod.rs – CLI argument parsing and command dispatching
  • model_list.rs – Model listing functionality
  • provider_list.rs – Provider listing functionality
  • settings/ – Trait-based set/unset handler registry
  • theme_list.rs – Theme listing functionality
• commands/ – Chat command processing and registry-driven dispatch
  • mod.rs – Command handlers and dispatcher
  • refine.rs – Message refinement logic
  • registry.rs – Static command metadata registry
• core/ – Core application components
  • app/ – Application state and controllers
    • actions/ – Internal action definitions and dispatcher for chat loop updates
    • app.rs – Main App struct and event loop integration
    • conversation.rs – Conversation controller for chat flow, retries, and streaming helpers
    • mod.rs – App struct and module exports
    • picker/ – Generic picker that powers all TUI selection dialogs
    • pickers.rs – Picker constructors and helpers for each picker type
    • session.rs – Session bootstrap and provider/model state
    • settings.rs – Theme and provider controllers
    • streaming.rs – Handles streaming responses from the API
    • ui_helpers.rs – UI state transition helpers
    • ui_state.rs – UI state management and text input helpers
    • builtin_presets.rs – Built-in preset loader
  • builtin_providers.rs – Built-in provider configuration (loads from builtins/models.toml)
  • chat_stream.rs – Shared streaming service that feeds responses to the app, UI, and loggers
  • config/ – Configuration data, defaults, caching, and persistence
    • data.rs – Configuration data types and pure helpers
    • defaults.rs – Default selection helpers and Config implementations
    • io.rs – Config path resolution and persistence routines
    • mod.rs – Public exports for configuration helpers
    • orchestrator.rs – Cached config loader, mutation orchestrator, and test isolation
    • tests.rs – Configuration module tests
  • keyring.rs – Secure storage for API keys
• message.rs – Message data structures
• mcp/ – Model Context Protocol client integration
  • client.rs – MCP transport and connection handling for HTTP and stdio
  • events.rs – MCP server request envelopes
  • mod.rs – MCP module exports and tool name constants
  • permissions.rs – Per-tool permission decision store
  • registry.rs – Enabled MCP server registry
• mcp_auth.rs – Keyring-backed MCP token storage
• persona.rs – Persona management and variable substitution
  • preset.rs – System instruction preset management
  • text_wrapping.rs – Text wrapping utilities
• ui/ – Terminal interface rendering
  • appearance.rs – Theme and style definitions
  • chat_loop/ – Mode-aware chat loop orchestrating UI flows, keybindings, and command routing
    • event_loop.rs – Async terminal loop orchestration, event polling, and stream dispatch
    • keybindings/ – Mode-aware keybinding registry and handlers
    • lifecycle.rs – Terminal setup/teardown helpers and resource guards
    • modes.rs – Mode-aware key handlers and text interaction utilities
  • help.rs – Help text rendering
  • layout.rs – Shared width-aware layout engine for Markdown and plain text
  • markdown/ – Markdown renderer and wrapping helpers that emit span metadata
  • mod.rs – UI module declarations
  • osc/ – Crossterm backend wrapper that emits OSC 8 hyperlinks
  • picker.rs – Picker controls and rendering
  • renderer.rs – Terminal interface rendering (chat area, input, pickers)
  • span.rs – Span metadata for clickable links
  • theme.rs – Theme loading and management
  • title.rs – Header bar rendering
• utils/ – Utility functions and helpers
  • clipboard.rs – Cross-platform clipboard helper
  • color.rs – Terminal color detection and palette quantization
  • editor.rs – External editor integration
  • logging.rs – Chat logging functionality
  • mod.rs – Utility module declarations
  • scroll.rs – Text wrapping and scroll calculations

Development

Running Tests

cargo test                    # All tests
cargo test scroll::           # Scroll functionality tests
cargo test --release          # Faster execution

Performance

Chabeau includes lightweight performance checks in the unit test suite and supports optional Criterion benches.

• Built-in perf checks (unit tests):
  • Short history prewrap (50 iters, ~60 lines): warns at ≥ 90ms; fails at ≥ 200ms.
  • Large history prewrap (20 iters, ~400 lines): warns at ≥ 400ms; fails at ≥ 1000ms.
  • Run with: cargo test (warnings print to stderr; tests only fail past the fail thresholds).
• Optional benches (release mode) using Criterion 0.7:
  • A render_cache bench validates the cached prewrapped rendering path.
  • Run: cargo bench
  • Reports live in target/criterion/ (HTML under report/index.html).
  • To add new benches, create files under benches/ (e.g., benches/my_bench.rs) and use Criterion’s criterion_group!/criterion_main!.
  • Benches import internal modules via src/lib.rs (e.g., use chabeau::...).

License

CC0 1.0 Universal (Public Domain)