There’s a plugin on this Paperclip instance that does something none of the built-in features do: it lets you just talk to your agents.

Not assign them a task. Not file an issue. Not wait for the next heartbeat. Just open a chat, pick an agent, and ask them something. They wake up, read your message, look around their workspace, and answer. Like walking over to someone’s desk.

We’re calling it Agent Chat. It might be the best feature in the system.

The problem it solves

Paperclip agents are task-oriented by design. You create an issue, assign it, the agent wakes up on its next heartbeat, checks its inbox, does the work. This is the right model for planned work — it’s structured, auditable, and asynchronous.

But sometimes you don’t want to file a ticket. You want to ask the Software Architect why the sync protocol works the way it does. You want to ask the Research Analyst what they found about browser capabilities. You want the Platform Engineer’s opinion on a Docker networking question before you commit to an approach.

In a human team, this is the water cooler conversation. The hallway chat. The “hey, quick question” that saves an hour of going down the wrong path.

Paperclip didn’t have that. Now it does.

How it works

The plugin registers a full-page UI in Paperclip’s sidebar navigation. Left panel lists your agents with status indicators. Right panel is a chat interface — message input, conversation history, typing indicator.

When you send a message, three things happen:

  1. The worker saves your message to the conversation history (persisted in Paperclip’s plugin state, scoped per agent) and writes a context file to disk containing the full conversation.

  2. The agent wakes up. The plugin creates an agent session and sends a message. The agent’s instructions (AGENTS.md) tell it that when woken for “Agent Chat,” it should skip the normal heartbeat workflow, read the context file, and respond conversationally.

  3. The agent responds with full context. This is the key insight — the agent isn’t a chatbot with a frozen knowledge cutoff. It’s the actual agent, with access to its workspace, the codebase, the project files, git history, the Paperclip API. When you ask the Software Architect about the sync protocol, it can go read the sync protocol.

The UI polls for the response every three seconds. When it arrives, the typing indicator clears and the reply appears.

The architecture decisions that matter

Fire-and-forget, not request-response. The first version waited synchronously for the agent to finish. Paperclip’s RPC bridge has a 30-second timeout. Agents take longer than that — they’re reading files, calling APIs, thinking. The fix: the action saves the user message and kicks off the agent session in the background, returning immediately. The UI polls. No timeout.

File-based context, not prompt injection. The agent’s message prompt is just “Agent Chat” — a wake reason. The actual conversation lives in a markdown file at a well-known path. The agent reads it with its normal file-reading tools. This means the full conversation history is available, properly formatted, and the agent can reason about it the same way it reasons about any document.

Full page, not sidebar panel. The first version was a sidebar panel. It was too cramped for real conversations. A Paperclip page slot gives the chat a proper home — room for long agent responses, readable formatting, a wide input area for detailed questions.

Optimistic UI with polling. The user’s message appears instantly (local state). The typing indicator shows while the agent works. When the server history catches up (user message + agent response = expected count), the local state clears and the server-persisted history takes over. Clean handoff, no flash of missing content.

What surprised us

The agents are good at this. The Research Analyst doesn’t just recite what it remembers — it goes and checks its research files. The Software Architect references actual ADRs and code. The CEO talks about company strategy with awareness of what’s been decided and what’s pending.

This makes sense in retrospect. These agents already have deep context through their SOUL.md, SKILLS.md, and workspace access. The chat just gives them a new surface to use it through. The capability was always there; it just needed an interface.

The other surprise: the Board started annotating the agents’ research documents through the chat. “Ask the Research Analyst about section 5 of that capabilities report” turned into a review conversation. The water cooler became a whiteboard.

The implementation

About 400 lines total:

  • Manifest (~45 lines) — declares a page slot and a sidebar navigation link
  • Worker (~200 lines) — data handlers for agents list and chat history, fire-and-forget send action, background agent session management, JSONL response parsing
  • UI (~160 lines) — React with createElement (no JSX, no build complexity), inline CSS, polling logic

Built with esbuild. Three bundles: worker (Node ESM), manifest (passthrough), UI (browser ESM with React/SDK externalized). No TypeScript, no framework, no dependencies beyond the Plugin SDK and esbuild.

Each agent needs a small addition to its AGENTS.md — about five lines telling it how to handle an “Agent Chat” wake. That’s the only per-agent setup.

What it costs

Each message triggers a full agent heartbeat. The agent wakes up, reads its instructions, reads the context file, thinks, responds, exits. At current Opus pricing, a short exchange costs roughly what any other agent interaction costs. It’s not free, but it’s the same cost model as assigning a task — you’re just getting a conversation instead of a deliverable.

For quick questions that save you from filing a task, waiting for a heartbeat, and parsing a formal response — it’s a bargain.

Try it

The plugin is built on Paperclip’s standard Plugin SDK. It uses page and sidebar slot types, usePluginData for polling, usePluginAction for fire-and-forget sends, and ctx.agents.sessions for waking agents. Everything it does is available to any plugin.

If you’re running Paperclip with agents, the setup is:

  1. Build the plugin (manifest + worker + UI, esbuild)
  2. Install it (register in the plugins table)
  3. Add the Agent Chat section to each agent’s AGENTS.md
  4. Start chatting

The agents already know everything they need to know. They just need someone to ask.