paperclip-plugins/plugin-agent-inbox-config/README.md

@paperclipai/plugin-agent-inbox-config

Plugin for configuring per-agent inbox-lite filter settings via UI.

What It Does

This plugin provides a UI for configuring which issues appear in each agent's inbox via the inbox-lite endpoint. Instead of using query parameters or code changes, users can use a simple interface with toggles to control:

• Issue statuses - Which issue statuses (todo, in_progress, blocked, etc.) should appear in the inbox
• Project filter - Optionally limit to issues from a specific project
• Goal filter - Optionally limit to issues linked to a specific goal
• Search query - Optional text search to filter issues by title, description, or comments
• Include backlog - Toggle to include/exclude backlog issues

UI Slots

The plugin registers three UI slots:

1. Sidebar entry (agent-inbox-config-sidebar) - Quick access to select an agent and navigate to their inbox config
2. Page (agent-inbox-config-page) - Overview page showing all agents with their current inbox configuration summaries
3. Agent detail tab (agent-inbox-tab) - Full configuration form on each agent's detail page

Configuration

Instance Config Schema

The plugin supports the following instance-level configuration:

{
  "defaultStatuses": "todo,in_progress,blocked",
  "includeBacklog": false,
  "maxIssuesPerAgent": 50
}

• defaultStatuses: Comma-separated list of statuses to use as default for new agents
• includeBacklog: Whether to include backlog issues by default
• maxIssuesPerAgent: Maximum number of issues returned per agent inbox (1-500)

Per-Agent Config Storage

Each agent's inbox configuration is stored in two places:

1. Plugin state - Under the key agentInboxConfigs scoped to instance. This allows the plugin to quickly read/write configs without querying the database.

2. Agent runtimeConfig - The config is also persisted to the agent's runtimeConfig.inboxConfig field for durability and to be available even if the plugin is uninstalled.

Data Handlers

The plugin registers the following data handlers for UI components:

• agents - Lists all agents in a company
• getAgentInboxConfig - Gets the inbox config for a specific agent
• listAgentInboxConfigs - Lists all agent inbox configs

Action Handlers

The plugin registers the following action handlers:

• setAgentInboxConfig - Sets or updates an agent's inbox configuration
• resetAgentInboxConfig - Resets an agent's config to defaults

Events

The plugin subscribes to:

• agent.created - Automatically sets default inbox config for new agents

Capabilities Required

[
  "agents.read",
  "projects.read", 
  "goals.read",
  "issues.read",
  "plugin.state.read",
  "plugin.state.write",
  "ui.sidebar.register",
  "ui.page.register"
]

Local Install (Dev)

From the repo root, build the plugin and install it:

pnpm --filter @paperclipai/plugin-agent-inbox-config build
pnpm paperclipai plugin install ./packages/plugins/plugin-agent-inbox-config

Usage

1. Navigate to an agent's detail page in Paperclip
2. Click the "Inbox Settings" tab
3. Configure the filters:
   • Check/uncheck issue statuses
   • Select a project filter (optional)
   • Select a goal filter (optional)
   • Enter a search query (optional)
   • Toggle include backlog
4. Click "Save Configuration"

The agent's inbox-lite endpoint will now return issues matching these filters.