Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/kingsword09/droid-acp

ACP adapter for Droid - Factory's AI coding agent.
https://github.com/kingsword09/droid-acp

acp agentclientprotocol droid

Last synced: 5 months ago
JSON representation

ACP adapter for Droid - Factory's AI coding agent.

Awesome Lists containing this project

README 

          
# droid-acp



ACP (Agent Client Protocol) adapter for [Droid](https://factory.ai) - Factory's AI coding agent.



Use Droid from any [ACP-compatible](https://agentclientprotocol.com) clients such as [Zed](https://zed.dev)!



## Features



- Context @-mentions

- Tool calls

- TODO lists

- Image prompts (e.g. paste screenshots in Zed)

- Context / token usage indicator (`/context`)

- Context compaction (`/compress`)

- Multiple model support

- Session modes (Spec, Manual, Auto Low/Medium/High)

- Experimental: sessions/history (session list/load + `/sessions`)

- Optional WebSearch proxy (Smithery Exa MCP / custom forward)



## Installation



```bash

npm install droid-acp

```



## Usage



### Prerequisites



1. Install Droid CLI from [Factory](https://factory.ai)

2. (Recommended) Set your Factory API key for Factory-hosted features:

   ```bash

   export FACTORY_API_KEY=fk-...

   ```



> 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).



### Running



```bash

# Default mode (stream-jsonrpc, supports custom models)

npx droid-acp



# Set initial reasoning effort (passes through to `droid exec --reasoning-effort`)

npx droid-acp --reasoning-effort high



# Enable experimental sessions/history helpers

npx droid-acp --experiment-sessions



# Native ACP mode (lighter, but no custom model support)

npx droid-acp --acp

```



### With Zed Editor



Add to your Zed `settings.json`:



```json

{

  "agent_servers": {

    "Droid": {

      "type": "custom",

      "command": "npx",

      "args": ["droid-acp"],

      "env": {

        "FACTORY_API_KEY": "fk-your-api-key-here"

      }

    }

  }

}

```



**Using native ACP mode (no custom model support):**



```json

{

  "agent_servers": {

    "Droid Native": {

      "type": "custom",

      "command": "npx",

      "args": ["droid-acp", "--acp"],

      "env": {

        "FACTORY_API_KEY": "fk-your-api-key-here"

      }

    }

  }

}

```



**Using a custom droid binary (e.g., patched version):**



```json

{

  "agent_servers": {

    "Droid Custom": {

      "type": "custom",

      "command": "npx",

      "args": ["droid-acp"],

      "env": {

        "FACTORY_API_KEY": "fk-your-api-key-here",

        "DROID_EXECUTABLE": "/path/to/custom/droid"

      }

    }

  }

}

```



**Enable WebSearch proxy (Smithery Exa MCP):**



```json

{

  "agent_servers": {

    "Droid WebSearch": {

      "type": "custom",

      "command": "npx",

      "args": ["droid-acp"],

      "env": {

        "SMITHERY_API_KEY": "your_smithery_key",

        "SMITHERY_PROFILE": "your_profile_id"

      }

    }

  }

}

```



**Enable experimental sessions/history (`/sessions`, `session/list`, `session/load`):**



```json

{

  "agent_servers": {

    "Droid Sessions (Experimental)": {

      "type": "custom",

      "command": "npx",

      "args": ["droid-acp", "--experiment-sessions"]

    }

  }

}

```



### Modes



| Command               | Mode           | Custom Models    | Description                   |

| --------------------- | -------------- | ---------------- | ----------------------------- |

| `npx droid-acp`       | stream-jsonrpc | ✅ Supported     | Default, recommended          |

| `npx droid-acp --acp` | native ACP     | ❌ Not supported | Lighter, direct pipe to droid |



> **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.



### Environment Variables



- `FACTORY_API_KEY` - Your Factory API key (recommended for Factory-hosted features)

- `DROID_EXECUTABLE` - Path to the droid binary (optional, defaults to `droid` in PATH)

- `DROID_ACP_FACTORY_DIR` - Override Factory config dir (defaults to `~/.factory`)

- `DROID_ACP_EXPERIMENT_SESSIONS` - Enable experimental sessions/history features (same as `--experiment-sessions`)

- `DROID_ACP_REASONING_EFFORT` - Initial reasoning effort passed to `droid exec --reasoning-effort` (optional)

- `DROID_DEBUG` - Enable adapter debug UI output (raw tool inputs, websearch proxy status, raw events)



- `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).

- `DROID_ACP_WEBSEARCH_FORWARD_URL` - Optional forward target for websearch (base URL or full URL)

- `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.

- `DROID_ACP_WEBSEARCH_UPSTREAM_URL` - Optional upstream Factory API base URL (default: `FACTORY_API_BASE_URL_OVERRIDE` or `https://api.factory.ai`)

- `DROID_ACP_WEBSEARCH_HOST` - Optional proxy bind host (default: `127.0.0.1`)

- `DROID_ACP_WEBSEARCH_PORT` - Optional proxy bind port (default: auto-assign an available port)



- `SMITHERY_API_KEY` - Optional (recommended) Smithery Exa MCP API key (enables high-quality websearch)

- `SMITHERY_PROFILE` - Optional Smithery Exa MCP profile id



### WebSearch Proxy (optional)



Enable the built-in proxy to intercept `POST /api/tools/exa/search` and serve results from Smithery Exa MCP (recommended):



```bash

export SMITHERY_API_KEY="your_smithery_key"

export SMITHERY_PROFILE="your_profile_id"

npx droid-acp

```



To debug proxy wiring (shows `proxyBaseUrl` and a `/health` link in the ACP UI):



```bash

DROID_DEBUG=1 npx droid-acp

```



To forward WebSearch to your own HTTP handler instead:



```bash

DROID_ACP_WEBSEARCH_FORWARD_URL="http://127.0.0.1:20002" \

npx droid-acp

```



To forward WebSearch to an MCP endpoint (JSON-RPC `tools/call`), set:



```bash

DROID_ACP_WEBSEARCH_FORWARD_URL="mcp:http://127.0.0.1:20002" \

npx droid-acp

```



Notes:



- The proxy exposes `GET /health` on `proxyBaseUrl` (handy for troubleshooting).

- 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.

- The proxy forces `Accept-Encoding: identity` upstream and strips `content-encoding`/`content-length` when proxying to avoid Brotli decompression errors in some client setups.



## Sessions (History / Resume)



This is an **experimental** feature. Enable with `npx droid-acp --experiment-sessions` (or set `DROID_ACP_EXPERIMENT_SESSIONS=1`).



droid-acp supports ACP `session/list`, `session/load` and `session/resume`, plus an in-thread workaround command:



- `/sessions`: list/load sessions from local Droid history (useful because some clients don’t yet persist external ACP agent history)

- `session/load`: replays the full conversation history back to the client

- `session/resume`: resumes without replay (faster, but the client won’t get old messages from the agent)



### `/sessions` usage



- `/sessions` (or `/sessions list`) - list sessions for the current `cwd` (numbered)

- `/sessions all` - list recent sessions across all `cwd`s (prefers the current `cwd`)

- `/sessions <#>` - load by index from the last list

- `/sessions load <#>` - load by index from the last list

- `/sessions load ` - load by id prefix (from the last list)

- `/sessions load ` - load by full session id

- `/sessions load last` - load the most recent session (from the last list)



When loading:



- droid-acp first tries to resume Droid via `--session-id` (fast path).

- 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.



Notes:



- History is replayed from Droid’s local session store under `~/.factory/sessions` (override with `DROID_ACP_FACTORY_DIR`).

- For a cleaner UI, history replay filters out system reminders, embedded `` blocks, and tool calls/tool results.

- Session titles are sanitized (some Droid sessions store titles like ` ...`).

- Session IDs are displayed as plain text for easy copy/paste.

- Times shown in `/sessions` are displayed as `YYYY-MM-DD HH:mm:ss` in your local timezone.

- Native ACP mode (`--acp`) does not support these helpers.



## Context / Token Usage (`/context`)



Some 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`.



Notes:



- `Total` is computed as `inputTokens + outputTokens + cacheReadTokens` (matching Droid’s internal “lastTokenUsage”).

- The context % matches Droid’s TUI: `max=200000` for Anthropic models, otherwise `max=300000`.



## Compress / Compact (`/compress`, `/compact`)



Droid’s built-in `/compress` is TUI-only. In stream-jsonrpc mode, droid-acp implements an equivalent workflow:



1. Ask Droid to generate a short `...` of the current conversation

2. Restart the underlying Droid exec session

3. Inject the summary as embedded context on your next message (so the new session continues with a smaller context)



Notes:



- This is an adapter-level feature; it is **not available** in native ACP mode (`npx droid-acp --acp`).

- 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.

- You can pass optional instructions: `/compress focus on current code changes and next steps`.



## Session Modes



| Mode        | Description                                 | Droid autonomy level |

| ----------- | ------------------------------------------- | -------------------- |

| Spec        | Plan-only (read-only)                       | `spec`               |

| Auto Off    | Prompts before edits/commands (per-tool)    | `normal`             |

| Auto Low    | Low-risk operations (basic file operations) | `auto-low`           |

| Auto Medium | Development operations                      | `auto-medium`        |

| Auto High   | Production operations (dangerous)           | `auto-high`          |



## Available Models



- Claude Opus 4.5 (default)

- Claude Sonnet 4.5

- Claude Haiku 4.5

- GPT-5.1

- GPT-5.1-Codex

- GPT-5.1-Codex-Max

- GPT-5.2

- Gemini 3 Pro

- Droid Core (GLM-4.6)



## Project Structure



- `src/acp/agent/` - ACP `Agent` implementation (sessions, prompts, slash commands)

- `src/acp/notifications/` - Droid notifications → ACP updates

- `src/acp/permissions/` - Permission prompts, diffs, and auto-approval logic

- `src/acp/session/` - Session attach/restart helpers

- `src/websearch-proxy.ts` - Optional local WebSearch proxy

- `src/acp-agent.ts` - Public entry point (re-exports `DroidAcpAgent`, `runAcp` from `src/acp/`)



## Development



```bash

# Install dependencies

npm install



# Build

npm run build



# Dev mode (watch)

npm run dev



# Lint

npm run lint



# Format

npm run format



# Check (lint + format)

npm run check

```



## License



Apache-2.0