@tryhamster/gerbil 1.0.0-rc.0

package/docs/repl.md

@@ -0,0 +1,473 @@
+# Gerbil REPL
+
+The Gerbil REPL is an interactive terminal interface that brings all of Gerbil's capabilities into a visual, navigable dashboard. Built with [Ink](https://github.com/vadimdemedes/ink) (React for CLIs), it provides a modern TUI experience.
+
+## Launch
+
+```bash
+npx @tryhamster/gerbil repl
+# or simply
+gerbil  # After global install
+```
+
+## Updates
+
+Gerbil checks for updates on startup but **never installs without your permission**.
+
+### In REPL
+
+When an update is available, you'll see a prompt in the header:
+
+```
+gerbil 1.0.0 / Chat  |  Update v1.0.1 → Press u to update
+```
+
+Press **`u`** to install the update. You'll see:
+
+```
+⬇ Updating...
+✅ Updated! Restart to use v1.0.1
+```
+
+### Via CLI Command
+
+```bash
+gerbil update
+```
+
+Output:
+```
+✔ Checking for updates...
+ℹ Update available: v1.0.0 → v1.0.1
+⠋ Installing v1.0.1...
+✔ ✅ Updated to v1.0.1
+
+  Restart your terminal or run 'gerbil' to use the new version.
+```
+
+### After Any Command
+
+After running any `gerbil` command, you'll see a notification if an update is available:
+
+```bash
+$ gerbil commit
+✔ Generated commit message
+
+💡 Update available: v1.0.0 → v1.0.1
+   Run 'gerbil update' to install
+```
+
+## Main Menu
+
+On launch, you'll see a dashboard with 8 feature cards in a 4×2 grid:
+
+```
+                    GERBIL
+        Local LLM inference for Node.js
+             by tryhamster.com
+
+    [AI-generated welcome message appears here]
+
+            model: qwen3-0.6b
+
+┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+│ [1] Chat    │ │ [2] Skills  │ │ [3] Tools   │ │ [4] Model   │
+│ Talk with   │ │ Run AI      │ │ Manage      │ │ Change      │
+│ Gerbil      │ │ skills      │ │ tools       │ │ model       │
+└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
+┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+│ [5]Integrate│ │ [6]Benchmark│ │ [7] Info    │ │ [8] Serve   │
+│ Framework   │ │ Speed       │ │ System      │ │ Start       │
+│ setup       │ │ tests       │ │ info        │ │ server      │
+└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
+
+    arrows | enter | 1-8 | d docs | g github | q quit
+```
+
+### Navigation
+- **Arrow keys** — Navigate the menu grid (up/down/left/right)
+- **Enter** or **1-8** — Select a feature
+- **t** — Toggle thinking mode (menu) or **⌘T** (anywhere)
+- **a** — Toggle agent mode (menu) or **⌘A** (anywhere)
+- **d** — Open documentation (tryhamster.com docs)
+- **g** — Open GitHub repository
+- **h** — Open tryhamster.com
+- **q** — Quit
+- **Ctrl+C** — Press twice to quit (safety confirmation)
+
+---
+
+## Features
+
+### [1] Chat
+
+Interactive conversation with your local LLM.
+
+**Chat Modes** (press `Tab` to switch):
+
+| Mode | Symbol | Description |
+|------|--------|-------------|
+| Assistant | `>` | Helpful and concise general assistant |
+| Coder | `$` | Code-focused, minimal explanations |
+| Teacher | `?` | Patient explanations with examples |
+| Creative | `*` | Expressive and imaginative |
+| Minimal | `.` | Ultra-short responses |
+
+**Agent Mode** (press `⌘A` to toggle):
+- When enabled, Gerbil can call tools like `gerbil_docs` and `run_skill`
+- Works with any chat mode (e.g., Coder + Agent)
+- Shows `+tools` badge when active
+- Tool calls display in cyan boxes with connected result boxes
+
+**Thinking Mode** (press `⌘T` to toggle):
+- When enabled, shows the model's chain-of-thought reasoning
+- Only available with Qwen3 models
+
+**Context Tracking:**
+- Shows tokens used vs. available context
+- Warning when context is >80% full
+- Color-coded: green (<50%), yellow (50-80%), red (>80%)
+
+**Commands:**
+
+| Command | Description |
+|---------|-------------|
+| `/new` or `/clear` | Start a new conversation |
+| `/docs <topic>` | Search Gerbil documentation |
+| `/summarize` or `/compress` | Summarize and compress context |
+| `/mode` | Open mode selector |
+| `/help` | Show all commands |
+
+**Shortcuts:**
+
+| Key | Action |
+|-----|--------|
+| `⌘C` | Copy entire chat to clipboard |
+| `⌘S` | Save chat to markdown file |
+| `⌘T` | Toggle thinking mode |
+| `⌘A` | Toggle agent mode |
+| `Tab` | Open mode selector |
+
+---
+
+### [2] Skills
+
+Run built-in AI skills or create custom ones.
+
+**Built-in Skills:**
+- `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
+
+**Usage:**
+1. Select a skill from the list
+2. Enter input (JSON or plain text)
+3. View the result
+
+**Controls:**
+- **Up/Down** — Navigate skill list
+- **Enter** — Select skill to run
+- **c** — Create a new skill (opens wizard)
+- **Esc** — Back to menu
+
+The first option is **"+ Create new skill"** which opens the skill creation wizard.
+
+---
+
+### [3] Tools
+
+View and manage tools that the agent can use.
+
+**Interface:**
+```
+📦 TOOLS
+Browse and manage available tools
+
+ ▸ gerbil_docs           [builtin]
+   run_skill             [builtin]
+   generate_joke         [project]
+
+Press c to create | x to execute | Esc back
+```
+
+**Tool Sources:**
+- `[builtin]` — Built-in tools like `gerbil_docs`, `run_skill`
+- `[project]` — Custom tools from `.gerbil/tools/`
+- `[error]` — Tools that failed to load (shows error message)
+
+**Controls:**
+- **Up/Down** — Navigate tool list
+- **Enter** — Expand tool details
+- **x** — Execute selected tool
+- **c** — Create a new tool (opens wizard)
+- **o** — Open project tool file in VS Code
+- **Esc** — Back to menu
+
+**Tool Details (when expanded):**
+```
+▾ gerbil_docs           [builtin]
+  Search Gerbil documentation
+  Parameters: query (string)
+```
+
+---
+
+### Create Tool Wizard
+
+A guided 4-step wizard to create custom tools:
+
+```
+[✓] Name --- [✓] Description --- [>] Parameters --- [ ] Logic
+
+┌─────────────────────────────────┐
+│ Name: get_weather               │
+│ Description: Gets weather       │
+│ Parameters: city as string      │
+│ Logic: ...                      │
+└─────────────────────────────────┘
+
+Parameters
+What inputs does this tool need? (press Enter to skip)
+
+> city as a string (required)
+```
+
+**Steps:**
+1. **Name** — Tool identifier (snake_case, e.g., `get_weather`)
+2. **Description** — What the tool does (one sentence)
+3. **Parameters** — What inputs it needs (optional, press Enter to skip)
+4. **Logic** — What it should return
+
+After completion, Gerbil generates a tool file and saves it to `.gerbil/tools/your_tool.tool.ts`.
+
+**Generated Tool Format:**
+```typescript
+// Gerbil Tool: my_tool
+// No imports needed - just export a config object
+
+export default {
+  name: "my_tool",
+  description: "Does something useful",
+  execute: async (params, ctx) => {
+    const value = params?.input || "default";
+    // ctx.generate() available for LLM calls!
+    return `Result: ${value}`;
+  },
+};
+```
+
+---
+
+### [4] Model
+
+Switch between models or download new ones.
+
+**Tabs:**
+- **[Recommended]** — Tested models with known performance
+- **[HuggingFace]** — Search any compatible model
+
+**Model List:**
+```
+● Qwen3 0.6B     ~400MB   fastest [current]
+● Qwen2.5 0.5B   ~350MB   fast
+○ SmolLM2 360M   ~250MB   fastest
+○ Phi-3 Mini     ~2.1GB   medium
+```
+
+- `●` Green dot = cached locally
+- `○` Gray dot = not downloaded
+
+**Controls:**
+- **Up/Down** — Select model
+- **Enter** — Download (if needed) + switch to model
+- **d** — Download only (pre-cache without switching)
+- **Tab** — Switch between Recommended/HuggingFace tabs
+
+---
+
+### [5] Integrate
+
+Framework integration code examples for:
+
+- **AI SDK (Vercel)** — `gerbil/ai`
+- **Next.js** — `gerbil/next`
+- **Express** — `gerbil/express`
+- **React Hooks** — `gerbil/react`
+- **Hono** — `gerbil/hono`
+- **LangChain** — `gerbil/langchain`
+
+Navigate with Up/Down to see code snippets for each framework.
+
+---
+
+### [6] Benchmark
+
+Performance testing with multiple runs and averages.
+
+```
+Benchmark: qwen3-0.6b
+Run multiple times for accurate averages
+
+Results (3 runs):
+Run 1: 45 tok/s, 234ms first token, 52 tokens
+Run 2: 47 tok/s, 198ms first token, 48 tokens
+Run 3: 46 tok/s, 212ms first token, 51 tokens
+
+┌─────────────────────────────┐
+│ Averages:                   │
+│   Tokens/sec:  46           │
+│   First token: 215ms        │
+└─────────────────────────────┘
+
+Enter run | c clear | Esc back
+```
+
+**Controls:**
+- **Enter** — Run benchmark
+- **c** — Clear results
+- **Esc** — Back to menu
+
+Results persist across runs for accurate averaging.
+
+---
+
+### [7] Info
+
+System and session information.
+
+**Tabs:**
+- **[Info]** — Model details, device info, memory usage
+- **[Stats]** — Session statistics (prompts, tokens, time)
+- **[Cache]** — Cached models and storage location
+
+Each tab includes an AI-generated observation about the current data.
+
+**Info Tab:**
+```
+GERBIL v0.1.0
+
+LOADED MODEL
+  Name:     qwen3-0.6b
+  Size:     400MB
+  Context:  32,768 tokens
+  Thinking: supported
+
+DEVICE
+  Device:   Apple Silicon (Metal)
+  Runtime:  Node.js v20.10.0
+
+MEMORY (Unified)
+  Total:     16GB
+  Used:      8.2GB (51%)
+  Available: 7.8GB
+```
+
+---
+
+### [8] Serve
+
+Start HTTP or MCP servers.
+
+**Server Types:**
+- **HTTP Server** — REST API for Gerbil
+- **MCP Server** — For Claude Desktop, Cursor, etc.
+
+**HTTP Server:**
+```
+Model: qwen3-0.6b
+Port: 3000
+
+Endpoints:
+  POST /generate - Generate text
+  GET  /info     - Server info
+
+[running] http://localhost:3000
+PID: 12345
+
+Enter or s to stop | Esc back
+```
+
+**Controls:**
+- **Tab** — Switch between HTTP/MCP
+- **Enter** — Start server (or stop if running)
+- **s** — Stop running server
+- **Esc** — Back (server keeps running in background)
+
+---
+
+## Global Controls
+
+These work from any view:
+
+| Key | Action |
+|-----|--------|
+| `Esc` | Go back to menu |
+| `⌘T` | Toggle thinking mode |
+| `⌘A` | Toggle agent mode |
+| `Ctrl+C` | Quit (press twice) |
+| `q` | Quit (from menu only) |
+
+---
+
+## AI-Generated Messages
+
+The REPL uses Gerbil itself to generate contextual messages:
+
+1. **Welcome Message** — Generated on startup, introduces capabilities
+2. **View Tips** — Generated when entering each view, explains what to do
+
+These messages are 1-2 sentences, helpful, and specific to the context.
+
+---
+
+## Technical Details
+
+- **Built with:** [Ink](https://github.com/vadimdemedes/ink) (React for CLIs)
+- **Components:** Custom React components for each view
+- **State:** React hooks for local state management
+- **Model:** Shared Gerbil instance across all views
+- **Streaming:** Real-time token streaming in chat
+
+---
+
+## Example Session
+
+```bash
+$ npx @tryhamster/gerbil repl
+
+# Gerbil loads, shows welcome message
+# Press 1 or navigate to Chat
+
+[gerbil / Chat]
+Context: 0 / 32,768 tokens (0%)
+[>] Assistant +tools  |  tab mode  |  ⌘Think  |  ⌘Agent  |  /help
+
+> How do I create a tool?
+
+🔧 tool(gerbil_docs)
+   query: "tools"
+
+📄 Documentation
+   Tools are functions the agent can call...
+
+> Based on the docs, you can create tools using...
+
+> /docs skills
+📄 docs(skills):
+Skills are reusable AI tasks with Zod-validated...
+
+> ⌘S
+# Saves to gerbil-chat-2024-01-15T10-30-00.md
+
+> Esc
+# Back to menu
+
+# Press 3 for Tools view
+# Press c to create a new tool
+# Follow the wizard to create your tool
+```