Full Local Setup for Dev Mode

Install all prerequisites, clone both Paperclip and your target project, configure environment variables, and verify the full stack is running.

Full Local Setup for Dev Mode

What you'll learn

Install every prerequisite, run Paperclip locally alongside your target project, and verify the agent can actually reach your codebase before you write a single task.

Prerequisites checklist

Before starting, confirm these are installed:

# Node.js 20+
node --version   # must be >= 20.0.0

# pnpm (Paperclip's package manager)
pnpm --version   # must be >= 8.0.0
# Install: npm install -g pnpm

# Git
git --version

# Claude Code CLI (needed by the claude-code adapter)
claude --version
# Install: npm install -g @anthropic-ai/claude-code

# Verify Claude is authenticated
claude auth status
# If not: claude auth login

Why Claude Code CLI? The claude-code adapter shells out to the claude binary in your PATH. It is not an API call — it runs the full Claude Code agent locally, which gives it real file access.

Step 1 — Clone and run Paperclip

# Clone Paperclip
git clone https://github.com/paperclipai/paperclip.git
cd paperclip

# Install dependencies
pnpm install

# Copy the environment template
cp .env.example .env

Edit .env — minimum required values for dev mode:

# .env
DATABASE_URL=           # Leave blank — PGlite is used in dev mode automatically
ANTHROPIC_API_KEY=sk-ant-...   # Your Anthropic API key (claude-code adapter needs this)

# Optional but useful
PAPERCLIP_LOG_LEVEL=debug      # See everything happening in the heartbeat
HEARTBEAT_INTERVAL_MS=30000    # 30s between ticks in dev (default is 60s)

Start the full stack:

pnpm dev

You should see:

[migrations] 8 tables ready
[server] Paperclip API listening on http://localhost:3100
[web] Vite dev server running at http://localhost:5173
[scheduler] Heartbeat tick scheduled every 60s

Step 2 — Locate your target project

Your "target project" is the codebase you want agents to work on. It must be a directory on the same machine running Paperclip.

# Example: a Node.js/Express project
ls ~/projects/my-api/
# src/  package.json  tsconfig.json  .env  ...

# Make note of the absolute path — you'll need it in Step 4
echo ~/projects/my-api
# /Users/you/projects/my-api

The target project does NOT need to be running. The agent reads and writes files directly — it doesn't need a live server.

Step 3 — Initialise git in your target project (if not already)

The agent will make file changes. Git lets you review them cleanly with git diff.

cd ~/projects/my-api

# If not already a git repo:
git init
git add .
git commit -m "initial commit before paperclip agent work"

# Create a dedicated branch for agent work
git checkout -b paperclip-agent

Working on a dedicated branch keeps agent changes isolated from your main branch until you're ready to merge.

Step 4 — Configure the claude-code adapter in Paperclip

Open apps/server/src/adapters/claude-code/config.ts (or the equivalent in your version — check src/adapters/):

// apps/server/src/adapters/claude-code/config.ts
export const claudeCodeAdapterConfig = {
  // Absolute path to the project the agent will work in
  workingDir: process.env.AGENT_WORKING_DIR ?? '',

  // Maximum time (ms) before the adapter times out a run
  timeoutMs: 300_000, // 5 minutes — increase for large tasks

  // Whether to run in dry-run mode (agent reads files but won't write)
  dryRun: process.env.AGENT_DRY_RUN === 'true',
};

Add AGENT_WORKING_DIR to your .env:

# .env
AGENT_WORKING_DIR=/Users/you/projects/my-api

Restart Paperclip after editing .env:

# Ctrl+C to stop pnpm dev, then:
pnpm dev

Step 5 — Verify agent access

Use the dry-run endpoint to confirm the adapter can see your project without making any changes:

curl -X POST http://localhost:3100/api/adapters/claude-code/test \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "List the top-level files and directories in this project.",
    "dry_run": true
  }'

Expected response:

{
  "status": "ok",
  "working_dir": "/Users/you/projects/my-api",
  "output": "The project contains: src/, package.json, tsconfig.json, README.md, .env ...",
  "files_read": ["package.json", "tsconfig.json"],
  "files_written": []
}

If you see "status": "error" with working_dir not set — check that AGENT_WORKING_DIR is in .env and you restarted pnpm dev.

Full setup checklist

[ ] Node 20+, pnpm, Git, Claude Code CLI all installed
[ ] claude auth status shows authenticated
[ ] pnpm dev starts without errors — server on 3100, web on 5173
[ ] Target project has an initial git commit on a paperclip-agent branch
[ ] AGENT_WORKING_DIR set in .env pointing to the target project
[ ] Dry-run test returns "status": "ok" with files listed

Checkpoint ✓

Why does the claude-code adapter require the Claude Code CLI instead of a direct API call?
What does AGENT_DRY_RUN=true protect you from?
Why is it recommended to work on a separate paperclip-agent git branch?
What does the /api/adapters/claude-code/test endpoint verify?