verysmolcode 0.14.0

A lightweight TUI coding assistant using Gemini API free tier

VerySmolCode

A lightweight TUI coding assistant powered by Gemini API free tier, designed for resource-constrained devices like Raspberry Pi 3.

Features

• CLI Prompt Mode: vsc -p "prompt" for single-shot usage (like claude -p), supports piped input
• Command Autocomplete: Type / to see all available commands with descriptions, navigate with arrow keys
• Smart Model Routing: 6 models across Gemini 3.x and 2.5 — automatically selects the best available model based on task complexity, with graceful fallback when rate-limited or overloaded
• Planning Mode: /plan for thorough analysis — reads code, creates architecture plans, and builds a todo list to guide implementation
• Task Tracking: Built-in todo list (like Claude Code) — the agent creates and tracks tasks during complex work, visible with /todo
• Full Tool Suite: File read/write/edit, grep search, find files, git operations, shell commands, web fetch, image reading (19 tools)
• MCP Support: Connect to MCP servers (context7, playwright, etc.) via /mcp-add — tools are live in the agent loop
• Code Reviewer: After tool use, reviews actual git diff with a structured checklist (correctness, bugs, completeness, style)
• Chain-of-Thought: All 6 models use thinking tokens for better reasoning, with tier-scaled budgets (Pro 2048, Flash 1024, Lite 512)
• Token-Aware: /tokens dashboard, /fast//smart model selection, rate limit warnings, conversation compaction, and thinking budget control
• Tool Timing: Each tool call shows execution time — helps identify bottlenecks on slow hardware
• Safe by Default: Blocks destructive operations, validates paths, and prevents dangerous commands
• Loop Mode: /loop <prompt> runs a prompt repeatedly — immediately after each completion (Ralph-style) or on a timed interval (e.g. 5m, 30s). Great for iterative refinement and monitoring tasks
• Telegram Integration: Connect a Telegram bot to receive agent messages on your phone, and send prompts back from Telegram
• Lightweight: ~5MB binary, minimal memory footprint, runs on Raspberry Pi 3

Installation

With pip (Python)

Pre-built wheels available for Linux (x86_64, aarch64, armv7), macOS (Intel + Apple Silicon), and Windows (x86_64):

pip install verysmolcode

From Source (Rust)

# Install Rust if needed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/marcelotournier/verysmolcode.git
cd verysmolcode
cargo install --path .

From Source (Python wheel)

pip install maturin
git clone https://github.com/marcelotournier/verysmolcode.git
cd verysmolcode
maturin develop --features python

Usage

# Set your Gemini API key (get one free at https://aistudio.google.com/apikey)
export GEMINI_API_KEY=your_key_here

# Run interactive TUI
vsc

# Run a single prompt (like claude -p)
vsc -p "explain this codebase"

# Pipe input as prompt
cat error.log | vsc -p "what's wrong here?"

# Show version
vsc -v

Commands

Command	Description
/help	Show available commands and keybindings
/fast	Use Flash models for next message (saves budget)
/smart	Use Pro models for next message (best quality)
/plan	Toggle planning mode (read-only, Pro model)
/undo	Undo the last batch of file changes
/save	Save conversation to file: /save [filename]
/tokens	Show detailed token usage and rate limits
/status	Show rate limits and token usage
/model	Show available models and rate limits
/config	Show current configuration
/config set	Edit config: /config set temperature 0.5
/compact	Manually compact conversation to save tokens
/mcp	List configured MCP servers
/mcp-add	Add MCP server: /mcp-add name command [args]
/mcp-rm	Remove MCP server: /mcp-rm name
/todo	Show current task list (alias: /t)
/retry	Retry the last message (alias: /r)
/loop	Loop a prompt: /loop [5m] [--max N] <prompt>
/loop-cancel	Cancel the active loop
/telegram	Telegram bot setup: /telegram setup <token> <id>
/telegram-test	Send a test Telegram message
/telegram-off	Disable Telegram integration
/version	Show version information
/clear	Clear conversation and screen
/quit	Exit VerySmolCode

Keybindings

Key	Action
Ctrl+C	Cancel/Quit
Ctrl+D	Quit (empty input)
Ctrl+L	Clear screen
Up/Down	Input history / Navigate command popup
PgUp/PgDn	Scroll output
Tab	Select from command popup
Esc	Dismiss command popup
Ctrl+A/E	Home/End of line
Ctrl+U/K	Clear line before/after cursor
Ctrl+W	Delete word backward

Model Tiers (Free Tier)

Model	RPM	RPD	Best For
Gemini 3.1 Pro	5	25	Complex tasks
Gemini 3 Flash	10	250	General coding
Gemini 3.1 Flash-Lite	15	1000	Simple tasks
Gemini 2.5 Pro	5	25	Fallback complex
Gemini 2.5 Flash	10	250	Fallback general
Gemini 2.5 Flash-Lite	15	1000	Fallback simple

VerySmolCode automatically manages rate limits across all 6 models independently. When one model is exhausted, it falls back to the next available one. Gemini 3 models are preferred; 2.5 models serve as fallbacks, effectively doubling your daily quota per tier.

Configuration

Config file is stored at ~/.config/verysmolcode/config.json. You can edit it directly or use /config set in the TUI:

/config set temperature 0.5     # Lower = more focused, higher = more creative
/config set max_tokens 2048     # Limit response length to save tokens
/config set compact_threshold 16000  # Compact conversation earlier
/config set safety off          # Disable safety checks (not recommended)

Default values:

{
  "max_tokens_per_response": 4096,
  "max_conversation_tokens": 32000,
  "temperature": 0.7,
  "auto_compact_threshold": 24000,
  "safety_enabled": true
}

Loop Mode

Loop mode runs a prompt repeatedly — useful for iterative refinement (Ralph-style) or timed monitoring tasks:

# Run immediately after each completion (Ralph-style refinement)
/loop check for build errors and fix them

# Run every 5 minutes (timed polling)
/loop 5m run the test suite and report results

# Max 3 iterations then auto-stop
/loop --max 3 optimize the code further

# Combined: every 10 minutes, max 5 times
/loop 10m --max 5 check if CI is green

# Cancel the active loop
/loop off
# or
/loop-cancel

# Show loop status
/loop

The loop status is also broadcast to Telegram if configured.

Telegram Integration

Connect a Telegram bot to receive agent messages on your phone:

# 1. Chat with @BotFather on Telegram to get a bot token
# 2. Send a message to your bot, then get your chat_id:
#    https://api.telegram.org/bot<TOKEN>/getUpdates
# 3. Setup in vsc:
/telegram setup <bot_token> <chat_id>

# Send a test message
/telegram-test

# Disable
/telegram-off

Once configured, the agent's responses, tool calls, and warnings are forwarded to Telegram. You can also send messages from Telegram and they'll reach the agent.

Architecture

src/
  main.rs           - Entry point
  config.rs         - Configuration management
  utils.rs          - Shared utilities (safe UTF-8 truncation)
  api/
    client.rs       - Gemini REST API client with fallback
    models.rs       - 6 model definitions, rate limiting, routing
    types.rs        - Request/response type definitions
  agent/
    loop_runner.rs  - Main agent loop with planning mode and critic
  tools/
    file_ops.rs     - File read/write/edit/list + image reading
    grep.rs         - Search and find files
    git.rs          - Git operations and shell commands
    web.rs          - Web page fetching
    todo.rs         - Task tracking (agent todo list)
    registry.rs     - Tool registration and dispatch (19 tools)
  mcp/
    client.rs       - MCP client (stdio JSON-RPC 2.0)
    config.rs       - MCP server configuration
    types.rs        - MCP protocol types
  tui/
    app.rs          - Application state and event handling
    ui.rs           - Terminal UI rendering
    input.rs        - Keyboard input handling
    commands.rs     - Slash command processing

Testing

# Unit tests (474+ tests)
cargo test

# Integration test (requires tmux + GEMINI_API_KEY)
./tests/integration_test.sh

License

MIT