@liquidmetal-ai/raindrop-code

v0.0.65

Published

7 days ago

AI-powered terminal coding assistant with deep code understanding, file operations, and extensible tools

Raindrop Code

AI coding assistant that runs in your terminal. It indexes your codebase, operates on files, runs commands, and integrates with git — driven by Claude, GPT, or GLM.

Built by LiquidMetal.AI. Written in Go, distributed as a native binary via npm.

Supported platforms: macOS (Apple Silicon & Intel), Linux (x64, arm64), Windows (x64)

Quick Start

npm install -g @liquidmetal-ai/raindrop-code

Set an API key:

export ANTHROPIC_API_KEY=sk-ant-...

export OPENAI_API_KEY=sk-...

Or log in to raindrop CLI to use LiquidMetal as a provider:

raindrop auth login

Launch in your project directory:

cd my-project
raindrop-code

On first run, Raindrop Code offers to create ~/.raindrop-code/ — a directory for configuration, custom agents, commands, and skills. This is optional but recommended. The built-in README displays automatically; revisit it anytime with /readme.

Providers & API Keys

Raindrop Code supports multiple LLM providers. Set the appropriate environment variable for the provider you want to use.

| Variable | Provider | Required | |----------|----------|----------| | ANTHROPIC_API_KEY | Anthropic (Claude) | For Anthropic provider | | OPENAI_API_KEY | OpenAI (GPT) | For OpenAI provider | | BRAVE_SEARCH_API_KEY | Brave Search | Optional — enables web_search tool |

The default provider out of the box is LiquidMetal.AI, which authenticates via raindrop auth jwt. To use Anthropic or OpenAI instead, set default_provider in your config file (see below).

Any OpenAI-compatible API works — adjust base_url and model names in the provider config.

Configuration

Configuration layers merge in order, with later layers overriding earlier ones:

Embedded defaults — built into the binary
Global config — ~/.raindrop-code/config.yaml
Project config — .raindrop-code/config.yaml (in your working directory)

Use the global config for personal settings. Use the project config for repo-specific overrides (different provider, different indexing behavior, etc.).

Minimal Example

default_provider: anthropic

providers:
  anthropic:
    connection:
      api_key: env:ANTHROPIC_API_KEY
      base_url: "https://api.anthropic.com/v1"
    protocol:
      type: anthropic
    model:
      default: claude-sonnet-4-5-20250929
      configs:
        claude-sonnet-4-5-20250929:
          context_window: 200000
          prompt_type: "coder"
          params:
            max_tokens: 16384
            temperature: 1.0
          extra_params:
            thinking:
              type: "enabled"
              budget_tokens: 8192
          prompt_caching:
            enabled: true

Provider Structure

Each provider has three sections:

connection — api_key and base_url. Use env:VAR_NAME to read from an environment variable, or jwt-cmd:COMMAND to get an API key from a command (the JWT is cached and auto-refreshed on expiry). Environment variables like ANTHROPIC_API_KEY, OPENAI_API_KEY, ANTHROPIC_BASE_URL, and OPENAI_BASE_URL always take precedence over config values.
protocol — type is either anthropic or openai.
model — default names the model to use. configs maps model names to their settings.

Model Settings

| Field | Description | |-------|-------------| | context_window | Total context size in tokens | | prompt_type | System prompt style (see below) | | params | API parameters: max_tokens, temperature, etc. | | extra_params | Provider-specific parameters (e.g., Anthropic thinking) | | prompt_caching | Anthropic only — enabled: true for prompt caching | | dynamic_context | Enable dynamic context window management | | max_input_tokens | Maximum input tokens (when separate from output) | | max_output_tokens | Maximum output tokens | | warning_threshold | Context usage ratio that triggers a warning (e.g., 0.80) | | critical_threshold | Context usage ratio that triggers auto-compaction (e.g., 0.85) | | separate_input_output | true if the provider has separate input/output token limits |

Prompt Types

| Type | Use case | |------|----------| | coder | General-purpose coding assistant (default) | | coder-directive | Structured instructions — better for models that need clarity | | coder-reasoning | For models with built-in reasoning/chain-of-thought | | coder-terse | Minimal prompt for fast models | | teacher | Educational, explanatory mode | | reviewer | Code review mode |

OpenAI-Compatible Provider Example

providers:
  my-provider:
    connection:
      api_key: env:MY_API_KEY
      base_url: "https://api.example.com/v1"
    protocol:
      type: openai
    model:
      default: my-model
      configs:
        my-model:
          context_window: 128000
          prompt_type: "coder"
          params:
            max_tokens: 8192
            temperature: 0.7

default_provider: my-provider

Resource Directories

Control where agents, commands, skills, and coordinators load from:

resources:
  skill_dirs:
    - "{home}/.raindrop-code/skills"
    - "{cwd}/.raindrop-code/skills"
  agent_dirs:
    - "{home}/.raindrop-code/agents"
    - "{cwd}/.raindrop-code/agents"
  command_dirs:
    - "{home}/.raindrop-code/commands"
    - "{cwd}/.raindrop-code/commands"
  coordinator_dirs:
    - "{home}/.raindrop-code/coordinators"
    - "{cwd}/.raindrop-code/coordinators"

{home} expands to your home directory. {cwd} expands to the current working directory. Directories are searched in order — later entries override earlier ones. Embedded defaults always have the lowest precedence.

CLI Usage

raindrop-code                                  # Launch interactive session
raindrop-code --version                        # Print version
raindrop-code -p anthropic                     # Use a specific provider
raindrop-code -p anthropic/claude-sonnet-4-5-20250929  # Provider and model
raindrop-code mcp list                         # List MCP servers
raindrop-code mcp add --name github ...        # Add an MCP server
raindrop-code mcp remove github                # Remove an MCP server
raindrop-code mcp auth github                  # Authenticate with an MCP server

Git Repository Detection

When started inside a git repository subdirectory, Raindrop Code detects the repository root and asks whether to change to it. Working from the root gives better codebase context and more accurate search results.

Slash Commands

Type these in the interactive session.

System Commands

| Command | Description | |---------|-------------| | /clear | Clear conversation history | | /compact | Manually compact context (also runs automatically at threshold) | | /context | Toggle context panel — shows indexing status, token usage, working set | | /debug | Toggle debug panel (also F12) | | /help | Show quick reference guide | | /readme | Show full documentation | | /reindex | Rebuild workspace index |

MCP Commands

| Command | Description | |---------|-------------| | /mcp list | Show configured MCP servers | | /mcp add | Add a server (--name, --transport, --url) | | /mcp remove <name> | Remove a server | | /mcp auth <name> | Authenticate with a server |

Built-in Custom Commands

| Command | Description | |---------|-------------| | /commit | Create a git commit with a formatted message | | /explain | Explain the codebase architecture | | /review <file> | Review a file using the code-reviewer agent | | /summarize | Summarize the conversation | | /agent | Create a new custom agent |

AI Tools

The AI can use these tools during a conversation:

| Tool | Description | |------|-------------| | read_file | Read file contents | | write_file | Create or overwrite files | | edit_file | Make targeted edits to existing files | | bash | Run shell commands (including git) | | search | Code search with symbol understanding | | explore | Browse directories, view structure and symbols | | web_search | Search the web (requires BRAVE_SEARCH_API_KEY) | | web_fetch | Fetch content from a URL | | ask_user | Ask you a clarifying question | | agent_tool | Spawn a sub-agent for a specialized task | | session_control | Coordinator signal management | | start_coordinator | Start a multi-session coordinator | | reset | Clear conversation and optionally start a new prompt |

When a tool requires approval, press y to allow once, a to allow for the session, or n to deny.

Features

Codebase Indexing

Raindrop Code indexes your project on startup and watches for file changes. This powers the search and explore tools with symbol-aware code intelligence. Rebuild the index manually with /reindex.

Sub-agents

The AI can spawn specialized sub-agents (up to 10 in parallel) for tasks like code review, exploration, and writing. Built-in agents include:

code-reviewer — reviews code for quality, bugs, security, and best practices
explorer — navigates and maps codebase structure
technical-writer — documents code with precision
review-filter — analyzes git changes and filters out generated files, lock files, data files, and binaries
review-clusterer — groups changed files into logical, reviewable clusters with dependency awareness

Coordinators

Coordinators are TypeScript modules that orchestrate multi-session workflows. They can pass prompts to AI sessions, collect results, manage state, and coordinate complex multi-step tasks. Store them in ~/.raindrop-code/coordinators/ or distribute them via npm.

MCP (Model Context Protocol)

Raindrop Code integrates with MCP servers, giving the AI access to external tools and data sources. Manage servers with raindrop-code mcp or the /mcp slash command.

Context Management

The context panel (/context) shows token usage and the working set. When usage reaches the warning threshold (default 80%), you get a warning. At the critical threshold (default 85%), context auto-compacts. Compact manually anytime with /compact.

Session Persistence

Conversations persist across sessions. The AI retains context about your project as you work. Use the session picker (available through the quick actions menu via Tab) to browse and switch between previous sessions. Sessions can also be forked, creating a new session that inherits the conversation history from a parent session.

Mermaid Diagrams

Mermaid code blocks in AI responses are rendered as Unicode diagrams directly in the terminal. Supported diagram types include flowcharts (graph TD / graph LR), sequence diagrams, and state diagrams.

Auto-Approve Mode

Toggle auto-approve mode from the quick actions menu (Tab → a). When enabled, tool calls are approved automatically without prompting. Useful for trusted workflows where you don't want to confirm each tool invocation.

External Editor

Press Tab → e to compose your message in an external editor (uses $EDITOR). Useful for writing longer, multi-line prompts.

Thinking Visibility

Press Ctrl+T to toggle visibility of the AI's reasoning/thinking process inline. This shows the chain-of-thought for models that support extended thinking (e.g., Claude with thinking enabled).

Location Approval

When started in a risky directory (home directory, root, or system paths), Raindrop Code prompts for confirmation before indexing. Approved locations are remembered for future sessions.

@File References

Type @ followed by a partial path to reference a file in your prompt. Press Tab to autocomplete and / to drill into subdirectories.

Customization

Custom Commands

Create markdown files in ~/.raindrop-code/commands/:

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

Run the test suite. Analyze any failures, fix them, and re-run to verify.
Focus on: {{.Arg}}

The filename (without .md) becomes the command name. {{.Arg}} expands to whatever the user types after the command. Use it as /mycommand some argument.

Custom Agents

Create markdown files in ~/.raindrop-code/agents/:

---
name: security-auditor
description: Audit code for security vulnerabilities
tools: [read_file, search, bash]
model: inherit
---

You are a security auditor. Examine code for vulnerabilities including
injection flaws, authentication issues, and data exposure risks.
Report findings with severity, location, and remediation steps.

Fields:

name — identifier used to invoke the agent
description — shown when listing agents
tools — which tools the agent can use (supports glob patterns like mcp_* for wildcard matching)
model — inherit to use the current model, or specify a provider/model

Skills

Skills are knowledge modules that extend the AI with specialized instructions. Create a SKILL.md file in a directory under ~/.raindrop-code/skills/:

~/.raindrop-code/skills/my-skill/SKILL.md

The AI loads relevant skills automatically based on task context. Built-in skills include:

prd-writer — guides writing comprehensive Product Requirements Documents
skill-creator — helps create new skills that extend the AI's capabilities
agent-creator — helps create new custom sub-agents
large-review — reviews large code changes (2000+ lines) using a multi-agent strategy

Project-Specific Customization

Place a .raindrop-code/ directory in your project root with any combination of config.yaml, agents/, commands/, skills/, and coordinators/. These override global settings for that project.

my-project/
  .raindrop-code/
    config.yaml          # Project-specific provider, model, etc.
    agents/
      my-project-agent.md
    commands/
      deploy.md

Keyboard Reference

Input

| Key | Action | |-----|--------| | Enter | Send message | | Shift+Enter / Ctrl+O / Alt+Enter | Insert newline | | Ctrl+V / Cmd+V | Paste (multiline supported) | | Ctrl+C / Cmd+C | Copy selection | | ↑ / ↓ | Browse command history (when cursor is on first/last line) | | Ctrl+R | Reverse search through history |

Navigation

| Key | Action | |-----|--------| | ↑ / ↓ | Scroll viewport line by line | | PgUp / PgDown | Scroll one page | | Home / End | Jump to top / bottom |

Tool Approval

| Key | Action | |-----|--------| | y | Approve this tool call | | a | Approve this tool for the rest of the session | | n | Deny | | Esc | Cancel the operation |

Autocomplete

| Key | Action | |-----|--------| | Tab / ↓ | Next suggestion | | Shift+Tab / ↑ | Previous suggestion | | Enter | Accept | | / | Drill into directory (for @ file references) | | Esc | Cancel |

Special

| Key | Action | |-----|--------| | Tab | Open quick actions menu | | Ctrl+T | Toggle thinking/reasoning visibility | | F12 | Toggle debug panel | | Esc | Context-dependent: clear selection → dismiss panel → cancel operation | | Ctrl+C (double-tap) | Cancel current operation, then quit | | Ctrl+D (double-tap) | Quit | | Ctrl+Z | Suspend to background (Unix; resume with fg) |

Text Selection

| Action | Method | |--------|--------| | Select text | Mouse drag | | Select word | Double-click | | Select line | Triple-click | | Copy (keep selection) | c or y | | Copy (clear selection) | C or Y |

Vim-style copy keys work when the textarea is not focused. Selecting text with the mouse automatically unfocuses the textarea.

Quick Actions Menu

Press Tab to open, then:

| Key | Action | |-----|--------| | s | Search command history | | + / - | Expand / collapse sub-agents | | a | Toggle auto-approve mode | | e | Open external editor | | / | Custom commands submenu | | p | Compact conversation | | c | Toggle context panel | | r | Reindex workspace | | x | Clear conversation | | m | MCP servers submenu | | w | Show README | | h | Show help |

Navigate: ↑/↓/j/k — Select: Enter/Space — Back: ←/Backspace — Close: Esc/q

Troubleshooting

Binary not found after install The install script downloads a platform-specific native binary. If it fails (e.g., --no-optional was passed), reinstall without those flags:

npm install -g @liquidmetal-ai/raindrop-code

Unsupported platform Supported: darwin-x64, darwin-arm64, linux-x64, linux-arm64, win32-x64. Other platforms are not currently supported.

API key not working Environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY) take precedence over config file values. Verify the variable is set:

echo $ANTHROPIC_API_KEY

Context window filling up Use /compact to free space. Adjust warning_threshold and critical_threshold in your model config to trigger auto-compaction earlier.

Index seems stale Run /reindex to rebuild. This is useful after switching branches or making large external changes.