REPL

Interactive terminal dashboard built with Ink. Chat, run skills, benchmark, and more.

gerbil repl

Main Menu

On launch, you'll see a dashboard with 8 feature cards (4×2 grid):

Navigation

• ↑↓←→ — Navigate the menu grid
• Enter or 1-8 — Select a feature
• u — Update Gerbil (when update available)
• d — Open documentation
• g — Open GitHub
• q — Quit

[1] Chat

Interactive conversation with your local LLM. Press Tab to switch between modes:

Chat Features

• ↑↓ — Browse command history
• Tab — Cycle through chat modes
• ⌘C — Copy chat to clipboard
• ⌘S — Save chat to file
• ⌘T — Toggle thinking mode
• ⌘A — Toggle agent mode
• Ctrl+V — Toggle voice mode (speak responses aloud)
• Ctrl+R — Record from microphone (5 seconds)
• Esc — Return to main menu

Responses render markdown with syntax highlighting, lists, and formatting.

Chat Commands

/new          # Start a new conversation
/clear        # Clear chat history
/summarize    # Summarize and compress context
/save [file]  # Save chat to markdown
/mode         # Open mode selector
/docs <topic> # Search Gerbil documentation
/help         # Show all commands

Voice Features

Toggle voice mode with Ctrl+V to have responses spoken aloud. Record from microphone with Ctrl+R for voice input.

# Status bar shows voice mode
model: qwen3-0.6b · thinking: off · agent: on · voice: on · tts: kokoro-82m · stt: whisper-tiny.en

Agent Mode

In Agent mode (@), Gerbil can use tools to accomplish tasks:

• gerbil_docs — Search Gerbil documentation
• run_skill — Execute any registered skill
• Custom tools you define in your config

The agent will automatically decide which tools to call based on your request.

[2] Skills

Run built-in AI skills or create custom ones.

• commit — Generate git commit messages
• summarize — Condense text or documents
• explain — Break down code or concepts
• review — Code review with issue detection
• test — Generate test cases
• translate — Translate text
• extract — Extract structured data
• title — Generate titles

Skills Shortcuts

• c — Create a new skill
• Enter — Run selected skill
• Esc — Back to menu

[3] Tools

Manage tools that the LLM can call in Agent mode. Lists all registered tools (builtin + project).

• [builtin] — Built-in tools like gerbil_docs, run_skill
• [project] — Custom tools from .gerbil/tools/
• [error] — Tools with loading errors

Tools Shortcuts

• x — Execute tool directly
• c — Create a new tool
• o — Open tool file in VS Code
• Enter — Expand tool details
• Esc — Back to menu

[4] Model

Switch between models or download new ones.

● Qwen3 0.6B     ~400MB   fastest [current]
● Qwen2.5 0.5B   ~350MB   fast
○ SmolLM2 360M   ~250MB   fastest
○ Phi-3 Mini     ~2.1GB   medium

● = cached locally
○ = not downloaded

• ↑↓ — Select model
• Enter — Download + switch
• d — Download only (pre-cache)
• Tab — Switch Recommended/HuggingFace

[5] Integrate

Framework integration code examples for AI SDK, Next.js, Express, React, Hono, and LangChain.

[6] Benchmark

Performance testing with multiple runs and averages.

Benchmark: qwen3-0.6b

Results (3 runs):
  Run 1: 45 tok/s, 234ms first token
  Run 2: 47 tok/s, 198ms first token
  Run 3: 46 tok/s, 212ms first token

Averages:
  Tokens/sec:  46
  First token: 215ms

[7] Info

System and session information with three tabs:

• [Info] — Model details, device info, memory usage
• [Stats] — Session statistics (prompts, tokens, time)
• [Cache] — Cached models and storage location

The Info view also shows TTS and STT model status when loaded:

🔊 TTS: kokoro-82m · loaded · webgpu
🎤 STT: whisper-tiny.en · loaded · webgpu

[8] Serve

Start HTTP or MCP servers.

• HTTP Server — REST API for Gerbil
• MCP Server — For Claude Desktop, Cursor, etc.

# HTTP endpoints
POST /generate  - Generate text
GET  /info      - Server info

# Controls
Tab   - Switch HTTP/MCP
Enter - Start/stop server
s     - Stop server
Esc   - Back (server keeps running)

Example Session

$ gerbil repl

# Gerbil loads, shows welcome message
# Press 1 or navigate to Chat

[>] Assistant  |  tab change mode  |  /help

> What is recursion?

Recursion is when a function calls itself to solve 
a problem by breaking it into smaller instances.

> /mode
# Switch to Coder mode

[$] Coder

> fibonacci in python

def fib(n):
    if n <= 1: return n
    return fib(n-1) + fib(n-2)

> /save
# Saves to gerbil-chat-2024-01-15.md

> Esc
# Back to menu

Technical Details

• Built with Ink (React for CLIs)
• Custom React components for each view
• React hooks for state management
• Shared Gerbil instance across views
• Real-time token streaming in chat