Paperclip as a Dev Assistant — the Mental Model

Understand the difference between research-style tasks and real code tasks, and how the claude-code adapter bridges Paperclip and your codebase.

Paperclip as a Dev Assistant — the Mental Model

What you'll learn

Understand why "dev assistant" tasks are fundamentally different from research tasks, and how the claude-code adapter turns Paperclip into something that can actually write, edit, and test code in your project.

Two kinds of Paperclip tasks

Every issue you create in Paperclip falls into one of two categories:

A research task says: "Summarise PostgreSQL RLS in 3 paragraphs."

A dev task says: "Add a GET /api/users/:id/profile endpoint in src/routes/users.ts that returns id, name, and email from the users table. Add a unit test in src/routes/users.test.ts."

The second task results in actual file changes you can git diff and review.

Why the claude-code adapter is different

The claude-code adapter is not just another LLM call. Under the hood it:

1. Launches a Claude Code process in your project directory (workingDir)
2. Gives Claude Code full tool access — Read, Write, Edit, Bash
3. Passes your issue description as the initial prompt
4. Captures everything Claude Code does (files read, files written, commands run)
5. Returns a structured result with the list of changed files and a summary

Issue description
      ↓
claude-code adapter
      ↓
  workingDir: ~/projects/my-app
      ↓
  Claude Code (has Read / Write / Edit / Bash tools)
      ↓
  Reads relevant files → makes changes → runs tests
      ↓
Result: { summary, changedFiles: [...], testsRan: true }

This is what makes Paperclip a dev assistant rather than a chatbot.

What Paperclip does NOT do (yet)

• It does not open a pull request automatically (you do that after reviewing)
• It does not push to git (all changes stay local until you commit)
• It does not have context of your entire git history by default (you can give it context in the issue description)
• It does not run your CI pipeline (you run it after reviewing the changes)

Think of Paperclip as an agent that works in your local checkout and hands the result back to you for review. You stay in control of what gets committed.

The dev assistant loop

You write an issue
      ↓
Heartbeat triggers the claude-code adapter
      ↓
Agent reads your files, makes changes, runs tests
      ↓
Issue marked resolved — result contains changed files + summary
      ↓
You run: git diff
      ↓
Accept → git add / commit / push
Reject → add a follow-up issue with corrections

This loop is the core of everything in this module.

Checkpoint ✓

• What is the key difference between a research task and a dev task in Paperclip?
• Which adapter handles real file changes?
• What tools does the claude-code adapter give to the agent?
• Who decides what gets committed to git — Paperclip, or you?