paperclipai / paperclip

Code

How paperclipai/paperclip is laid out, and where to start for common changes.

There is no import map for this report yet.

Where to start reading

Repository root
Repository root
Likely public API
Likely public API
Likely start-up file
Likely start-up file
Suggested starting pointAI
Suggested starting pointAI

Find files for a task

AI

Add a New MCP Server Integration

Create a new MCP server package directory following the pattern packages/[name]-mcp-server/src/
Register the MCP server in the adapter integration layer
Add tests in config.test.ts following the pattern

Add a New Protocol Action

Create a new file in packages/paperclip-runner/src/protocol-actions/ following naming pattern
Define action type and handler conforming to canonical operations
Register action in control plane dispatch logic
Add conformance test to ensure action meets capability standards

Add a New Database Schema

Create schema definition file in packages/db/src/schema/
Create corresponding SQL migration in packages/db/src/migrations/
Export schema from schema module for runtime type safety
Add integration test validating schema constraints

Change the public API

Trace runtime behavior

Add or update tests

Change build or automation

RepoPilot lists up to 500 files, so a file missing here may still exist.

Files marked “likely” are guessed from their names.

Code quality and hotspots

Largest source files

Branch points906 per file on average
Code issues1 error, 80 warnings
Largest file6,580 lines
Hotspot load9 high-risk files

Static checks on the 15 largest source files.

Tests, CI and tooling

CIGitHub Actions23 workflows
Tests3,872 test filesJest/Vitest · Pytest · 0.74 test files per source file (file count, not coverage)
Dependency updatesNo config detected

Test folders: .github/scripts/tests · cli/src/__tests__ · .agents/skills/garden-inbox/scripts

Hotspots

packages/adapter-utils/src/acpx-engine/execute.ts84 commits in 180 days · 918 branch points
packages/paperclip-runner/src/control-plane/durable-prp-control-plane.ts38 commits in 180 days · 800 branch points
packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts25 commits in 180 days · 411 branch points
packages/paperclip-runner/src/cli/acpx-runtime-sidecar.ts21 commits in 180 days · 291 branch points
packages/paperclip-runner/src/contracts/native-execution.ts21 commits in 180 days · 249 branch points
packages/paperclip-runner/src/live/live-session.ts18 commits in 180 days · 629 branch points
packages/paperclip-runner/src/drivers/acpx/codex-acpx-driver.ts17 commits in 180 days · 452 branch points
packages/db/src/backup-lib.ts9 commits in 180 days · 184 branch points

Files that change often and branch heavily, highest first. Branch points count if, loop, case, catch, ternary, && and || in the file.