@paperclipai/plugin-chat

March 10, 2026 · View on GitHub

Multi-adapter AI chat plugin for Paperclip. Provides a conversational interface to Paperclip agents with thread management, slash commands, and real-time streaming.

How It Works

The plugin creates a chat UI inside the Paperclip plugin page slot. When a user sends a message, the plugin:

Creates a thread (persisted in plugin state)
Finds a compatible agent via ctx.agents.list() (prefers "Chat Assistant", falls back to role "general")
Creates or resumes an agent session via ctx.agents.sessions
Streams the agent's response back to the UI

All LLM access goes through Paperclip's agent session system. The plugin does not talk to models directly — it talks to agents that talk to models. See Plugin vs Core Analysis for the implications of this architecture.

Prerequisites

A running Paperclip instance
At least one agent with adapterType: "claude_local" (or another supported adapter)
The plugin installed and enabled in Settings > Plugins

Build

npm run build

Produces dist/worker.js (server-side) and dist/ui/index.js (browser bundle).

Docker deployment

docker cp dist/ui/index.js paperclip-plugin-chat-server-1:/app/packages/plugins/plugin-chat/dist/ui/index.js

Hard refresh the browser after deploying — the server caches bundles with ETags.

Features

Chat UI

Welcome screen with quick action chips (check issues, review goals, plan work, agent status)
Threaded conversations with sidebar navigation
Rich markdown rendering (tables, code blocks, lists, links, blockquotes)
Collapsible tool usage display ("Used 3 tools Bash x3")
Auto-generated thread titles from first message
Inline thread rename (double-click) and delete (with confirmation)

Slash Commands

Type / in the input to access built-in commands:

Command	Action
`/tasks`	List active tasks
`/dashboard`	Workspace dashboard
`/agents`	Agent status overview
`/create`	Create a new task
`/projects`	List projects
`/costs`	Cost breakdown
`/activity`	Recent activity
`/blocked`	Blocked tasks
`/plan`	Plan and break down work
`/handoff`	Hand off work to an agent

Streaming

The plugin supports real-time streaming via SSE (ctx.streams). During agent execution, users see live text output with a blinking cursor, tool activity indicators, and a stop button.

Configuration

Navigate to Settings > Plugins > Chat (gear icon):

Setting	Description
Default Adapter	Adapter type for new threads (`claude_local`, `codex_local`, `opencode_local`)
System Prompt Override	Custom text appended to chat sessions

Plugin Capabilities

Capability	Purpose
`ui.page.register`	Full chat page at `/:prefix/plugins/:pluginId`
`ui.sidebar.register`	Sidebar entry point
`agent.sessions.*`	Create and message agent sessions
`agents.read`	Discover available agents/adapters
`plugin.state.*`	Thread and message persistence
`activity.log.write`	Activity logging

Architecture

Browser                          Server
-------                          ------
ChatPage (React)
  |
  |-- usePluginData("threads")    --> Worker: getData("threads")
  |-- usePluginData("messages")   --> Worker: getData("messages")
  |-- usePluginAction("sendMessage") --> Worker: sendMessage action
  |                                      |
  |                                      |--> ctx.agents.sessions.create()
  |                                      |--> ctx.agents.sessions.sendMessage()
  |                                      |      |
  |                                      |      +--> Agent adapter --> CLI process
  |                                      |      |
  |                                      |      +--> onEvent callbacks
  |                                      |
  |                                      |--> ctx.streams.emit() (SSE)
  |
  |-- usePluginStream("chat:threadId") <-- SSE events (text, thinking, tool, done)

Known Limitations

No direct LLM access — requires a pre-configured agent; can't create agents or select models
Agent sessions are task-oriented — no way to distinguish "answer this question" from "execute this task"
No design system — UI is built with inline styles and CSS variable fallbacks
No deep linking — thread state is lost on page refresh
No toast/dialog — errors go to console only
Host page chrome — breadcrumbs and back button can't be hidden

For the full analysis, see Plugin vs Core: Chat Feature Analysis.

Testing

See the Testing Guide for setup instructions, a full test checklist, and troubleshooting steps.

Document	Description
Plugin vs Core Analysis	Why chat as a plugin has fundamental limitations
Testing Guide	Test checklist and setup for testers
Core Integration Spec	Recommendation for building chat as a core page
Streaming Implementation	SSE streaming architecture notes
Stream Bus Gap	Stream bus wiring analysis