Ratatalk 🦀💬

A terminal chat client for Ollama, built with Rust and ratatui.

Features

• 🚀 Fast & Responsive: Non-blocking UI with streamed responses
• 💬 Multi-Session: Manage multiple named chat conversations
• 💾 Persistent: Sessions auto-save across restarts
• ⌨️ Keyboard-Driven: Vim-inspired keybindings
• 🎨 Beautiful TUI: Clean, modern terminal interface
• ⚙️ Configurable: TOML-based configuration

Installation

Prerequisites

• Rust (stable)
• Ollama running locally

Install via crates.io (recommended)

The easiest way to get started is to install Ratatalk as a global CLI tool:

cargo install ratatalk

This downloads the latest version from crates.io and installs it to your ~/.cargo/bin directory. After installation, ratatalk will be available in your PATH, so you can run it from any directory:

ratatalk

Screenshot from the app:

Run from source (for development)

If you want to hack on Ratatalk or try the latest features from the repository:

git clone https://github.com/mohammad-albarham/ratatalk.git
cd ratatalk

Then run it in development mode:

cargo run

Or with optimizations (recommended for better performance):

cargo run --release

Optional: Handy shell alias

If you frequently run from source, you can add a shell alias to ~/.bashrc or ~/.zshrc:

alias rt='cargo run --release'

Reload your shell configuration to apply it:

source ~/.zshrc  # or source ~/.bashrc

Now you can simply type rt to run Ratatalk:

rt

Usage

Running Ollama

Ratatalk expects a local Ollama server running on http://127.0.0.1:11434 (the default). Start Ollama in a terminal:

ollama serve

Starting Ratatalk

In another terminal, run Ratatalk:

ratatalk

If you installed via crates.io, just use ratatalk. If you're running from source with the shell alias, use rt.

Keybindings

General

Navigation

Chat

Scrolling

Input Editing

Configuration

Configuration is stored at ~/.config/ratatalk/config.toml:

[server]
host = "http://127.0.0.1:11434"
timeout_secs = 30

[model]
default_model = "llama3.2:latest"
temperature = 0.7
top_k = 40
top_p = 0.9
max_tokens = 0  # 0 = unlimited

[ui]
show_timestamps = true
show_token_count = true
sidebar_width = 30
mouse_support = true
tick_rate_ms = 100

[keybindings]
vim_mode = false

Data Storage

• Config: ~/.config/ratatalk/config.toml
• Sessions: ~/.local/share/ratatalk/sessions.json
• Logs: ~/.config/ratatalk/ratatalk.log

Architecture

src/
├── main.rs           # Entry point, terminal setup, main loop
├── app.rs            # Application state, events, actions
├── config.rs         # Configuration management
├── error.rs          # Error types
├── events.rs         # Input handling, keybindings
├── persistence.rs    # Session save/load
├── ollama/
│   ├── mod.rs        # Module exports
│   ├── client.rs     # HTTP client
│   └── types.rs      # API types
└── ui/
    ├── mod.rs        # UI module, colors, styles
    ├── layout.rs     # Screen layout
    ├── chat.rs       # Chat area rendering
    ├── input.rs      # Input box rendering
    ├── sidebar.rs    # Session/model sidebar
    └── popup.rs      # Modal dialogs

Roadmap

MVP ✅

• Connect to local Ollama
• List available models
• Chat with streaming responses
• Multiple chat sessions
• Persistent config & sessions
• Basic keybindings

Future

• System prompts per session
• Adjustable model parameters per session
• SQLite backend for history
• Export chat to Markdown
• Token/latency statistics
• Vim-style keybindings
• Search within chat
• RAG support with local files
• Image/multimodal support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Acknowledgments

• Ollama for the excellent local LLM server
• ratatui for the amazing TUI framework
• oterm for inspiration