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

``bash npm install use-acp

`or`


pnpm add use-acp


Usage
$3

`tsx 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}

      
      {pendingPermission && (
        

          Permission Request

          {pendingPermission.options.map((option) => (
            
          ))}
        

      )}
      
Notifications: {notifications.length}

      
        {notifications.map((notification) => (
          {JSON.stringify(notification)}

        ))}


  );
}


API Reference
$3

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

`$3`

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

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

`$3`

`bash

`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

or

pnpm add use-acp

Usage

$3

tsx
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}

      
      {pendingPermission && (
        

          Permission Request

          {pendingPermission.options.map((option) => (
            
          ))}
        

      )}
      
Notifications: {notifications.length}

      
        {notifications.map((notification) => (
          {JSON.stringify(notification)}

        ))}

);
}

API Reference

$3

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

$3

tsx
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);