{"id":35028704,"url":"https://github.com/kingsword09/droid-acp","last_synced_at":"2026-01-13T21:59:03.886Z","repository":{"id":330807987,"uuid":"1122672929","full_name":"kingsword09/droid-acp","owner":"kingsword09","description":"ACP adapter for Droid - Factory's AI coding agent.","archived":false,"fork":false,"pushed_at":"2025-12-28T06:24:18.000Z","size":227,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-30T13:47:43.311Z","etag":null,"topics":["acp","agentclientprotocol","droid"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/droid-acp","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","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-25T08:55:51.000Z","updated_at":"2025-12-30T01:44:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kingsword09/droid-acp","commit_stats":null,"previous_names":["kingsword09/droid-acp"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/kingsword09/droid-acp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingsword09%2Fdroid-acp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingsword09%2Fdroid-acp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingsword09%2Fdroid-acp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingsword09%2Fdroid-acp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kingsword09","download_url":"https://codeload.github.com/kingsword09/droid-acp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingsword09%2Fdroid-acp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28400397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["acp","agentclientprotocol","droid"],"created_at":"2025-12-27T06:44:30.832Z","updated_at":"2026-01-13T21:59:03.880Z","avatar_url":"https://github.com/kingsword09.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# droid-acp\n\nACP (Agent Client Protocol) adapter for [Droid](https://factory.ai) - Factory's AI coding agent.\n\nUse Droid from any [ACP-compatible](https://agentclientprotocol.com) clients such as [Zed](https://zed.dev)!\n\n## Features\n\n- Context @-mentions\n- Tool calls\n- TODO lists\n- Image prompts (e.g. paste screenshots in Zed)\n- Context / token usage indicator (`/context`)\n- Context compaction (`/compress`)\n- Multiple model support\n- Session modes (Spec, Manual, Auto Low/Medium/High)\n- Experimental: sessions/history (session list/load + `/sessions`)\n- Optional WebSearch proxy (Smithery Exa MCP / custom forward)\n\n## Installation\n\n```bash\nnpm install droid-acp\n```\n\n## Usage\n\n### Prerequisites\n\n1. Install Droid CLI from [Factory](https://factory.ai)\n2. (Recommended) Set your Factory API key for Factory-hosted features:\n   ```bash\n   export FACTORY_API_KEY=fk-...\n   ```\n\n\u003e If you only need WebSearch via the built-in proxy + Smithery Exa MCP, a valid Factory key is not required (droid-acp injects a dummy key into the spawned droid process to satisfy droid's local auth gate).\n\n### Running\n\n```bash\n# Default mode (stream-jsonrpc, supports custom models)\nnpx droid-acp\n\n# Set initial reasoning effort (passes through to `droid exec --reasoning-effort`)\nnpx droid-acp --reasoning-effort high\n\n# Enable experimental sessions/history helpers\nnpx droid-acp --experiment-sessions\n\n# Native ACP mode (lighter, but no custom model support)\nnpx droid-acp --acp\n```\n\n### With Zed Editor\n\nAdd to your Zed `settings.json`:\n\n```json\n{\n  \"agent_servers\": {\n    \"Droid\": {\n      \"type\": \"custom\",\n      \"command\": \"npx\",\n      \"args\": [\"droid-acp\"],\n      \"env\": {\n        \"FACTORY_API_KEY\": \"fk-your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n**Using native ACP mode (no custom model support):**\n\n```json\n{\n  \"agent_servers\": {\n    \"Droid Native\": {\n      \"type\": \"custom\",\n      \"command\": \"npx\",\n      \"args\": [\"droid-acp\", \"--acp\"],\n      \"env\": {\n        \"FACTORY_API_KEY\": \"fk-your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n**Using a custom droid binary (e.g., patched version):**\n\n```json\n{\n  \"agent_servers\": {\n    \"Droid Custom\": {\n      \"type\": \"custom\",\n      \"command\": \"npx\",\n      \"args\": [\"droid-acp\"],\n      \"env\": {\n        \"FACTORY_API_KEY\": \"fk-your-api-key-here\",\n        \"DROID_EXECUTABLE\": \"/path/to/custom/droid\"\n      }\n    }\n  }\n}\n```\n\n**Enable WebSearch proxy (Smithery Exa MCP):**\n\n```json\n{\n  \"agent_servers\": {\n    \"Droid WebSearch\": {\n      \"type\": \"custom\",\n      \"command\": \"npx\",\n      \"args\": [\"droid-acp\"],\n      \"env\": {\n        \"SMITHERY_API_KEY\": \"your_smithery_key\",\n        \"SMITHERY_PROFILE\": \"your_profile_id\"\n      }\n    }\n  }\n}\n```\n\n**Enable experimental sessions/history (`/sessions`, `session/list`, `session/load`):**\n\n```json\n{\n  \"agent_servers\": {\n    \"Droid Sessions (Experimental)\": {\n      \"type\": \"custom\",\n      \"command\": \"npx\",\n      \"args\": [\"droid-acp\", \"--experiment-sessions\"]\n    }\n  }\n}\n```\n\n### Modes\n\n| Command               | Mode           | Custom Models    | Description                   |\n| --------------------- | -------------- | ---------------- | ----------------------------- |\n| `npx droid-acp`       | stream-jsonrpc | ✅ Supported     | Default, recommended          |\n| `npx droid-acp --acp` | native ACP     | ❌ Not supported | Lighter, direct pipe to droid |\n\n\u003e **Note:** Native ACP mode (`--acp`) has a limitation in droid where custom models configured in `~/.factory/config.json` are not recognized. Use the default stream-jsonrpc mode if you need custom models.\n\n### Environment Variables\n\n- `FACTORY_API_KEY` - Your Factory API key (recommended for Factory-hosted features)\n- `DROID_EXECUTABLE` - Path to the droid binary (optional, defaults to `droid` in PATH)\n- `DROID_ACP_FACTORY_DIR` - Override Factory config dir (defaults to `~/.factory`)\n- `DROID_ACP_EXPERIMENT_SESSIONS` - Enable experimental sessions/history features (same as `--experiment-sessions`)\n- `DROID_ACP_REASONING_EFFORT` - Initial reasoning effort passed to `droid exec --reasoning-effort` (optional)\n- `DROID_DEBUG` - Enable adapter debug UI output (raw tool inputs, websearch proxy status, raw events)\n\n- `DROID_ACP_WEBSEARCH` - Enable local WebSearch proxy. When unset, the proxy auto-enables if `SMITHERY_API_KEY`+`SMITHERY_PROFILE` or `DROID_ACP_WEBSEARCH_FORWARD_URL` is set (set to `0` to force disable).\n- `DROID_ACP_WEBSEARCH_FORWARD_URL` - Optional forward target for websearch (base URL or full URL)\n- `DROID_ACP_WEBSEARCH_FORWARD_MODE` - (Legacy) Forward mode for `DROID_ACP_WEBSEARCH_FORWARD_URL` (`http` or `mcp`, default: `http`). Prefer `mcp:` prefix in the forward URL.\n- `DROID_ACP_WEBSEARCH_UPSTREAM_URL` - Optional upstream Factory API base URL (default: `FACTORY_API_BASE_URL_OVERRIDE` or `https://api.factory.ai`)\n- `DROID_ACP_WEBSEARCH_HOST` - Optional proxy bind host (default: `127.0.0.1`)\n- `DROID_ACP_WEBSEARCH_PORT` - Optional proxy bind port (default: auto-assign an available port)\n\n- `SMITHERY_API_KEY` - Optional (recommended) Smithery Exa MCP API key (enables high-quality websearch)\n- `SMITHERY_PROFILE` - Optional Smithery Exa MCP profile id\n\n### WebSearch Proxy (optional)\n\nEnable the built-in proxy to intercept `POST /api/tools/exa/search` and serve results from Smithery Exa MCP (recommended):\n\n```bash\nexport SMITHERY_API_KEY=\"your_smithery_key\"\nexport SMITHERY_PROFILE=\"your_profile_id\"\nnpx droid-acp\n```\n\nTo debug proxy wiring (shows `proxyBaseUrl` and a `/health` link in the ACP UI):\n\n```bash\nDROID_DEBUG=1 npx droid-acp\n```\n\nTo forward WebSearch to your own HTTP handler instead:\n\n```bash\nDROID_ACP_WEBSEARCH_FORWARD_URL=\"http://127.0.0.1:20002\" \\\nnpx droid-acp\n```\n\nTo forward WebSearch to an MCP endpoint (JSON-RPC `tools/call`), set:\n\n```bash\nDROID_ACP_WEBSEARCH_FORWARD_URL=\"mcp:http://127.0.0.1:20002\" \\\nnpx droid-acp\n```\n\nNotes:\n\n- The proxy exposes `GET /health` on `proxyBaseUrl` (handy for troubleshooting).\n- When the WebSearch proxy is enabled, droid-acp injects a dummy `FACTORY_API_KEY` into the spawned droid process if none is set, so WebSearch requests can reach the proxy even without Factory login.\n- The proxy forces `Accept-Encoding: identity` upstream and strips `content-encoding`/`content-length` when proxying to avoid Brotli decompression errors in some client setups.\n\n## Sessions (History / Resume)\n\nThis is an **experimental** feature. Enable with `npx droid-acp --experiment-sessions` (or set `DROID_ACP_EXPERIMENT_SESSIONS=1`).\n\ndroid-acp supports ACP `session/list`, `session/load` and `session/resume`, plus an in-thread workaround command:\n\n- `/sessions`: list/load sessions from local Droid history (useful because some clients don’t yet persist external ACP agent history)\n- `session/load`: replays the full conversation history back to the client\n- `session/resume`: resumes without replay (faster, but the client won’t get old messages from the agent)\n\n### `/sessions` usage\n\n- `/sessions` (or `/sessions list`) - list sessions for the current `cwd` (numbered)\n- `/sessions all` - list recent sessions across all `cwd`s (prefers the current `cwd`)\n- `/sessions \u003c#\u003e` - load by index from the last list\n- `/sessions load \u003c#\u003e` - load by index from the last list\n- `/sessions load \u003csession_id_prefix\u003e` - load by id prefix (from the last list)\n- `/sessions load \u003csession_id\u003e` - load by full session id\n- `/sessions load last` - load the most recent session (from the last list)\n\nWhen loading:\n\n- droid-acp first tries to resume Droid via `--session-id` (fast path).\n- If resume fails, it replays history from disk and automatically appends a transcript to your _next_ message so Droid can continue without a Factory login.\n\nNotes:\n\n- History is replayed from Droid’s local session store under `~/.factory/sessions` (override with `DROID_ACP_FACTORY_DIR`).\n- For a cleaner UI, history replay filters out system reminders, embedded `\u003ccontext ...\u003e` blocks, and tool calls/tool results.\n- Session titles are sanitized (some Droid sessions store titles like `\u003ccontext ref=\"session_history\"\u003e ...`).\n- Session IDs are displayed as plain text for easy copy/paste.\n- Times shown in `/sessions` are displayed as `YYYY-MM-DD HH:mm:ss` in your local timezone.\n- Native ACP mode (`--acp`) does not support these helpers.\n\n## Context / Token Usage (`/context`)\n\nSome ACP clients don’t expose Droid’s built-in token usage indicator UI. Use `/context` to print the **last model call** context indicator (matching Droid’s TUI). droid-acp reads this from `~/.factory/logs/droid-log-single.log`.\n\nNotes:\n\n- `Total` is computed as `inputTokens + outputTokens + cacheReadTokens` (matching Droid’s internal “lastTokenUsage”).\n- The context % matches Droid’s TUI: `max=200000` for Anthropic models, otherwise `max=300000`.\n\n## Compress / Compact (`/compress`, `/compact`)\n\nDroid’s built-in `/compress` is TUI-only. In stream-jsonrpc mode, droid-acp implements an equivalent workflow:\n\n1. Ask Droid to generate a short `\u003csummary\u003e...\u003c/summary\u003e` of the current conversation\n2. Restart the underlying Droid exec session\n3. Inject the summary as embedded context on your next message (so the new session continues with a smaller context)\n\nNotes:\n\n- This is an adapter-level feature; it is **not available** in native ACP mode (`npx droid-acp --acp`).\n- The generated summary is captured silently (it is not shown in the chat transcript) and will be appended to your next message as embedded context.\n- You can pass optional instructions: `/compress focus on current code changes and next steps`.\n\n## Session Modes\n\n| Mode        | Description                                 | Droid autonomy level |\n| ----------- | ------------------------------------------- | -------------------- |\n| Spec        | Plan-only (read-only)                       | `spec`               |\n| Auto Off    | Prompts before edits/commands (per-tool)    | `normal`             |\n| Auto Low    | Low-risk operations (basic file operations) | `auto-low`           |\n| Auto Medium | Development operations                      | `auto-medium`        |\n| Auto High   | Production operations (dangerous)           | `auto-high`          |\n\n## Available Models\n\n- Claude Opus 4.5 (default)\n- Claude Sonnet 4.5\n- Claude Haiku 4.5\n- GPT-5.1\n- GPT-5.1-Codex\n- GPT-5.1-Codex-Max\n- GPT-5.2\n- Gemini 3 Pro\n- Droid Core (GLM-4.6)\n\n## Project Structure\n\n- `src/acp/agent/` - ACP `Agent` implementation (sessions, prompts, slash commands)\n- `src/acp/notifications/` - Droid notifications → ACP updates\n- `src/acp/permissions/` - Permission prompts, diffs, and auto-approval logic\n- `src/acp/session/` - Session attach/restart helpers\n- `src/websearch-proxy.ts` - Optional local WebSearch proxy\n- `src/acp-agent.ts` - Public entry point (re-exports `DroidAcpAgent`, `runAcp` from `src/acp/`)\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Dev mode (watch)\nnpm run dev\n\n# Lint\nnpm run lint\n\n# Format\nnpm run format\n\n# Check (lint + format)\nnpm run check\n```\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingsword09%2Fdroid-acp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkingsword09%2Fdroid-acp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingsword09%2Fdroid-acp/lists"}