REPL

The REPL is an interactive terminal dashboard for Gerbil. Chat with a model, run skills, and benchmark performance, all without leaving your command line.

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.5-0.8b · thinking: off · agent: on · voice: on · tts: kani-tts-2 · stt: moonshine

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.5 0.8B    ~404MB   fastest [current]
● LFM2.5 350M     ~199MB   fastest
○ Qwen3.5 2B      ~1.1GB   medium
○ Gemma 4 E2B     ~2.5GB   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.5-0.8b

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: kani-tts-2 · loaded · webgpu
🎤 STT: moonshine · 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