Use Acp

use-acp

React hooks for Agent Client Protocol (ACP) over WebSockets.

Features

• WebSocket connection management
• Reactive state management
• Notifications timeline for ACP events
• Permission request/response handling
• Full TypeScript support

Installation

npm install use-acp
# or
pnpm add use-acp

Usage

Basic Usage

import { useAcpClient } from 'use-acp';

function App() {
  const {
    connect,
    disconnect,
    connectionState,
    notifications,
    pendingPermission,
    resolvePermission,
  } = useAcpClient({
    wsUrl: 'ws://localhost:8080',
    autoConnect: true
  });

  return (
    
      Status: {connectionState.status}
      
        {connectionState.status === 'connected' ? 'Disconnect' : 'Connect'}
      

      {pendingPermission && (
        
          Permission Request
          {pendingPermission.options.map((option) => (
             resolvePermission(option)}>
              {option.name}
            
          ))}
        
      )}

      Notifications: {notifications.length}
      
        {notifications.map((notification) => (
          {JSON.stringify(notification)}
        ))}
      
    
  );
}

API Reference

useAcpClient({ wsUrl, autoConnect?, reconnectAttempts?, reconnectDelay? })

Returns: { connect(), disconnect(), connectionState, notifications, clearNotifications(), pendingPermission, resolvePermission(), rejectPermission(), agent }

Utils

import { groupNotifications, mergeToolCalls } from 'use-acp';

// Group notifications by their type
// This helps when displaying notifications in a timeline
const groupedNotifications = groupNotifications(notifications);

// Merge tool calls with the same toolCallId
const mergedToolCalls = mergeToolCalls(toolCalls);

Development

pnpm install
pnpm test      # run tests
pnpm build     # build library
pnpm dev       # run demo, http://localhost:5173

Example Agents

# Gemini ACP
npx -y stdio-to-ws "npx @google/gemini-cli --experimental-acp"

# Claude Code ACP
npx -y stdio-to-ws "npx @zed-industries/claude-code-acp"

# Codex ACP
npx -y stdio-to-ws "npx @zed-industries/codex-acp"

License

Apache 2.0

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: marimo-team
• Source: marimo-team/use-acp
• License: Apache-2.0
• Homepage: https://marimo-team.github.io/use-acp/

Install and usage instructions live in the source repository linked above.