System of Oversight and Monitoring for Agents — Paperclip integration.
The nervous system for your AI agent company. Real-time behavioral monitoring, pressure tracking, and directive control — inside Paperclip.
This plugin brings SOMA Core into Paperclip, giving you a visual control plane for all your agents.
SOMA monitors every tool call, LLM request, and error from your agents. It computes behavioral vitals (uncertainty, drift, error rate), calculates aggregate pressure, and escalates when things go wrong.
| Feature | Description |
|---|---|
| Dashboard Widget | Real-time pressure bars, budget health, worst-level indicator |
Full Page (/soma) |
Agent grid with vitals, Control Panel (quarantine/release/reset), budget management |
| Settings Page | Editable thresholds, budget limits, behavior toggles, file paths, danger zone |
| Sidebar | Compact status indicator with link to full page |
| Agent Detail Tab | SOMA vitals on individual agent pages |
| Toast Notifications | Alerts when agents change levels |
| Tooltips | Explanations on every vital, level, and action |
Settings → Plugins → Examples → "SOMA Core — Agent Monitor" → Install
curl -X POST http://localhost:4444/api/plugins/install \
-H "Content-Type: application/json" \
-d '{"packageName":"/path/to/SOMA-Paperclip","isLocalPath":true}'- SOMA Core —
pip install soma-core - SOMA Daemon running —
python3 -m soma.daemon - Claude Code hook installed (SOMA sets this up automatically)
Agent tool call
↓
Claude Code PostToolUse hook → ~/.soma/inbox/*.json
↓
SOMA daemon (polls every 1s) → engine.record_action()
↓
engine.export_state() → ~/.soma/state.json
↓
Paperclip plugin (polls every 2-3s) → UI updates
Commands flow in reverse:
Plugin UI button click → ~/.soma/commands/*.json → daemon → engine
No servers. No APIs. Just files.
| Action | What It Does |
|---|---|
| Quarantine | Blocks all LLM calls for an agent. Immediate. |
| Release | Removes quarantine. Agent resumes on next heartbeat. |
| Reset Baseline | Clears behavioral baseline. Use after prompt/tool changes. |
| Replenish Budget | Adds tokens to SOMA budget. Quick buttons + custom input. |
| Set Thresholds | Change escalation pressure values (CAUTION/DEGRADE/QUARANTINE/RESTART). |
| Set Budget Limits | Change token and cost limits. |
| Export State | Download current SOMA state as JSON. |
| QUARANTINE ALL | Emergency kill switch — blocks all agents. |
| Level | Pressure | What Happens |
|---|---|---|
| HEALTHY | < 0.25 | Normal operation |
| CAUTION | 0.25 - 0.50 | Context trimmed 20%. Warning in UI. |
| DEGRADE | 0.50 - 0.75 | Context trimmed 50%. Expensive tools blocked. |
| QUARANTINE | 0.75 - 0.90 | All LLM calls blocked. Manual release required. |
| RESTART | > 0.90 | Complete agent reset needed. |
| SAFE_MODE | Budget = 0 | Everything stops. |
Thresholds are editable from the Settings page.
src/
manifest.ts — Plugin manifest (5 UI slots, 8 capabilities)
worker.ts — Reads state.json, writes commands, data/action handlers
ui/
index.tsx — 5 React components (Widget, Page, Sidebar, Settings, AgentTab)
# In the Paperclip monorepo
pnpm --filter @soma-core/paperclip-plugin build
pnpm --filter @soma-core/paperclip-plugin dev # watch modeComing soon — the plugin is in active development.
This plugin is under active development. Current version works with SOMA Core v0.2.0+.
What works:
- Real-time agent monitoring (via daemon + file IPC)
- Quarantine/Release/Reset commands
- Budget management
- Settings with editable thresholds
- Toast notifications and tooltips
Coming soon:
- Pressure history sparklines
- Trust graph visualization
- Agent comparison view
- Persistent settings (currently reset on daemon restart)
- Direct integration with Paperclip cost events
See SOMA Core CHANGELOG for details.
- SOMA Core — The engine. Python library + CLI + dashboard.
- Paperclip — AI company orchestration platform.
MIT
Tim Hunt (@tr00x)
Built with Claude Code. Monitored by SOMA.