Paperclip Plugin
Give every Paperclip agent deep structural codebase knowledge — module maps, dependency graphs, semantic search, and health analysis.
Why this is different
Most AI agents work blind — they grep files, guess at structure, and miss architectural context. SourcePrep's Paperclip plugin gives agents a structural brain: they understand which modules exist, how files connect, what the blast radius of a change is, and what the codebase health looks like — before writing a single line of code.
This is a novel workflow: epistemic-first agent orchestration. Instead of agents discovering codebase structure through trial and error, SourcePrep pre-computes it and serves it on demand. The result is agents that make better decisions, faster, with fewer hallucinations.
How It Works
The SourcePrep plugin registers 5 tools that any Paperclip agent can call during their runs. These tools proxy to your local SourcePrep daemon, which has already indexed your codebase with embeddings, a structural graph, and epistemic analysis.
Installation
Prerequisites
- SourcePrep Desktop App — Download from prep.dev. The daemon must be running at
localhost:8400. - A SourcePrep project — Add your repo:
prep add /path/to/your/project - A Paperclip instance — Running at
localhost:3100or your deployment URL.
Install the Plugin
Or install from a local path during development:
Configure
In Paperclip Settings → Plugins → SourcePrep:
| Setting | Default | Description |
|---|---|---|
| daemon_url | http://127.0.0.1:8400 | SourcePrep daemon URL |
| project_id | (auto-detected) | SourcePrep project ID. Auto-detects if you have one project. |
| auto_context | true | Automatically attach SourcePrep context to new issues |
Tools Reference
Once installed, all Paperclip agents can use these tools during their runs. Tools are namespaced as prep:* and appear in the agent's tool palette.
| Tool | What It Does |
|---|---|
| prep:context | Structural overview — modules, hub files, atlas. Call at the start of every task. |
| prep:search | Semantic code search with structural trace expansion. Finds code by meaning, not just keywords. |
| prep:impact | Blast radius analysis — what depends on a file, what it depends on. Use before modifying code. |
| prep:audit | Codebase health findings — tech debt, architecture issues, dead code, naming inconsistencies. |
| prep:observe | Save cross-session observations. Agents build persistent memory about the codebase. |
Dashboard Extensions
The plugin adds UI components directly into the Paperclip dashboard:
- Codebase Health Widget — Dashboard widget showing readiness score, role count, research runs, and archived items at a glance.
- Knowledge Scope Tab — On each agent's detail page, shows which files SourcePrep has assigned to that agent's role scope.
- Issue Context Tab — On each issue's detail page, shows SourcePrep structural context for issues created from audit findings.
- Settings Page — Connection status, available tools reference, and plugin configuration.
The Agent Workflow
Here's what happens when a Paperclip agent works on a task with SourcePrep installed:
Why This Is Novel
Traditional AI agents approach codebases like a developer on their first day — grepping files, reading README.md, hoping they stumble onto the right architecture. SourcePrep inverts this:
- Pre-computed structure — The code graph, module clusters, and hub files are already indexed. Agents don't discover structure; they query it.
- Epistemic confidence — SourcePrep knows which parts of the codebase are well-understood (high enrichment) vs. opaque. Agents can be cautious where the index is thin.
- Role-scoped context — A backend agent sees backend-relevant files. A frontend agent sees frontend files. SourcePrep's RoleVector system projects the atlas differently per role.
- Impact-aware changes — Before modifying a file, agents know exactly what depends on it. This prevents the cascade of broken imports that plagues autonomous coding agents.
Source Code
The plugin source is at packages/paperclip-plugin in the SourcePrep repository. It's MIT-licensed.