Chabeau

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](#features)
• [Getting Started](#getting-started)
• [Install](#install)
• [Authenticate](#authenticate)
• [Launch](#launch)
• [Working with Providers and Models](#working-with-providers-and-models)
• [Configuration](#configuration)
• [MCP Servers](#mcp-servers)
• [Character Cards](#character-cards)
• [Personas](#personas)
• [Presets](#presets)
• [Appearance and Rendering](#appearance-and-rendering)
• [Keyboard and Workflow Tips](#keyboard-and-workflow-tips)
• [Architecture Overview](#architecture-overview)
• [Development](#development)
• [License](#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
• MCP tool calls
• Inspecting MCP requests

The MCP server shown in the videos above is "MCP Research Friend", a Permacommons project.

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
• 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](WISHLIST.md).

Getting Started

Install

cargo install chabeau

Versioned release binaries (tagged semver releases) are published on the GitHub Releases page after the release tag becomes reachable from main (for example, when a release/* branch carrying the tag is merged).

Nightly pre-release binaries are also published under the Nightly pre-release tag.

Each nightly artifact includes per-file SHA-256 checksums plus a combined SHA256SUMS file. Nightly releases also include SHA256SUMS.sig and SHA256SUMS.pem, produced by keyless Sigstore signing in GitHub Actions.

On macOS, unsigned nightly binaries may be quarantined by Gatekeeper. If you trust the downloaded artifact, you can remove the quarantine attribute:

xattr -d com.apple.quarantine ./chabeau

Run unsigned binaries at your own risk.

Stable release artifacts are signed by .github/workflows/publish.yml. Nightly checksum manifests are signed by .github/workflows/nightly.yml. You can verify them with:

# Stable release checksums
cosign verify-blob \
  --signature SHA256SUMS.sig \
  --certificate SHA256SUMS.pem \
  --certificate-identity-regexp 'https://github.com/permacommons/chabeau/\.github/workflows/publish\.yml@refs/heads/main' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS

# Nightly checksums
cosign verify-blob \
  --signature SHA256SUMS.sig \
  --certificate SHA256SUMS.pem \
  --certificate-identity-regexp 'https://github.com/permacommons/chabeau/\.github/workflows/nightly\.yml@refs/heads/main' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS

sha256sum -c SHA256SUMS

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 
chabeau provider remove   # 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](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 , chabeau mcp edit -a, and chabeau mcp remove .
• chabeau mcp add and chabeau mcp edit run in basic mode by default and prompt only for required settings; use -a/--advanced to configure optional fields.
• HTTP servers can use bearer tokens with chabeau mcp token list [server-id], chabeau mcp token add , and chabeau mcp token remove .
• Advanced MCP HTTP configs support custom request headers via headers = { KEY = "VALUE" } in [[mcp_servers]].
• Streamable HTTP transport reuses pooled HTTP connections across MCP initialize/list/tool calls for lower request overhead.
• 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 , and chabeau mcp oauth remove directly. Use chabeau mcp oauth add -a to provide an OAuth client id manually.
• For OAuth-backed MCP HTTP servers, Chabeau automatically refreshes expiring access tokens when a refresh token is available; if refresh fails, re-run chabeau mcp oauth add .
• Stdio servers run a local command with optional args and env.
• In the TUI, /mcp lists servers and /mcp shows server info, including whether cached MCP tool schemas have client-side validation available. Toggle with /mcp on|off (or chabeau set mcp on|off). To also clear session runtime MCP state, use /mcp forget instead.
• If a tool requires approval, Chabeau prompts you; use /yolo on|off (or chabeau set mcp 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 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 configuration directory (including cards), set the CHABEAU_CONFIG_DIR environment variable before launching Chabeau.

Example cards live in [examples/hypatia.json](examples/hypatia.json) and [examples/darwin.json](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, scenar

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: permacommons
• Source: permacommons/chabeau
• License: CC0-1.0

Install and usage instructions live in the source repository linked above.