typescript

Qoder ACP TypeScript Demo

This demo is a small TypeScript ACP client that launches a real qodercli --acp process and talks to it over stdio newline-delimited JSON. It does not mock qodercli.

It is intended as a customer-facing reference for integrating qodercli into an ACP-capable editor or host application.

What This Demo Shows

• Start qodercli in ACP mode.
• Create a client-side ACP connection with @agentclientprotocol/sdk.
• Initialize ACP capabilities.
• Create a qodercli session.
• Send a prompt and stream session/update events.
• Handle tool permission requests.
• Handle AskUserQuestion through ACP form elicitation.
• Optionally expose client-side file read/write RPCs to qodercli.

Prerequisites

• Node.js 20 or newer.
• A working qodercli command in PATH, or a path to a qodercli JS/package entry.
• Existing qodercli login state, or a QODER_PERSONAL_ACCESS_TOKEN environment variable.

Quick Start

cd typescript
npm install
npm run dev -- "Explain this repository in one short paragraph."

By default, the demo runs:

qodercli --acp

To use a local qodercli checkout or a custom executable, pass --qodercli:

npm run dev -- --qodercli /path/to/qodercli/packages/cli "/help"

If the --qodercli value points to a directory or a .js, .mjs, or .cjs file, the demo runs it with Node:

node <path> --acp

Otherwise, it runs the value directly:

<path> --acp

Common Commands

Run against the default qodercli command:

npm run dev -- "/help"

Run against a local qodercli source checkout:

npm run dev -- \
  --qodercli /path/to/qodercli/packages/cli \
  --cwd /path/to/workspace \
  "/help"

Pass additional qodercli arguments:

npm run dev -- \
  --agent-arg --tools \
  --agent-arg AskUserQuestion \
  "Ask me which UI style this integration should use."

Auto-approve permission prompts:

npm run dev -- --allow-all "Inspect this project."

Disable client-side file-system RPCs:

npm run dev -- --no-client-fs "Summarize this workspace."

AskUserQuestion

The demo advertises ACP form elicitation by default:

clientCapabilities: {
  elicitation: {
    form: {
    }
  }
}

When qodercli invokes AskUserQuestion, qodercli converts it to unstable_createElicitation, and this demo renders the form in the terminal.

To make this easy to test, restrict qodercli to the AskUserQuestion tool:

npm run dev -- \
  --agent-arg --tools \
  --agent-arg AskUserQuestion \
  "Use AskUserQuestion to ask me two questions: one single-select UI style question and one multi-select output preference question."

For a multi-select question, enter comma-separated option numbers:

1,2

To verify capability gating, disable elicitation:

npm run dev -- \
  --no-elicitation \
  --agent-arg --tools \
  --agent-arg AskUserQuestion \
  "Use AskUserQuestion to ask me one question."

Project Layout

src/
  main.ts                # Process orchestration and ACP lifecycle.
  acp/                   # ACP capabilities, session creation, auth retry.
  cli/                   # Demo CLI argument parsing.
  client/                # ACP Client implementation and host-side callbacks.
  qodercli/              # qodercli --acp launch and cleanup helpers.
docs/
  ask-user-question.md   # Focused AskUserQuestion testing notes.
  integration-guide.md   # How to map this demo into a real host app.
  troubleshooting.md     # Common setup and protocol issues.
examples/
  prompts.md             # Copyable prompts and command examples.

The key integration points are:

• src/qodercli/spawn.ts: where the host launches the real qodercli ACP process.
• src/acp/session.ts: where the host advertises ACP capabilities and creates a session.
• src/client/demo-client.ts: where qodercli calls back into host features such as permission prompts, form elicitation, and client file-system RPCs.

Build

npm run check
npm run build
npm start -- "/help"