droid-patch

English | 简体中文

CLI tool to patch the droid binary with various modifications.

Installation

npm install -g droid-patch
# or use directly with npx
npx droid-patch --help

Usage

Patch and Create an Alias

# Patch with --is-custom and create an alias
npx droid-patch --is-custom droid-custom

# Patch with --skip-login to bypass login requirement
npx droid-patch --skip-login droid-nologin

# Patch with --websearch to enable local search proxy
npx droid-patch --websearch droid-search

# Patch with --websearch --standalone for fully local mode (mock non-LLM APIs)
npx droid-patch --websearch --standalone droid-local

# Patch with --reasoning-effort to enable reasoning for custom models
npx droid-patch --reasoning-effort droid-reasoning

# Patch with --statusline for a Claude-style terminal statusline
npx droid-patch --statusline droid-status

# Combine --websearch and --statusline
npx droid-patch --websearch --statusline droid-full-ui

# Enable sessions browser (interactive session selector)
npx droid-patch --statusline --sessions droid-full

# Combine multiple patches
npx droid-patch --is-custom --skip-login --websearch --reasoning-effort droid-full

# Specify a custom path to the droid binary
npx droid-patch --skip-login -p /path/to/droid my-droid

# Dry run - verify patches without actually applying them
npx droid-patch --skip-login --dry-run droid

# Verbose output
npx droid-patch --skip-login -v droid

Output to a Specific Directory

# Output patched binary to current directory
npx droid-patch --skip-login -o . my-droid

# Output to a specific directory
npx droid-patch --skip-login -o /path/to/dir my-droid

Available Options

Manage Aliases and Files

# List all aliases (shows versions, flags, creation time)
npx droid-patch list

# Remove an alias
npx droid-patch remove <alias-name>

# Remove a patched binary file by path
npx droid-patch remove ./my-droid
npx droid-patch remove /path/to/patched-binary

# Remove aliases by filter
npx droid-patch remove --patch-version=0.4.0     # by droid-patch version
npx droid-patch remove --droid-version=1.0.40    # by droid version
npx droid-patch remove --flag=websearch          # by feature flag

# Clear all droid-patch data (aliases, binaries, metadata)
npx droid-patch clear

Update Aliases

When the original droid binary is updated, you can re-apply patches to all aliases:

# Update all aliases with new droid binary
npx droid-patch update

# Update a specific alias
npx droid-patch update <alias-name>

# Preview without making changes
npx droid-patch update --dry-run

# Use a different droid binary
npx droid-patch update -p /path/to/new/droid

The update command reads metadata stored when aliases were created and re-applies the same patches automatically.

Check Version

npx droid-patch version

PATH Configuration

When creating an alias (without -o), the tool will try to install to a directory already in your PATH (like ~/.local/bin). If not available, you need to add the aliases directory to your PATH:

# Add to your shell config (~/.zshrc, ~/.bashrc, etc.)
export PATH="$HOME/.droid-patch/aliases:$PATH"

How It Works

1. Patching: The tool searches for specific byte patterns in the droid binary and replaces them with equal-length replacements
2. Alias Creation (without -o):
   • Copies the patched binary to ~/.droid-patch/bins/
   • Creates a symlink in a PATH directory or ~/.droid-patch/aliases/
   • On macOS, automatically re-signs the binary with codesign
3. Direct Output (with -o):
   • Saves the patched binary directly to the specified directory
   • On macOS, automatically re-signs the binary with codesign

Available Patches

--is-custom

Changes isCustom:!0 (true) to isCustom:!1 (false) for custom models.

Purpose: This may enable context compression (auto-summarization) for custom models, which is normally only available for official models.

Note: Side effects are unknown - test thoroughly before production use.

--skip-login

Replaces all process.env.FACTORY_API_KEY references in the binary with a hardcoded fake key "fk-droid-patch-skip-00000".

Purpose: Bypass the login/authentication requirement without needing to set the FACTORY_API_KEY environment variable.

How it works:

• The original code checks process.env.FACTORY_API_KEY to authenticate
• After patching, the code directly uses the fake key string, bypassing the env check
• This is a binary-level patch, so it works across all terminal sessions without any environment setup

--api-base <url>

Replace the Factory API base URL. Has different behavior depending on usage:

1. Standalone (without --websearch)

Binary patch to replace https://api.factory.ai with your custom URL.

• Limitation: URL must be 22 characters or less (same length as original URL)
• Use case: Direct API URL replacement without proxy

# Valid URLs (<=22 chars)
npx droid-patch --api-base "http://127.0.0.1:3000" droid-local
npx droid-patch --api-base "http://localhost:80" droid-local

# Invalid (too long)
npx droid-patch --api-base "http://my-long-domain.com:3000" droid  # Error!

2. With --websearch

Sets the forward target URL for the WebSearch proxy by configuring the FACTORY_API variable in the proxy script.

• No length limitation: Any valid URL can be used
• Use case: Forward non-search requests to your custom LLM backend

# Forward to custom backend (no length limit)
npx droid-patch --websearch --api-base "http://127.0.0.1:20002" droid-custom
npx droid-patch --websearch --api-base "http://my-proxy.example.com:3000" droid-custom

--websearch

Enables WebSearch functionality through a local proxy server that intercepts /api/tools/exa/search requests.

Purpose: Enable WebSearch functionality without Factory.ai authentication.

Features:

• Multiple search providers with automatic fallback
• Per-instance proxy: Each droid instance runs its own proxy on an auto-assigned port
• Auto-cleanup: Proxy automatically stops when droid exits
• Forward target: Use --api-base with --websearch to forward non-search requests to a custom backend
• Non-interactive passthrough: --version/version, --help/help, completion(s), exec do not start the proxy

Usage:

# Create alias with websearch (uses official Factory API)
npx droid-patch --websearch droid-search

# Create alias with websearch + custom backend
npx droid-patch --websearch --api-base=http://127.0.0.1:20002 droid-custom

# Just run it - everything is automatic!
droid-search

--reasoning-effort

Enables reasoning effort control for custom models by patching the binary to:

1. Set supportedReasoningEfforts from ["none"] to ["high"]
2. Set defaultReasoningEffort from "none" to "high"
3. Enable the reasoning effort UI selector (normally hidden for custom models)
4. Bypass validation to allow xhigh via settings.json

Purpose: Allow custom models to use reasoning effort features that are normally only available for official models.

How it works:

• The droid UI shows a reasoning effort selector when supportedReasoningEfforts.length > 1
• Custom models are hardcoded with ["none"], hiding the selector
• This patch changes the value to ["high"] and modifies the UI condition to show the selector
• The reasoning effort setting will be sent to your custom model's API

Usage:

# Enable reasoning effort for custom models
npx droid-patch --reasoning-effort droid-reasoning

# Combine with other patches
npx droid-patch --is-custom --reasoning-effort droid-full

Configuring xhigh Reasoning Effort:

The default reasoning effort is high. To use xhigh (extra high), edit your settings file:

# Edit ~/.factory/settings.json
{
  "model": "custom:Your-Model-0",
  "reasoningEffort": "xhigh",
  // ... other settings
}

Available values:

Note: The xhigh value bypasses validation and is sent directly to your API. Make sure your custom model/proxy supports this parameter.

--standalone

Enables standalone mode when used with --websearch. In this mode, non-LLM Factory APIs are mocked locally instead of being forwarded to Factory servers.

Purpose: Reduce unnecessary network requests and enable fully local operation (except for LLM API calls).

How it works:

• Whitelist approach: Only /api/llm/a/* (Anthropic) and /api/llm/o/* (OpenAI) are forwarded to upstream
• All other Factory APIs are mocked:
  • /api/sessions/create → Returns unique local session ID
  • /api/cli/whoami → Returns 401 (triggers local token fallback)
  • /api/tools/get-url-contents → Returns 404 (triggers local URL fetch)
  • Other APIs → Returns empty {} response

Usage:

# Standalone mode with websearch
npx droid-patch --websearch --standalone droid-local

# Combine with other patches for fully local setup
npx droid-patch --is-custom --skip-login --websearch --standalone droid-full-local

--disable-telemetry

Disables telemetry data uploads and Sentry error reporting.

Purpose: Prevent droid from sending usage data and error reports to Factory servers.

How it works:

• Breaks Sentry environment variable checks (ENABLE_SENTRY, VITE_VERCEL_ENV)
• Makes flushToWeb() always return early, preventing any telemetry fetch requests

Usage:

# Disable telemetry only
npx droid-patch --disable-telemetry droid-private

# Combine with other patches
npx droid-patch --is-custom --skip-login --disable-telemetry droid-private

--statusline

Enables a Claude-style statusline at the bottom of the terminal, displaying real-time session information.

Purpose: Provide at-a-glance visibility into model, context usage, git status, and token usage without interrupting the main UI.

Features:

• Real-time context tracking: Shows current token usage (cache read + new input)
• Model info: Displays the active model and provider
• Token usage summary: Shows session totals (In/Out/Cre/Read/Think) plus LastOut for the most recent reply
• Git integration: Shows current branch and diff summary (+insertions, -deletions)
• Compaction indicator: Shows when context compaction is in progress
• PTY proxy architecture: Reserves bottom row(s) for statusline without flickering
• Non-interactive passthrough: --version/version, --help/help, completion(s), exec (or non-TTY) bypass the statusline wrapper

How it works:

1. A Python PTY wrapper intercepts terminal I/O and reserves bottom row(s)
2. A Node.js monitor script tails the Factory log file (~/.factory/logs/droid-log-single.log)
3. The monitor parses streaming token usage and emits statusline frames
4. The wrapper renders the latest frame on the reserved rows

Usage:

# Enable statusline only
npx droid-patch --statusline droid-status

# Combine with websearch
npx droid-patch --websearch --statusline droid-full-ui

# Combine with all features
npx droid-patch --is-custom --skip-login --websearch --statusline droid-ultimate

Example statusline display:

 Model: claude-sonnet-4-20250514  Prov: anthropic  Ctx: 12345 (c8000+n4345)  In:33 Out:1273 Cre:33.9k Read:25.9k Think:212 LastOut:130  ⎇ main (+10,-5)  cwd: my-project

Note: The statusline requires Python 3 for the PTY wrapper. It works best in modern terminal emulators (iTerm2, Alacritty, Kitty, etc.). Apple Terminal is supported but uses a longer render interval to reduce flicker.

--sessions

Enables an interactive sessions browser that allows you to browse, search, and resume past sessions in the current directory.

Purpose: Quickly find and resume previous conversations without remembering session IDs.

Features:

• Interactive selector: Use arrow keys (↑/↓) or vim keys (j/k) to navigate
• Session details: Shows session ID, title, model, message count, timestamps
• First/last input display: Preview what you discussed in each session
• Auto-resume: Press Enter to resume the selected session with all patch features preserved
• Filtered results: Only shows sessions with actual user interactions (no empty sessions)
• Sorted by recency: Most recently used sessions appear first

Usage:

# Enable sessions browser (requires --statusline)
npx droid-patch --statusline --sessions droid-full

# Browse sessions
droid-full --sessions

Interactive controls:

• ↑/↓ or j/k - Navigate up/down
• Page Up/Page Down - Jump pages
• Enter - Resume selected session
• q or Ctrl+C - Quit

Example display:

Sessions: /Users/you/project
[↑/↓] Select  [Enter] Resume  [q] Quit

▶ Fix statusline flickering issue
    ID: abc123def456...
    Last: 12-18 14:30 | Model: claude-sonnet-4 | 42 msgs
    First input: The statusline is flickering when...
    Last input:  Can you also add error handling?

  Add websearch feature (12-17 09:15)
  Refactor CLI options (12-16 18:22)

Page 1/3 (25 sessions)

Note: The --sessions flag requires --statusline to be enabled. Sessions are stored in ~/.factory/sessions/ and filtered by the current working directory.

WebSearch Configuration Guide

The --websearch feature supports multiple search providers. Configure them using environment variables in your shell config (~/.zshrc, ~/.bashrc, etc.).

Search Provider Priority

The proxy tries providers in this order and uses the first one that succeeds:

1. Smithery Exa (Recommended)

Smithery Exa provides high-quality semantic search results through the MCP protocol. Smithery acts as a free proxy to the Exa search API.

Setup Steps

1. Create a Smithery Account

   • Go to smithery.ai
   • Sign up for a free account

2. Get Your API Key

   • Navigate to your account settings
   • Copy your API key

3. Get Your Profile ID

   • Go to smithery.ai/server/exa
   • Your profile ID is shown in the connection URL or settings

4. Configure Environment Variables

   # Add to ~/.zshrc or ~/.bashrc
   export SMITHERY_API_KEY="your_api_key_here"
   export SMITHERY_PROFILE="your_profile_id"

Pricing

• Free through Smithery (Smithery proxies the Exa API at no cost)
• Note: The official Exa API (exa.ai) is paid, but Smithery provides free access

2. Google Programmable Search Engine (PSE)

Google PSE provides high-quality search results with a generous free tier.

Setup Steps

Step 1: Create a Programmable Search Engine

1. Go to Google Programmable Search Engine Console
2. Click "Add" to create a new search engine
3. Configure:
   • Sites to search: Enter * to search the entire web
   • Name: Give it a descriptive name (e.g., "Web Search")
4. Click "Create"
5. Click "Control Panel" for your new search engine
6. Copy the Search engine ID (cx) - looks like 017576662512468239146:omuauf_lfve

Step 2: Get an API Key

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Custom Search API:
   • Go to "APIs & Services" > "Library"
   • Search for "Custom Search API"
   • Click "Enable"
4. Create credentials:
   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "API Key"
   • Copy the API key

Step 3: Configure Environment Variables

# Add to ~/.zshrc or ~/.bashrc
export GOOGLE_PSE_API_KEY="AIzaSy..."        # Your API key
export GOOGLE_PSE_CX="017576662512468239146:omuauf_lfve"  # Your Search engine ID

Free Tier Limits

• 10,000 queries/day free
• Max 10 results per query
• After limit: $5 per 1,000 queries

3. Serper

Serper provides Google search results through an easy-to-use API.

Setup Steps

1. Create an Account

   • Go to serper.dev
   • Sign up for a free account

2. Get Your API Key

   • After signing in, your API key is displayed on the dashboard
   • Copy the API key

3. Configure Environment Variable

   # Add to ~/.zshrc or ~/.bashrc
   export SERPER_API_KEY="your_api_key_here"

Free Tier

• 2,500 free credits on signup
• 1 credit = 1 search query
• Paid plans available for more usage

4. Brave Search

Brave Search API provides privacy-focused search results.

Setup Steps

1. Create an Account

   • Go to brave.com/search/api
   • Click "Get Started"

2. Subscribe to a Plan

   • Choose the Free plan (2,000 queries/month)
   • Or a paid plan for more queries

3. Get Your API Key

   • Go to your API dashboard
   • Copy your API key

4. Configure Environment Variable

   # Add to ~/.zshrc or ~/.bashrc
   export BRAVE_API_KEY="BSA..."

Free Tier

• 2,000 queries/month free
• Rate limit: 1 query/second
• Paid plans start at $5/month for 20,000 queries

5. SearXNG (Self-Hosted)

SearXNG is a free, privacy-respecting metasearch engine you can self-host.

Setup Steps

Option A: Use a Public Instance

You can use a public SearXNG instance, but availability and reliability vary.

# Example public instance (check if it's available)
export SEARXNG_URL="https://searx.be"

Find public instances at searx.space

Option B: Self-Host with Docker

1. Run SearXNG with Docker

   docker run -d \
     --name searxng \
     -p 8080:8080 \
     -e SEARXNG_BASE_URL=http://localhost:8080 \
     searxng/searxng

2. Configure Environment Variable

   # Add to ~/.zshrc or ~/.bashrc
   export SEARXNG_URL="http://localhost:8080"

Advantages

• Unlimited searches
• No API key required
• Privacy-focused
• Aggregates results from multiple search engines

Disadvantages

• Requires self-hosting for reliability
• Public instances may be slow or unavailable

6. DuckDuckGo (Default Fallback)

DuckDuckGo is used automatically as the final fallback when no other providers are configured or available.

Configuration

No configuration required! DuckDuckGo works out of the box.

Limitations

• HTML scraping (less reliable than API)
• Basic results compared to other providers
• May be rate-limited with heavy use

Quick Configuration Examples

Minimal Setup (Free, No API Keys)

Just use DuckDuckGo fallback:

npx droid-patch --websearch droid-search
droid-search  # Works immediately with DuckDuckGo

Recommended Setup (Best Quality)

# Add to ~/.zshrc or ~/.bashrc
export SMITHERY_API_KEY="your_smithery_key"
export SMITHERY_PROFILE="your_profile_id"

# Fallback: Google PSE
export GOOGLE_PSE_API_KEY="your_google_key"
export GOOGLE_PSE_CX="your_search_engine_id"

Budget-Friendly Setup (All Free)

# Add to ~/.zshrc or ~/.bashrc

# Option 1: Google PSE (10,000/day free)
export GOOGLE_PSE_API_KEY="your_google_key"
export GOOGLE_PSE_CX="your_search_engine_id"

# Option 2: Serper (2,500 free credits)
export SERPER_API_KEY="your_serper_key"

# Option 3: Brave (2,000/month free)
export BRAVE_API_KEY="your_brave_key"

# DuckDuckGo is always available as final fallback

Debug Mode

Enable detailed logging to troubleshoot search issues:

export DROID_SEARCH_DEBUG=1
droid-search

Examples

# Quick start: create droid with websearch
npx droid-patch --websearch droid-search
droid-search  # Just works!

# Full-featured droid
npx droid-patch --is-custom --skip-login --websearch --reasoning-effort droid-full

# Standalone mode: websearch + mock non-LLM APIs
npx droid-patch --websearch --standalone droid-local

# Privacy mode: disable telemetry
npx droid-patch --disable-telemetry droid-private

# Statusline mode: Claude-style terminal statusline
npx droid-patch --statusline droid-status

# Statusline + Sessions: browse and resume past sessions
npx droid-patch --statusline --sessions droid-full
droid-full --sessions  # Interactive session browser

# Websearch + Statusline: full UI experience
npx droid-patch --websearch --statusline droid-full-ui

# Full local setup: all features combined
npx droid-patch --is-custom --skip-login --websearch --standalone --disable-telemetry droid-full-local

# Ultimate setup: all features including statusline
npx droid-patch --is-custom --skip-login --websearch --standalone --statusline --disable-telemetry droid-ultimate

# Websearch with custom backend
npx droid-patch --websearch --api-base=http://127.0.0.1:20002 droid-custom

# Create a standalone patched binary in current directory
npx droid-patch --skip-login -o . my-droid
./my-droid --version

# List all aliases with version info
npx droid-patch list

# Clean up
npx droid-patch remove droid-search              # remove single alias
npx droid-patch remove --flag=websearch          # remove all websearch aliases
npx droid-patch remove --flag=statusline         # remove all statusline aliases
npx droid-patch remove --flag=sessions           # remove all sessions-enabled aliases
npx droid-patch remove --flag=standalone         # remove all standalone aliases
npx droid-patch remove --patch-version=0.4.0     # remove by droid-patch version
npx droid-patch clear                            # remove everything

License

MIT