npm package: @sergioconejo/paperclip-plugin-agent-chat
Description: Paperclip plugin that adds a quick chat sidebar panel for real-time conversations with agent employees
Author: sergioconejo
Latest version: 0.5.0

# @sergioconejo/paperclip-plugin-agent-chat

Quick chat plugin for [Paperclip](https://github.com/paperclipai/paperclip) — talk to your AI agent employees in real time without creating formal issues.

## What it does

Adds a chat interface to Paperclip so you can have quick conversations with any agent in your company. Ask questions, give instructions, request status updates — all without leaving the board.

**Sidebar panel** — compact chat widget always accessible from the navigation sidebar, with agent selector dropdown.

**Agent detail tab** — full-size "Chat" tab on every agent's detail page for longer conversations.

**Streaming responses** — messages stream in real time as the agent thinks and responds.

**Persistent history** — conversations are saved per-agent and survive page reloads (configurable max messages).

## Install

In the Paperclip UI, go to **Settings > Plugins > Install Plugin** and enter:

```
@sergioconejo/paperclip-plugin-agent-chat
```

Or via API:

```sh
curl -X POST http://localhost:3100/api/plugins/install \
  -H "Content-Type: application/json" \
  -d '{"packageName": "@sergioconejo/paperclip-plugin-agent-chat"}'
```

## Configuration

After installation, the plugin settings page exposes:

| Setting | Default | Description |
|---------|---------|-------------|
| Max Chat History Per Agent | 50 | Maximum messages retained per agent conversation |

## Features

- **Agent selector** with live status indicators (idle, running, paused, error, terminated)
- **Real-time streaming** via SSE — see the agent's response as it types
- **Session continuity** — reuses the same agent session across messages for coherent multi-turn conversations
- **Enter to send**, Shift+Enter for newline
- **Clear history** per agent
- **Unavailable agent detection** — shows a message when an agent is paused or terminated
- **Activity logging** — every chat interaction is recorded in Paperclip's activity log
- **Dark theme** — styled with Paperclip's OKLCH design tokens

## Capabilities used

This plugin declares the following Paperclip capabilities:

- `agents.read` — list and read agent metadata
- `agents.invoke` — wake agents
- `agent.sessions.create/list/send/close` — two-way chat sessions
- `plugin.state.read/write` — persist chat history
- `activity.log.write` — audit trail
- `events.subscribe` — react to agent status changes
- `companies.read` — company context
- `ui.sidebar.register` — sidebar link and panel
- `ui.detailTab.register` — agent detail chat tab
- `ui.action.register` — bridge actions

## Development

```sh
# Clone and install
git clone https://github.com/sergioconejo/paperclip-plugin-agent-chat
cd paperclip-plugin-agent-chat
npm install

# Build
npm run build

# Typecheck
npm run typecheck

# Install locally in a running Paperclip instance
curl -X POST http://localhost:3100/api/plugins/install \
  -H "Content-Type: application/json" \
  -d '{"packageName": "'$(pwd)'", "isLocalPath": true}'
```

## Project structure

```
src/
  manifest.ts   — Plugin manifest (capabilities, UI slots, config schema)
  worker.ts     — Backend: data handlers, actions, streaming, state persistence
  ui/index.tsx  — Frontend: sidebar panel, agent tab, chat components
  index.ts      — Package entrypoint
scripts/
  build-ui.mjs  — esbuild bundler for UI components
```

## Built with

- [Paperclip Plugin SDK](https://www.npmjs.com/package/@paperclipai/plugin-sdk) — plugin framework
- React 19 — UI components
- TypeScript — type safety
- esbuild — UI bundling

## License

MIT