Raindrop Code - AI-Powered Terminal Assistant

Raindrop Code is an AI coding assistant that runs in your terminal. It combines the intelligence of Claude, GPT, or GLM with deep codebase understanding, file operations, git integration, and extensible tools to help you code faster and more effectively.

Key Features

• Deep Code Understanding - Automatically indexes your codebase for intelligent search and context-aware assistance
• Rich Tool Ecosystem - File operations, git, bash, web search, and more - all accessible to the AI
• Smart Agents - Specialized AI agents for code review, summarization, and custom tasks
• Fast & Responsive - Incremental indexing with real-time file watching
• Modern Terminal Interface - Clean UI with syntax highlighting and markdown rendering
• MCP Support - Integrates with Model Context Protocol servers
• Multi-Provider - Works with Anthropic (Claude), OpenAI (GPT), and compatible APIs

Getting Started

First Run Setup

On first run, Raindrop Code will:

1. Ask if you want to create ~/.raindrop-code/ - Global directory with configuration, agents, commands, and skills
2. Display this README automatically to help you get started

The ~/.raindrop-code/ directory is optional but recommended. All custom agents, commands, and prompts are stored centrally in your home directory. You can view this README anytime with /readme.

API Keys

Set at least one API key as an environment variable:

# Anthropic Claude (recommended)
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI GPT
export OPENAI_API_KEY=sk-...

# Optional: Enable web search
export BRAVE_SEARCH_API_KEY=your_brave_api_key

Configuration File

Edit ~/.raindrop-code/config.yaml to customize behavior. See config.example.yaml for a complete example.

# Which provider to use by default
default_provider: liquidmetal

providers:
  # Anthropic (Claude) provider configuration
  anthropic:
    connection:
      # API key options:
      # - env:VAR_NAME: Read from a specific environment variable
      # - "": Use ANTHROPIC_API_KEY environment variable (recommended)
      # - "sk-ant-...": Literal API key (not recommended)
      api_key: env:ANTHROPIC_API_KEY

      # Base URL for the API
      # Note: ANTHROPIC_BASE_URL environment variable always takes precedence
      base_url: "https://api.anthropic.com/v1"

    protocol:
      type: anthropic

    model:
      # Default model to use
      default: claude-sonnet-4-5-20250929
      configs:
        claude-sonnet-4-5-20250929:
          context_window: 200000
          separate_input_output: true  # Anthropic has separate 200k input + 16k output limits

          # Prompt configuration (model-specific)
          # Available types:
          #   - coder           : Default - comprehensive prompt optimized for Claude
          #   - coder-directive : Direct, structured instructions for models needing clarity (Qwen, DeepSeek)
          #   - coder-terse     : Ultra-concise for fast models
          #   - teacher         : Educational mode
          #   - reviewer        : Code review mode
          prompt_type: "coder"

          # Model API parameters
          params:
            max_tokens: 16384
            temperature: 1.0  # Thinking requires a temperature of 1

          # Extra provider-specific parameters (optional)
          extra_params:
            thinking:
              type: "enabled"
              budget_tokens: 8192

          # Prompt caching for Anthropic (reduces costs significantly)
          prompt_caching:
            enabled: true  # Enabled by default - uses multi-tier strategy for optimal caching

  # OpenAI (GPT) provider configuration
  openai:
    connection:
      # Note: OPENAI_API_KEY environment variable always takes precedence
      api_key: env:OPENAI_API_KEY

      # Custom base URL for OpenAI-compatible APIs
      # Note: OPENAI_BASE_URL environment variable always takes precedence
      base_url: "https://api.openai.com/v1"

    protocol:
      type: openai

    model:
      default: gpt-4o-mini
      
      configs:
        gpt-4o-mini:
          context_window: 128000
          prompt_type: "coder-directive"  # Smaller models work better with directive prompts
          params:
            max_tokens: 16384
            temperature: 0.7

  # LiquidMetal.AI provider configuration
  liquidmetal:
    connection:
      api_key: "env:OPENAI_API_KEY"
      base_url: "https://raindrop-code.liquidmetal.run/v1"
    protocol:
      type: "openai"
      version: "v1"
    model:
      default: "GLM-4.6"
      configs:
        GLM-4.6:
          context_window: 200000
          dynamic_context: true
          max_input_tokens: 200000
          max_output_tokens: 128000
          prompt_type: "coder-reasoning"
          params:
            temperature: 1.0
            top_p: 0.95
            top_k: 40
          extra_params:
            tool_choice: auto

Alternative Providers

Raindrop Code supports any OpenAI-compatible API. Here's the complete LiquidMetal.AI configuration from the example:

providers:
  liquidmetal:
    connection:
      api_key: "env:OPENAI_API_KEY"
      base_url: "https://raindrop-code.liquidmetal.run/v1"
    protocol:
      type: "openai"
      version: "v1"
    model:
      default: "GLM-4.6"
      configs:
        GLM-4.6:
          context_window: 200000
          dynamic_context: true
          max_input_tokens: 200000
          max_output_tokens: 128000
          prompt_type: "coder-reasoning"
          params:
            temperature: 1.0
            top_p: 0.95
            top_k: 40
          extra_params:
            tool_choice: auto

# Set this as the default provider
default_provider: liquidmetal

For other OpenAI-compatible APIs, adjust the base_url and model names accordingly.

Usage

Start Raindrop Code in your project directory:

cd my-project
raindrop-code

Then start chatting. Examples:

• "Explain how authentication works in this codebase"
• "Find all TODO comments"
• "Review src/handlers/user.go for potential bugs"
• "Create a new API endpoint for user registration"
• "Write tests for the calculateTotal function"

Git Repository Detection

Raindrop Code automatically detects when you're in a git repository and provides smart directory handling:

• Repository Detection: Automatically detects git repositories and shows you the repository root
• Smart Directory Navigation: If you start in a subdirectory of a git repository, Raindrop Code will ask if you'd like to change to the repository root for better context
• Recommended Practice: Working from the git repository root provides better code context and more accurate search results

Example interaction:

🔍 Git Repository Detection
   Current directory: /Users/ian/my-project/src/components
   Git repository root: /Users/ian/my-project
   You are in subdirectory: src/components

   It's recommended to work from the git repository root for better context.
   Change to git repository root? (Y/n): 

Available Tools

The AI has access to these tools:

| Tool | Description | |------|-------------| | read_file | Read any file in your project | | write_file | Create new files | | edit_file | Make precise edits to existing files | | bash | Execute shell commands (including git) | | search | Intelligent code search with symbol understanding | | explore | Browse directories, see file structure and symbols | | web_search | Search the web (requires BRAVE_SEARCH_API_KEY) | | web_fetch | Fetch content from URLs | | ask_user | Ask clarifying questions | | agent_tool | Spawn specialized sub-agents | | reset | Clear conversation context and optionally run a new prompt |

Slash Commands

| Command | Description | |---------|-------------| | /clear | Clear conversation history | | /context | Toggle context panel (shows indexing status) | | /help | Show available commands | | /reindex | Manually trigger workspace reindexing | | /readme | Display this README | | /mcp | Manage MCP servers |

MCP Servers

Manage Model Context Protocol servers:

raindrop-code mcp list                          # List configured servers
raindrop-code mcp add --name github ...         # Add a server
raindrop-code mcp auth github                   # Authenticate
raindrop-code mcp remove github                 # Remove a server

MCP tools will be automatically available to the AI once configured.

Customization

Custom Commands

Create custom commands in ~/.raindrop-code/commands/:

---
description: Your command description here
---

Your prompt template here. Use {{.Arg}} for arguments.

Example - ~/.raindrop-code/commands/test.md:

---
description: Run tests and fix any failures
---

Please run the test suite and fix any failures you find.

1. Run tests using bash
2. Analyze failures
3. Fix the issues
4. Re-run tests to verify

Use: /test

Agents

Agents are specialized AI assistants with specific tools and expertise.

Built-in: code-reviewer - Reviews code for quality, bugs, security, and best practices.

Example command - ~/.raindrop-code/commands/review.md:

---
description: Review a specific file
---

Use the code-reviewer agent to review the file {{.Arg}}.

Use: /review src/main.go

Creating Custom Agents - ~/.raindrop-code/agents/my-agent.md:

---
name: my-agent
description: What your agent does
tools: [read_file, search, bash]
model: inherit
---

Your agent's system prompt here. Define its personality,
expertise, and instructions.

Tips & Best Practices

Leveraging Code Context

Raindrop Code automatically indexes your codebase:

• Ask "Where is the authentication logic?"
• Request "Find all usages of the User struct"
• Query "Show me files related to payment processing"

Batch Operations

Ask for multiple tasks at once:

• "Create user.go, user_test.go, and add the User model with CRUD operations plus tests"

Interactive Refinement

Raindrop Code can ask clarifying questions:

• "Add a new API endpoint"
• Raindrop Code asks: "REST or GraphQL? What should it do?"

Using Agents for Complex Tasks

For thorough code reviews or analysis:

• "/review src/handlers/payment.go"

Context Management

When conversations get long, Raindrop Code automatically manages context:

• Shows warnings at 80% context usage
• Preserves important information

Manual Reset

You can manually reset the entire conversation at any time:

• "Please reset our conversation and start fresh"
• "reset() - clear everything and let's start over"
• "reset(prompt='Help me understand this new codebase')"

The reset tool completely clears the conversation history and context window, providing a clean slate. You can optionally provide a new prompt to start the fresh conversation immediately.

Web Search

With BRAVE_SEARCH_API_KEY set:

• "Search for the latest best practices for Go error handling"
• "Find the documentation for React hooks"

Project-Specific Setup

All custom agents, commands, and prompts are now stored centrally in your home directory:

~/.raindrop-code/
  agents/
    api-designer.md
    security-auditor.md
  commands/
    deploy.md
    test.md
    review-pr.md
  prompts/
    custom-system-prompt.md

Keyboard Shortcuts & Controls

Raindrop Code provides comprehensive keyboard controls for efficient navigation and operation. The interface adapts based on the current context.

Basic Navigation & Scrolling

| Key | Action | Context | |-----|--------|---------| | ↑ ↓ | Navigate viewport content line by line | All modes | | PgUp PgDown | Page up/down in viewport | All modes | | Home End | Jump to top/bottom of viewport | All modes |

Text Input & Editing

| Key | Action | Notes | |-----|--------|-------| | Enter | Send message | Works for both single and multi-line messages | | Shift+Enter Ctrl+O Alt+Enter | Insert newline in textarea | Continue typing on new line | | Ctrl+V Cmd+V | Paste from clipboard | Supports multiline paste | | Ctrl+C Cmd+C | Copy selection or textarea content | Smart copy based on context | | Ctrl+R | Start reverse search in command history | Search through previous messages | | ESC | Clear selection/dismiss panels/cancel operations | Context-aware behavior |

Special Function Keys

| Key | Action | Description | |-----|--------|-------------| | Ctrl+T | Toggle thinking visibility | Show/hide model reasoning (when available) | | Ctrl+Z | Suspend application | Suspends to background - use fg to resume (Unix-like systems only) | | Ctrl+C (double-tap) | Cancel operation or quit | First tap cancels, second tap quits within 3s | | Ctrl+D (double-tap) | Quit application | Same double-tap behavior as Ctrl+C |

Autocomplete Navigation

| Key | Action | Autocomplete Context | |-----|--------|---------------------| | Tab ↓ | Next suggestion | Cycle through autocomplete options | | Shift+Tab ↑ | Previous suggestion | Cycle backwards | | Enter | Accept suggestion | Complete and add space | | ESC | Cancel autocomplete | Return to normal input | | / | Directory drilling | Special for @ file references - explore subdirectories |

Approval Mode Controls

When AI requests tool execution approval:

| Key | Action | Description | |-----|--------|-------------| | y Y | Approve once | Allow this specific tool execution | | a A | Approve always | Allow this tool for entire session | | n N | Deny | Block this tool execution | | ESC | Cancel operation | Cancel the current request | | ↑ ↓ PgUp PgDown Home End | Scroll | Read tool details before deciding |

Interactive Question Controls

When AI asks clarifying questions:

| Key | Action | Context | |-----|--------|---------| | ↑ ↓ | Navigate options | Move between answer choices | | Tab Shift+Tab | Navigate questions | Move between different questions | | Space | Toggle selection | Select/deselect options (multi-select) | | Enter | Submit answers | Submit all answers when complete | | Backspace | Delete text | Remove characters from "Other" input | | A-Z 0-9 | Type in "Other" | Enter custom text when "Other" option selected |

Search Mode Controls

Reverse search in command history:

| Key | Action | Description | |-----|--------|-------------| | Ctrl+R | Start reverse search | Begin searching through history | | ESC | Exit search | Cancel search and return to normal | | ↑ ↓ | Navigate results | Browse through matching history entries | | Enter | Accept result | Replace current input with selected history |

Text Selection & Vim-style Copy

Mouse and keyboard selection:

| Key | Action | Behavior | |-----|--------|----------| | Mouse drag | Select text | Click and drag to select content | | Double-click | Word selection | Select entire word | | Triple-click | Line selection | Select entire line | | c y | Copy selection (keep) | Vim-style copy, keeps selection active | | C Y | Copy selection (clear) | Vim-style copy, clears selection after copy |

Note: Vim-style copy keys only work when textarea is not focused (text selection automatically blurs the textarea)

Quick Actions Menu (Tab)

The Tab menu provides instant access to common commands and actions:

| Key | Action | Availability | |-----|--------|--------------| | s | Search command history | Always | | + | Expand all subagents | When subagents are active | | - | Collapse all subagents | When subagents are active | | a | Toggle auto-approve mode | Always | | e | Open external editor | Always | | / | Custom commands submenu | Always | | p | Compact conversation | Always | | c | Toggle context panel | Always | | r | Reindex workspace | Always | | x | Clear conversation | Always | | m | MCP servers submenu | Always | | w | Show README documentation | Always | | h | Show help information | Always |

Menu Navigation:

• Movement: ↑ ↓ j k Ctrl+P Ctrl+N
• Select: Enter or Space
• Back: ← or Backspace (from submenus)
• Close: Esc q or Ctrl+G

Context-Aware Behavior

Raindrop Code intelligently adapts controls based on current state:

• ESC has multiple behaviors:

  • Clears active text selection
  • Dismisses context panel if visible
  • Cancels current operation (approval, question, etc.)
  • Exits search mode

• Ctrl+C behavior varies:

  • With text selection: copies selection
  • During operations: cancels current task
  • Double-tap: quits application

Pro Tips

1. Quick Menu Access: Press Tab for instant access to all commands, including history search (s) and subagent expansion (+/-).

2. Quick History Navigation: Use ↑ ↓ in the textarea (first line only) to quickly browse command history, or press Tab then s for full search.

3. Fast File References: Type @ followed by partial path, then use Tab to autocomplete and / to drill into directories.

4. Multiline Editing: Use Shift+Enter to create properly formatted multiline messages without accidentally sending.

5. Emergency Stop: Double-tap Ctrl+C quickly to interrupt any operation and quit if needed.

6. Application Suspend: Use Ctrl+Z to suspend the application to background on Unix-like systems. This is useful when you need to switch to another task. Resume with fg command in your shell. On Windows, this shows a message indicating the feature is not supported.

7. Context Management: Press Ctrl+T to toggle thinking visibility and see how the AI is reasoning about your request.

8. Smart Scrolling: All scrolling keys work during tool execution and streaming, so you can read long outputs while operations continue.

9. Selection Preservation: When you select text, the textarea automatically loses focus so you can use vim-style copy keys (c, y, C, Y).

Raindrop Code - Your AI coding companion for the terminal.