Claude Code for Rio Terminal (2026)

The Setup

You are running Claude Code in Rio, a hardware-accelerated terminal built with Rust and WebGPU that supports tabs, split panes, and a configurable vi mode. Rio uses TOML configuration and provides built-in multiplexing without needing tmux. Claude Code can configure terminals, but it generates iTerm2 or Alacritty settings instead of Rio’s configuration format.

What Claude Code Gets Wrong By Default

  1. References iTerm2 preferences panes. Claude says “open iTerm2 Preferences > Profiles.” Rio is configured entirely through ~/.config/rio/config.toml — there is no GUI preferences panel.

  2. Suggests tmux for splits and tabs. Claude tells you to install tmux for pane management. Rio has built-in tabs and split panes with keyboard shortcuts — tmux is optional, not required.

  3. Uses Alacritty TOML structure. Claude writes Alacritty-style TOML configuration. While both use TOML, Rio’s configuration keys and structure differ — [fonts] vs [font], [navigation] for tabs, etc.

  4. Ignores Rio’s vi mode and search. Claude suggests installing shell plugins for vi bindings. Rio has a built-in vi mode for scrollback navigation and an inline search feature — no plugins needed.

The CLAUDE.md Configuration

# Rio Terminal Configuration
## Terminal
- Emulator: Rio (GPU-accelerated with WebGPU)
- Config: ~/.config/rio/config.toml
- Features: tabs, splits, vi mode, search
- Rendering: WebGPU (hardware accelerated)
## Rio Rules
- Config: TOML format at ~/.config/rio/config.toml
- Tabs: built-in (no tmux needed for tabs)
- Splits: built-in horizontal/vertical splits
- Vi mode: built-in scrollback navigation
- Fonts: [fonts] section with family and size
- Theme: [colors] section or theme file import
- Navigation: [navigation] for tab bar configuration
## Conventions
- Use Rio's built-in tabs and splits for Claude Code
- Font: monospace at 14px for readability
- Scrollback: set history_size for Claude Code output
- Vi mode for navigating long Claude Code output
- Search: built-in search for finding in scrollback
- Key bindings: [[keyboard]] for custom shortcuts
- Padding: add padding for comfortable reading

Workflow Example

You want to configure Rio optimally for Claude Code development sessions. Prompt Claude Code:

“Configure Rio terminal with JetBrains Mono font at size 14, a Catppuccin Mocha color theme, increased scrollback for long Claude Code output, and key bindings for creating splits and navigating between them.”

Claude Code should create ~/.config/rio/config.toml with [fonts] section for JetBrains Mono, [colors] section with Catppuccin Mocha values, history_size set to 10000 or higher, and [[keyboard]] entries for split creation and navigation shortcuts.

Common Pitfalls

  1. Scrollback too small for Claude Code. Claude uses default scrollback settings. Claude Code can produce very long output. Set history_size = 10000 or higher in the config to ensure you can scroll back through complete outputs.

  2. WebGPU not available on older systems. Claude configures Rio with WebGPU features that may not work. Rio falls back to other renderers if WebGPU is unavailable, but performance may differ. Check rio --version for renderer support.

  3. Font not installed. Claude configures JetBrains Mono without checking installation. Rio shows a fallback font if the configured font is missing. Install the font first or use a font known to be installed on your system.

Find commands → Search all commands in our Command Reference.

Common Questions

How do I get started with claude code for rio terminal?

Begin with the setup instructions in this guide. Install the required dependencies, configure your environment, and test with a small project before scaling to your full codebase.

What are the prerequisites?

You need a working development environment with Node.js or Python installed. Familiarity with the command line and basic Git operations is helpful. No advanced AI knowledge is required.

Can I use this with my existing development workflow?

Yes. These techniques integrate with standard development tools and CI/CD pipelines. Start by adding them to a single project and expand once you have verified the benefits.

Where can I find more advanced techniques?

Explore the related resources below for deeper coverage. The Claude Code documentation and community forums also provide advanced patterns and real-world case studies.