ripl

A shell-based agent chat client and TUI framework.

ripl provides a full-featured ratatui event loop wired to any LLM provider — Anthropic, OpenAI, Ollama, OpenRouter — with Fish Audio TTS/STT, ambient audio, hue-shifting themes, and a session cache. It ships as both a standalone binary (ripl) and a library for building your own AI shell experiences on top of it.

Audio features require platform tools: afplay/afinfo on macOS, or paplay/aplay/mpv/ffplay on Linux. TTS uses say (macOS) or espeak/espeak-ng (Linux). STT recording uses sox.

Install

cargo install ripl-tui

Requires a provider API key in your environment or ~/.ripl/config.toml.

Configure

ripl config          # open ~/.ripl/config.toml in $EDITOR
ripl pair anthropic
ripl pair openai
ripl pair openrouter

# ~/.ripl/config.toml
[provider]
name = "anthropic"
model = "claude-sonnet-4-5"

[speech]
tts = "fish"    # or "say"
stt = "fish"    # or "whisper"

[theme]
root_hue = 217

Environment variables

ripl reads these from your shell — no config file needed to get started.

Variable	Purpose
`ANTHROPIC_API_KEY`	Anthropic / Claude provider key
`OPENAI_API_KEY`	OpenAI provider key
`OPENROUTER_API_KEY`	OpenRouter provider key
`FISH_AUDIO_API_KEY`	Fish Audio TTS/STT key (alias: `FISH_API_KEY`)
`FISH_AUDIO_VOICE_ID`	Fish Audio voice ID (alias: `FISH_VOICE_ID`)
`FISH_AUDIO_MODEL`	Fish TTS model override (alias: `FISH_TTS_MODEL`)
`FISH_STT_LANG`	Fish STT language code (e.g. `en`)
`RIPL_ROOT_HUE`	Theme hue 0–360 (overrides config)
`RIPL_DEV`	Enable dev mode (any value)
`RIPL_WHISPER_CMD`	Path to `whisper` binary
`RIPL_WHISPER_MODEL`	Path to Whisper model file
`RIPL_WHISPER_LANG`	Whisper language code
`RIPL_STT_RECORDER`	Audio recorder command (default: `sox`)
`RIPL_TTS_CACHE_DIR`	TTS audio cache directory
`BUN_PATH`	Path to `bun` for ambient scripts

Use as a library

# Cargo.toml
[dependencies]
ripl-tui = "0.3"

use std::sync::Arc;
use ripl::{RunOptions, with_terminal, run_in_terminal}; // "terminal" is the ratatui type
use ripl::providers::Provider;

fn main() -> color_eyre::eyre::Result<()> {
    let provider: Arc<dyn Provider> = // your provider
    with_terminal(|terminal| {
        run_in_terminal(terminal, RunOptions {
            provider: Some(provider),
            label: Some("My App".to_string()),
            scaffold: false,
            ..Default::default()
        })
    })
}

Built with ripl

clea — Chief Priestess of Ouracle

License

MIT