# Chabeau > OpenAI-API compatible terminal chatbot and MCP client in Rust - **Type:** MCP server - **Install:** `agentstack add mcp-permacommons-chabeau` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [permacommons](https://agentstack.voostack.com/s/permacommons) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** CC0-1.0 - **Upstream author:** [permacommons](https://github.com/permacommons) - **Source:** https://github.com/permacommons/chabeau ## Install ```sh agentstack add mcp-permacommons-chabeau ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](https://permacommons.org/videos/chabeau-0.7.0/retry.mp4) - [Presets](https://permacommons.org/videos/chabeau-0.7.0/preset-short.mp4) - [Themes](https://permacommons.org/videos/chabeau-0.7.0/themes.mp4) - [User message editing](https://permacommons.org/videos/chabeau-0.7.0/user-edit.mp4) - [Assistant response editing](https://permacommons.org/videos/chabeau-0.7.0/assistant-edit.mp4) - [Character cards](https://permacommons.org/videos/chabeau-0.7.0/character.mp4) - [In-place refinement](https://permacommons.org/videos/chabeau-0.7.0/refine.mp4) - [Syntax highlighting](https://permacommons.org/videos/chabeau-0.7.0/syntax.mp4) - [Code block selection](https://permacommons.org/videos/chabeau-0.7.0/codeblock.mp4) - [Complex tables](https://permacommons.org/videos/chabeau-0.7.0/table.mp4) - [MCP tool calls](https://permacommons.org/videos/chabeau-0.7.2/mcp.mp4) - [Inspecting MCP requests](https://permacommons.org/videos/chabeau-0.7.2/mcp-inspector.mp4) The MCP server shown in the videos above is "[MCP Research Friend](https://github.com/permacommons/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 ```bash cargo install chabeau ``` Versioned release binaries (tagged semver releases) are published on the [GitHub Releases page](https://github.com/permacommons/chabeau/releases) 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: ```bash 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: ```bash # 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 ```bash chabeau provider list chabeau provider add ``` ### Launch ```bash 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 ```bash 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: ```bash 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: ```bash 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`. ```bash 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: ```bash 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. ```bash 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: ```bash 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 ```bash 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 ```bash 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: ```bash 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](https://github.com/permacommons) - **Source:** [permacommons/chabeau](https://github.com/permacommons/chabeau) - **License:** CC0-1.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-permacommons-chabeau - Seller: https://agentstack.voostack.com/s/permacommons - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.