{"id":34761094,"url":"https://github.com/kingsword09/droid-patch","last_synced_at":"2026-03-11T02:17:33.945Z","repository":{"id":328132822,"uuid":"1114302588","full_name":"kingsword09/droid-patch","owner":"kingsword09","description":"CLI tool to patch the droid binary with various modifications.","archived":false,"fork":false,"pushed_at":"2026-02-27T02:27:57.000Z","size":426,"stargazers_count":32,"open_issues_count":0,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-27T09:45:40.073Z","etag":null,"topics":["ai","droid","patch"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/droid-patch","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kingsword09.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-11T07:20:01.000Z","updated_at":"2026-02-27T02:27:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kingsword09/droid-patch","commit_stats":null,"previous_names":["kingsword09/droid-patch"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/kingsword09/droid-patch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingsword09%2Fdroid-patch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingsword09%2Fdroid-patch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingsword09%2Fdroid-patch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingsword09%2Fdroid-patch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kingsword09","download_url":"https://codeload.github.com/kingsword09/droid-patch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingsword09%2Fdroid-patch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30367811,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T21:41:54.280Z","status":"online","status_checked_at":"2026-03-11T02:00:07.027Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","droid","patch"],"created_at":"2025-12-25T06:27:43.694Z","updated_at":"2026-03-11T02:17:33.932Z","avatar_url":"https://github.com/kingsword09.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# droid-patch\n\nEnglish | [简体中文](./README.zh-CN.md)\n\nCLI tool to patch the droid binary with various modifications.\n\n## Installation\n\n```bash\nnpm install -g droid-patch\n# or use directly with npx\nnpx droid-patch --help\n```\n\n## Usage\n\n### Patch and Create an Alias\n\n```bash\n# Patch with --is-custom and create an alias\nnpx droid-patch --is-custom droid-custom\n\n# Patch with --skip-login to bypass login requirement\nnpx droid-patch --skip-login droid-nologin\n\n# Patch with --websearch to enable local search proxy\nnpx droid-patch --websearch droid-search\n\n# Patch with --websearch --standalone for fully local mode (mock non-LLM APIs)\nnpx droid-patch --websearch --standalone droid-local\n\n# Patch with --reasoning-effort to enable reasoning for custom models\nnpx droid-patch --reasoning-effort droid-reasoning\n\n# Combine multiple patches\nnpx droid-patch --is-custom --skip-login --websearch --reasoning-effort droid-full\n\n# Specify a custom path to the droid binary\nnpx droid-patch --skip-login -p /path/to/droid my-droid\n\n# Dry run - verify patches without actually applying them\nnpx droid-patch --skip-login --dry-run droid\n\n# Verbose output\nnpx droid-patch --skip-login -v droid\n```\n\n### Output to a Specific Directory\n\n```bash\n# Output patched binary to current directory\nnpx droid-patch --skip-login -o . my-droid\n\n# Output to a specific directory\nnpx droid-patch --skip-login -o /path/to/dir my-droid\n```\n\n### Available Options\n\n| Option                | Description                                                                                                  |\n| --------------------- | ------------------------------------------------------------------------------------------------------------ |\n| `--is-custom`         | Patch `isCustom:!0` to `isCustom:!1` (enables context compression for custom models)                         |\n| `--skip-login`        | Bypass login by injecting a fake `FACTORY_API_KEY` into the binary                                           |\n| `--api-base \u003curl\u003e`    | Replace API URL (standalone: binary patch, max 22 chars; with `--websearch`: proxy forward target, no limit) |\n| `--websearch`         | External providers mode: Smithery, Google PSE, Tavily, Serper, Brave, SearXNG, DuckDuckGo                    |\n| `--websearch-proxy`   | Native provider mode: use model's built-in web_search (requires proxy plugin)                                |\n| `--standalone`        | Standalone mode: mock non-LLM Factory APIs (use with `--websearch` or `--websearch-proxy`)                   |\n| `--reasoning-effort`  | Enable reasoning effort UI selector for custom models (default `high`; options: `high`, `max`, `xhigh`)      |\n| `--disable-telemetry` | Disable telemetry and Sentry error reporting                                                                 |\n| `--dry-run`           | Verify patches without actually modifying the binary                                                         |\n| `-p, --path \u003cpath\u003e`   | Path to the droid binary (default: `~/.droid/bin/droid`)                                                     |\n| `-o, --output \u003cdir\u003e`  | Output directory for patched binary (creates file without alias)                                             |\n| `--no-backup`         | Skip creating backup of original binary                                                                      |\n| `-v, --verbose`       | Enable verbose output                                                                                        |\n\n### Manage Custom Models\n\n```bash\n# List all custom models\nnpx droid-patch list-models\n\n# Add model interactively\nnpx droid-patch add-model\n\n# Add model via command line\nnpx droid-patch add-model \\\n  -m \"claude-sonnet-4-20250514\" \\\n  -n \"Sonnet [proxy]\" \\\n  -u \"http://127.0.0.1:20002/droid\" \\\n  -k \"your-api-key\" \\\n  -p \"anthropic\"\n\n# Insert model at specific position\nnpx droid-patch add-model -i 0  # Interactive, insert at position 0\n\n# Remove model (supports index, ID, or displayName)\nnpx droid-patch remove-model 0                    # By index\nnpx droid-patch remove-model \"custom:Sonnet-[proxy]-1\"  # By ID\nnpx droid-patch remove-model \"Sonnet [proxy]\"    # By display name\n```\n\n**Model ID Format**: `custom:{DisplayName}-{index}`\n\n- Spaces in `DisplayName` are replaced with `-`\n- `index` is the position in the array (starting from 0)\n- Example: `displayName: \"Opus [proxy]\"` → `id: \"custom:Opus-[proxy]-0\"`\n\n**Important**: When deleting or inserting models, subsequent model IDs are automatically updated (because index changes).\n\n### Manage Aliases and Files\n\n```bash\n# List all aliases (shows versions, flags, creation time)\nnpx droid-patch list\n\n# Remove an alias\nnpx droid-patch remove \u003calias-name\u003e\n\n# Remove a patched binary file by path\nnpx droid-patch remove ./my-droid\nnpx droid-patch remove /path/to/patched-binary\n\n# Remove aliases by filter\nnpx droid-patch remove --patch-version=0.4.0     # by droid-patch version\nnpx droid-patch remove --droid-version=1.0.40    # by droid version\nnpx droid-patch remove --flag=websearch          # by feature flag\n\n# Clear all droid-patch data (aliases, binaries, metadata)\nnpx droid-patch clear\n```\n\n### Update Aliases\n\nWhen the original droid binary is updated, you can re-apply patches to all aliases:\n\n```bash\n# Update all aliases with new droid binary\nnpx droid-patch update\n\n# Update a specific alias\nnpx droid-patch update \u003calias-name\u003e\n\n# Preview without making changes\nnpx droid-patch update --dry-run\n\n# Use a different droid binary\nnpx droid-patch update -p /path/to/new/droid\n```\n\nThe update command reads metadata stored when aliases were created and re-applies the same patches automatically.\n\n### Check Version\n\n```bash\nnpx droid-patch version\n```\n\n## PATH Configuration\n\nWhen 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:\n\n```bash\n# Add to your shell config (~/.zshrc, ~/.bashrc, etc.)\nexport PATH=\"$HOME/.droid-patch/aliases:$PATH\"\n```\n\n## How It Works\n\n1. **Patching**: The tool searches for specific byte patterns in the droid binary and replaces them with equal-length replacements\n2. **Alias Creation** (without `-o`):\n   - Copies the patched binary to `~/.droid-patch/bins/`\n   - Creates a symlink in a PATH directory or `~/.droid-patch/aliases/`\n   - On macOS, automatically re-signs the binary with `codesign`\n3. **Direct Output** (with `-o`):\n   - Saves the patched binary directly to the specified directory\n   - On macOS, automatically re-signs the binary with `codesign`\n\n## Available Patches\n\n### `--is-custom`\n\nChanges `isCustom:!0` (true) to `isCustom:!1` (false) for custom models.\n\n**Purpose**: This may enable context compression (auto-summarization) for custom models, which is normally only available for official models.\n\n**Note**: Side effects are unknown - test thoroughly before production use.\n\n### `--skip-login`\n\nReplaces all `process.env.FACTORY_API_KEY` references in the binary with a hardcoded fake key `\"fk-droid-patch-skip-00000\"`.\n\n**Purpose**: Bypass the login/authentication requirement without needing to set the `FACTORY_API_KEY` environment variable.\n\n**How it works**:\n\n- The original code checks `process.env.FACTORY_API_KEY` to authenticate\n- After patching, the code directly uses the fake key string, bypassing the env check\n- This is a binary-level patch, so it works across all terminal sessions without any environment setup\n\n### `--api-base \u003curl\u003e`\n\nReplace the Factory API base URL. Has different behavior depending on usage:\n\n**1. Standalone (without `--websearch`)**\n\nBinary patch to replace `https://api.factory.ai` with your custom URL.\n\n- **Limitation**: URL must be 22 characters or less (same length as original URL)\n- **Use case**: Direct API URL replacement without proxy\n\n```bash\n# Valid URLs (\u003c=22 chars)\nnpx droid-patch --api-base \"http://127.0.0.1:3000\" droid-local\nnpx droid-patch --api-base \"http://localhost:80\" droid-local\n\n# Invalid (too long)\nnpx droid-patch --api-base \"http://my-long-domain.com:3000\" droid  # Error!\n```\n\n**2. With `--websearch`**\n\nSets the forward target URL for the WebSearch proxy by configuring the `FACTORY_API` variable in the proxy script.\n\n- **No length limitation**: Any valid URL can be used\n- **Use case**: Forward non-search requests to your custom LLM backend\n\n```bash\n# Forward to custom backend (no length limit)\nnpx droid-patch --websearch --api-base \"http://127.0.0.1:20002\" droid-custom\nnpx droid-patch --websearch --api-base \"http://my-proxy.example.com:3000\" droid-custom\n```\n\n### `--websearch` vs `--websearch-proxy`\n\n**Important**: `--websearch` and `--websearch-proxy` are **mutually exclusive** - you can only use one at a time.\n\n| Mode                | Description                          | Requires                    |\n| ------------------- | ------------------------------------ | --------------------------- |\n| `--websearch`       | External search providers            | Environment variables       |\n| `--websearch-proxy` | Model's native web_search capability | Proxy plugin + custom model |\n\n### `--websearch`\n\nEnables WebSearch via **external search providers** through a local proxy server.\n\n**Purpose**: Enable WebSearch using third-party search APIs.\n\n**Features**:\n\n- **Multiple search providers** with automatic fallback (Smithery \u003e Google PSE \u003e Tavily \u003e Serper \u003e Brave \u003e SearXNG \u003e DuckDuckGo)\n- **Per-instance proxy**: Each droid instance runs its own proxy on an auto-assigned port\n- **Auto-cleanup**: Proxy automatically stops when droid exits\n- **Forward target**: Use `--api-base` with `--websearch` to forward non-search requests to a custom backend\n- **Non-interactive passthrough**: `--version`/`version`, `--help`/`help`, `completion(s)`, `exec` do not start the proxy\n\n**Usage**:\n\n```bash\n# Create alias with websearch (uses official Factory API)\nnpx droid-patch --websearch droid-search\n\n# Create alias with websearch + custom backend\nnpx droid-patch --websearch --api-base=http://127.0.0.1:20002 droid-custom\n\n# Just run it - everything is automatic!\ndroid-search\n```\n\n### `--websearch-proxy`\n\nEnables WebSearch via **model's native web_search capability** (e.g., Claude's `web_search_20250305` tool).\n\n**Purpose**: Use the LLM provider's built-in web search instead of external providers.\n\n**Requirements**:\n\n1. **Custom model** configured in `~/.factory/settings.json` with a supported provider (`anthropic` or `openai`)\n2. **Proxy plugin** ([jixoai/proxy](https://github.com/jixoai/proxy)) to handle Claude Code format conversion\n\n**Features**:\n\n- Reads model configuration from `~/.factory/settings.json`\n- Supports Anthropic (`web_search_20250305`) and OpenAI (`web_search`) native tools\n- Automatically detects current model's provider\n- No external API keys needed (uses your LLM provider's search)\n\n**Usage**:\n\n```bash\n# Create alias with native websearch (requires proxy plugin)\nnpx droid-patch --is-custom --skip-login --websearch-proxy droid-native\n\n# Combine with reasoning effort\nnpx droid-patch --is-custom --skip-login --reasoning-effort --websearch-proxy droid-full\n\n# Debug mode\nDROID_SEARCH_DEBUG=1 droid-native\n```\n\n**Proxy Plugin Setup**:\n\nThe `--websearch-proxy` mode requires the [jixoai/proxy](https://github.com/jixoai/proxy) plugin to convert between Claude Code format and standard Anthropic API format.\n\n```bash\n# Clone and setup the proxy\ngit clone https://github.com/jixoai/proxy.git\ncd proxy\n\n# Install and run (see proxy README for details)\npnpm install\npnpm dev\n```\n\nConfigure your custom model in `~/.factory/settings.json`:\n\n```json\n{\n  \"customModels\": [\n    {\n      \"model\": \"claude-sonnet-4-20250514\",\n      \"id\": \"custom:Opus-[proxy]-0\",\n      \"baseUrl\": \"http://127.0.0.1:20002/droid\",\n      \"apiKey\": \"your-api-key\",\n      \"displayName\": \"Opus [proxy]\",\n      \"provider\": \"anthropic\"\n    }\n  ],\n  \"sessionDefaultSettings\": {\n    \"model\": \"custom:Opus-[proxy]-0\"\n  }\n}\n```\n\n**Important**: The `id` field must match the `displayName` pattern:\n\n- Format: `custom:{DisplayName}-{index}` where spaces are replaced with `-`\n- Example: `displayName: \"Opus [proxy]\"` → `id: \"custom:Opus-[proxy]-0\"`\n- The trailing number (`-0`) is the index (starting from 0)\n\n### `--reasoning-effort`\n\nEnables reasoning effort control for custom models by patching the binary to:\n\n1. Set `supportedReasoningEfforts` from `[\"none\"]` to `[\"high\",\"max\",\"xhigh\"]`\n2. Set `defaultReasoningEffort` from `\"none\"` to `\"high\"`\n3. Enable the reasoning effort UI selector (normally hidden for custom models)\n4. Bypass validation to allow `xhigh` via settings.json\n\n**Purpose**: Allow custom models to use reasoning effort features that are normally only available for official models.\n\n**How it works**:\n\n- The droid UI shows a reasoning effort selector when `supportedReasoningEfforts.length \u003e 1`\n- Custom models are hardcoded with `[\"none\"]`, hiding the selector\n- This patch changes the value to `[\"high\",\"max\",\"xhigh\"]` and modifies the UI condition to show the selector\n- The reasoning effort setting will be sent to your custom model's API\n\n**Usage**:\n\n```bash\n# Enable reasoning effort for custom models\nnpx droid-patch --reasoning-effort droid-reasoning\n\n# Combine with other patches\nnpx droid-patch --is-custom --reasoning-effort droid-full\n```\n\n**Configuring `xhigh` Reasoning Effort**:\n\nThe default reasoning effort is `high`. To use `xhigh` (extra high), edit your settings file:\n\n```bash\n# Edit ~/.factory/settings.json\n{\n  \"model\": \"custom:Your-Model-0\",\n  \"reasoningEffort\": \"xhigh\",\n  // ... other settings\n}\n```\n\nAvailable values:\n| Value | Description |\n|-------|-------------|\n| `high` | High reasoning effort (default after patching) |\n| `max` | Maximum reasoning effort |\n| `xhigh` | Extra high reasoning effort |\n\n**Note**: The `xhigh` value bypasses validation and is sent directly to your API. Make sure your custom model/proxy supports this parameter.\n\n### `--standalone`\n\nEnables standalone mode when used with `--websearch`. In this mode, non-LLM Factory APIs are mocked locally instead of being forwarded to Factory servers.\n\n**Purpose**: Reduce unnecessary network requests and enable fully local operation (except for LLM API calls).\n\n**How it works**:\n\n- **Whitelist approach**: Only `/api/llm/a/*` (Anthropic) and `/api/llm/o/*` (OpenAI) are forwarded to upstream\n- All other Factory APIs are mocked:\n  - `/api/sessions/create` → Returns unique local session ID\n  - `/api/cli/whoami` → Returns 401 (triggers local token fallback)\n  - `/api/tools/get-url-contents` → Returns 404 (triggers local URL fetch)\n  - Other APIs → Returns empty `{}` response\n\n**Usage**:\n\n```bash\n# Standalone mode with websearch\nnpx droid-patch --websearch --standalone droid-local\n\n# Combine with other patches for fully local setup\nnpx droid-patch --is-custom --skip-login --websearch --standalone droid-full-local\n```\n\n### `--disable-telemetry`\n\nDisables telemetry data uploads and Sentry error reporting.\n\n**Purpose**: Prevent droid from sending usage data and error reports to Factory servers.\n\n**How it works**:\n\n- Breaks Sentry environment variable checks (`ENABLE_SENTRY`, `VITE_VERCEL_ENV`)\n- Makes `flushToWeb()` always return early, preventing any telemetry fetch requests\n\n**Usage**:\n\n```bash\n# Disable telemetry only\nnpx droid-patch --disable-telemetry droid-private\n\n# Combine with other patches\nnpx droid-patch --is-custom --skip-login --disable-telemetry droid-private\n```\n\n---\n\n## WebSearch Configuration Guide\n\nThe `--websearch` feature supports multiple search providers. Configure them using environment variables in your shell config (`~/.zshrc`, `~/.bashrc`, etc.).\n\n### Search Provider Priority\n\nThe proxy tries providers in this order and uses the first one that succeeds:\n\n| Priority | Provider     | Quality   | Free Tier             | Setup Difficulty |\n| -------- | ------------ | --------- | --------------------- | ---------------- |\n| 1        | Smithery Exa | Excellent | Free (via Smithery)   | Easy             |\n| 2        | Google PSE   | Very Good | 10,000/day            | Medium           |\n| 3        | Tavily       | Very Good | Free credits (varies) | Easy             |\n| 4        | Serper       | Very Good | 2,500 free credits    | Easy             |\n| 5        | Brave Search | Good      | 2,000/month           | Easy             |\n| 6        | SearXNG      | Good      | Unlimited (self-host) | Hard             |\n| 7        | DuckDuckGo   | Basic     | Unlimited             | None             |\n\n---\n\n## 1. Smithery Exa (Recommended)\n\n[Smithery Exa](https://smithery.ai/server/exa) provides high-quality semantic search results through the MCP protocol. Smithery acts as a free proxy to the Exa search API.\n\n### Setup Steps\n\n1. **Create a Smithery Account**\n   - Go to [smithery.ai](https://smithery.ai)\n   - Sign up for a free account\n\n2. **Get Your API Key**\n   - Navigate to your account settings\n   - Copy your API key\n\n3. **Get Your Profile ID**\n   - Go to [smithery.ai/server/exa](https://smithery.ai/server/exa)\n   - Your profile ID is shown in the connection URL or settings\n\n4. **Configure Environment Variables**\n   ```bash\n   # Add to ~/.zshrc or ~/.bashrc\n   export SMITHERY_API_KEY=\"your_api_key_here\"\n   export SMITHERY_PROFILE=\"your_profile_id\"\n   ```\n\n### Pricing\n\n- **Free** through Smithery (Smithery proxies the Exa API at no cost)\n- Note: The official Exa API (exa.ai) is paid, but Smithery provides free access\n\n---\n\n## 2. Google Programmable Search Engine (PSE)\n\nGoogle PSE provides high-quality search results with a generous free tier.\n\n### Setup Steps\n\n#### Step 1: Create a Programmable Search Engine\n\n1. Go to [Google Programmable Search Engine Console](https://cse.google.com/all)\n2. Click **\"Add\"** to create a new search engine\n3. Configure:\n   - **Sites to search**: Enter `*` to search the entire web\n   - **Name**: Give it a descriptive name (e.g., \"Web Search\")\n4. Click **\"Create\"**\n5. Click **\"Control Panel\"** for your new search engine\n6. Copy the **Search engine ID (cx)** - looks like `017576662512468239146:omuauf_lfve`\n\n#### Step 2: Get an API Key\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. Create a new project or select an existing one\n3. Enable the **Custom Search API**:\n   - Go to **\"APIs \u0026 Services\"** \u003e **\"Library\"**\n   - Search for **\"Custom Search API\"**\n   - Click **\"Enable\"**\n4. Create credentials:\n   - Go to **\"APIs \u0026 Services\"** \u003e **\"Credentials\"**\n   - Click **\"Create Credentials\"** \u003e **\"API Key\"**\n   - Copy the API key\n\n#### Step 3: Configure Environment Variables\n\n```bash\n# Add to ~/.zshrc or ~/.bashrc\nexport GOOGLE_PSE_API_KEY=\"AIzaSy...\"        # Your API key\nexport GOOGLE_PSE_CX=\"017576662512468239146:omuauf_lfve\"  # Your Search engine ID\n```\n\n### Free Tier Limits\n\n- **10,000 queries/day** free\n- Max 10 results per query\n- After limit: $5 per 1,000 queries\n\n---\n\n## 3. Tavily\n\n[Tavily](https://tavily.com/) provides an easy-to-use web search API.\n\n### Setup Steps\n\n1. **Create an Account**\n   - Go to [tavily.com](https://tavily.com/)\n   - Sign up for an account\n\n2. **Get Your API Key**\n   - Navigate to your dashboard / API settings\n   - Copy your API key\n\n3. **Configure Environment Variable**\n   ```bash\n   # Add to ~/.zshrc or ~/.bashrc\n   export TAVILY_API_KEY=\"your_api_key_here\"\n   ```\n\n---\n\n## 4. Serper\n\n[Serper](https://serper.dev) provides Google search results through an easy-to-use API.\n\n### Setup Steps\n\n1. **Create an Account**\n   - Go to [serper.dev](https://serper.dev)\n   - Sign up for a free account\n\n2. **Get Your API Key**\n   - After signing in, your API key is displayed on the dashboard\n   - Copy the API key\n\n3. **Configure Environment Variable**\n   ```bash\n   # Add to ~/.zshrc or ~/.bashrc\n   export SERPER_API_KEY=\"your_api_key_here\"\n   ```\n\n### Free Tier\n\n- **2,500 free credits** on signup\n- 1 credit = 1 search query\n- Paid plans available for more usage\n\n---\n\n## 5. Brave Search\n\n[Brave Search API](https://brave.com/search/api/) provides privacy-focused search results.\n\n### Setup Steps\n\n1. **Create an Account**\n   - Go to [brave.com/search/api](https://brave.com/search/api/)\n   - Click **\"Get Started\"**\n\n2. **Subscribe to a Plan**\n   - Choose the **Free** plan (2,000 queries/month)\n   - Or a paid plan for more queries\n\n3. **Get Your API Key**\n   - Go to your API dashboard\n   - Copy your API key\n\n4. **Configure Environment Variable**\n   ```bash\n   # Add to ~/.zshrc or ~/.bashrc\n   export BRAVE_API_KEY=\"BSA...\"\n   ```\n\n### Free Tier\n\n- **2,000 queries/month** free\n- Rate limit: 1 query/second\n- Paid plans start at $5/month for 20,000 queries\n\n---\n\n## 6. SearXNG (Self-Hosted)\n\n[SearXNG](https://github.com/searxng/searxng) is a free, privacy-respecting metasearch engine you can self-host.\n\n### Setup Steps\n\n#### Option A: Use a Public Instance\n\nYou can use a public SearXNG instance, but availability and reliability vary.\n\n```bash\n# Example public instance (check if it's available)\nexport SEARXNG_URL=\"https://searx.be\"\n```\n\nFind public instances at [searx.space](https://searx.space/)\n\n#### Option B: Self-Host with Docker\n\n1. **Run SearXNG with Docker**\n\n   ```bash\n   docker run -d \\\n     --name searxng \\\n     -p 8080:8080 \\\n     -e SEARXNG_BASE_URL=http://localhost:8080 \\\n     searxng/searxng\n   ```\n\n2. **Configure Environment Variable**\n   ```bash\n   # Add to ~/.zshrc or ~/.bashrc\n   export SEARXNG_URL=\"http://localhost:8080\"\n   ```\n\n### Advantages\n\n- Unlimited searches\n- No API key required\n- Privacy-focused\n- Aggregates results from multiple search engines\n\n### Disadvantages\n\n- Requires self-hosting for reliability\n- Public instances may be slow or unavailable\n\n---\n\n## 7. DuckDuckGo (Default Fallback)\n\nDuckDuckGo is used automatically as the final fallback when no other providers are configured or available.\n\n### Configuration\n\n**No configuration required!** DuckDuckGo works out of the box.\n\n### Limitations\n\n- HTML scraping (less reliable than API)\n- Basic results compared to other providers\n- May be rate-limited with heavy use\n\n---\n\n## Quick Configuration Examples\n\n### Minimal Setup (Free, No API Keys)\n\nJust use DuckDuckGo fallback:\n\n```bash\nnpx droid-patch --websearch droid-search\ndroid-search  # Works immediately with DuckDuckGo\n```\n\n### Recommended Setup (Best Quality)\n\n```bash\n# Add to ~/.zshrc or ~/.bashrc\nexport SMITHERY_API_KEY=\"your_smithery_key\"\nexport SMITHERY_PROFILE=\"your_profile_id\"\n\n# Fallback: Google PSE\nexport GOOGLE_PSE_API_KEY=\"your_google_key\"\nexport GOOGLE_PSE_CX=\"your_search_engine_id\"\n```\n\n### Budget-Friendly Setup (All Free)\n\n```bash\n# Add to ~/.zshrc or ~/.bashrc\n\n# Option 1: Google PSE (10,000/day free)\nexport GOOGLE_PSE_API_KEY=\"your_google_key\"\nexport GOOGLE_PSE_CX=\"your_search_engine_id\"\n\n# Option 2: Tavily (free credits vary)\nexport TAVILY_API_KEY=\"your_tavily_key\"\n\n# Option 3: Serper (2,500 free credits)\nexport SERPER_API_KEY=\"your_serper_key\"\n\n# Option 4: Brave (2,000/month free)\nexport BRAVE_API_KEY=\"your_brave_key\"\n\n# DuckDuckGo is always available as final fallback\n```\n\n---\n\n## Debug Mode\n\nEnable detailed logging to troubleshoot search issues:\n\n```bash\nexport DROID_SEARCH_DEBUG=1\ndroid-search\n```\n\n---\n\n## Examples\n\n```bash\n# Quick start: create droid with websearch (external providers)\nnpx droid-patch --websearch droid-search\ndroid-search  # Just works!\n\n# Full-featured droid with external websearch\nnpx droid-patch --is-custom --skip-login --websearch --reasoning-effort droid-full\n\n# Native websearch via proxy plugin (requires jixoai/proxy)\nnpx droid-patch --is-custom --skip-login --websearch-proxy droid-native\n\n# Native websearch + reasoning effort\nnpx droid-patch --is-custom --skip-login --reasoning-effort --websearch-proxy droid-native-full\n\n# Standalone mode: websearch + mock non-LLM APIs\nnpx droid-patch --websearch --standalone droid-local\n\n# Privacy mode: disable telemetry\nnpx droid-patch --disable-telemetry droid-private\n\n# Full local setup: all features combined (external websearch)\nnpx droid-patch --is-custom --skip-login --websearch --standalone --disable-telemetry droid-full-local\n\n# Full local setup with native websearch\nnpx droid-patch --is-custom --skip-login --websearch-proxy --standalone --disable-telemetry droid-native-local\n\n# Websearch with custom backend\nnpx droid-patch --websearch --api-base=http://127.0.0.1:20002 droid-custom\n\n# Create a standalone patched binary in current directory\nnpx droid-patch --skip-login -o . my-droid\n./my-droid --version\n\n# List all aliases with version info\nnpx droid-patch list\n\n# Clean up\nnpx droid-patch remove droid-search              # remove single alias\nnpx droid-patch remove --flag=websearch          # remove all websearch aliases\nnpx droid-patch remove --flag=standalone         # remove all standalone aliases\nnpx droid-patch remove --patch-version=0.4.0     # remove by droid-patch version\nnpx droid-patch clear                            # remove everything\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingsword09%2Fdroid-patch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkingsword09%2Fdroid-patch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingsword09%2Fdroid-patch/lists"}