@axhub/acp

Experimental sibling project for validating an ACP + assistant-ui migration path.

This project uses assistant-ui for the chat runtime/UI and routes messages through ACP using the vendored @mcpc-tech/[email protected] baseline in lib/acp2aisdk/vendor/acp-ai-provider, with the Codex ACP provider fixed to @zed-industries/codex-acp.

Getting Started

Run from npm

npx -y @axhub/acp

Common options:

npx -y @axhub/acp --port 32124
npx -y @axhub/acp --cors-origin https://client.example.com

By default the CLI allows /api/* CORS requests from http://localhost:53817 and http://127.0.0.1:53817. --cors-origin replaces that default with another allowed browser Origin list. It also supports comma-separated origins and the aliases --cors and --cor.

External Integration

• HTTP Chat API documents POST /api/chat, including request parameters, stream chunks, response headers, a one-shot command example, and a live message listener example.
• Post Message API documents the browser postMessage bridge for iframe/opened-window context injection, host runtime configuration, UI-originated chat/attachments, thread snapshot queries, and lifecycle subscriptions.
• Host Integration documents generic iframe/child-window embedding, runtime API base configuration, context injection, runtime config injection, postMessage thread queries, HTTP chat execution, image generation, and React component reuse.
• Component And Runtime API documents package-level @axhub/acp/ui, @axhub/acp/runtime, @axhub/acp/server, @axhub/acp/react, and @axhub/acp/react/styles.css entries for component/runtime reuse, including embedded runtime API base configuration and Composer host extension props.
• Provider And Model Defaults lists built-in provider keys, startup commands, default modes, and fallback model options.

1. Configure an ACP Provider

Use a local provider login/session that the selected ACP command can access. Built-in provider recipes cover Codex, Claude, Gemini, OpenCode, Cursor, Qoder, CodeBuddy, and Reasonix. Qoder, CodeBuddy, Cursor, and Reasonix authentication or project configuration stays in the vendor CLI or inherited process environment. See Provider And Model Defaults for provider keys and default built-in model options.

2. Install Dependencies

npm install
# or
yarn install
# or
pnpm install

3. Run the Development Server

npm run dev
# or
yarn dev
# or
pnpm dev

Open http://localhost:32124 with your browser to see the result.

npm run dev uses the local source checkout and runs next dev. It allows the same default host-app origins on port 53817. For a local host app on another origin, pass the CORS option through npm:

npm run dev -- --cors-origin http://localhost:3000

For the common local host-app setup, use the host-aware development command. It binds the ACP UI dev server on 0.0.0.0, allows the usual host app origins on port 53817, and also lets Next.js dev assets/HMR accept those origins:

npm run dev:host

Development

You can start customizing the UI by modifying components in the components/assistant-ui/ directory.

To add more assistant-ui components:

npx assistant-ui add

Key Files

• app/assistant.tsx - Sets up the runtime provider
• app/api/chat/route.ts - ACP Codex chat endpoint with per-thread session reuse
• components/assistant-ui/thread.tsx - Compatibility re-export for the chat thread component
• components/assistant-ui/thread/ - Split thread UI modules for message list, composer, context chips, empty states, and message renderers
• public-api/ - Component/runtime/server facade entries emitted to dist/ for package-level external reuse

Regression

The recommended local regression flow is documented in docs/regression/test-coverage.zh-CN.md.

npm run regression

The pipeline runs provider official command smoke first, then provider registry/smoke tests, then the Codex API/CLI P0 regression, and finally the Midscene frontend smoke.

Provider Defaults

New conversations default each provider's engine mode to the closest trusted or vendor-default mode: Claude/Gemini bypassPermissions, Codex full-access, OpenCode build, Cursor agent, and Qoder/CodeBuddy default. Reasonix does not receive a default mode because its ACP implementation is driven by model and effort config options. A user-selected mode still overrides that default for the conversation/run when the provider exposes one.

Default ACP capability snapshots are generated from live ACP provider initSession responses:

npm run refresh:default-capabilities -- --providers=all
npm run refresh:default-capabilities -- --provider=codex

Use ACP_PROVIDER_COMMAND_OVERRIDES or per-provider ACP_<PROVIDER>_COMMAND environment variables when refreshing defaults for a new or local provider. Provider startup recipes live in lib/acp2aisdk/provider-registry.ts; each entry can define command, args, and optional fallbackCommands without touching the shared session runtime. Cross-platform PATH/PATHEXT enrichment and Windows npm shim wrapping are centralized in lib/acp2aisdk/provider-command.ts, so new providers should only need a startup recipe unless they have protocol differences.