@tickernelz/paperclip-pro 2026.926.1 → 2026.926.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +109 -453
- package/dist/index.js +142 -17
- package/dist/index.js.map +4 -4
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,515 +1,171 @@
|
|
|
1
|
-
<p align="center">
|
|
2
|
-
<img src="https://raw.githubusercontent.com/paperclipai/paperclip/185366d797dcf9fceeba036889b27bfddf783d56/doc/assets/banner.jpg" alt="Paperclip Pro" width="720" />
|
|
3
|
-
</p>
|
|
4
|
-
|
|
5
|
-
<p align="center">
|
|
6
|
-
<a href="#quickstart"><strong>Quickstart</strong></a> ·
|
|
7
|
-
<a href="docs/fork/OPERATIONS.md"><strong>Operations</strong></a> ·
|
|
8
|
-
<a href="https://github.com/tickernelz/paperclip-pro"><strong>This fork</strong></a> ·
|
|
9
|
-
<a href="https://github.com/paperclipai/paperclip"><strong>Upstream</strong></a> ·
|
|
10
|
-
<a href="https://docs.paperclip.ing"><strong>Upstream docs</strong></a> ·
|
|
11
|
-
<a href="https://paperclip.ing"><strong>Upstream website</strong></a>
|
|
12
|
-
</p>
|
|
13
|
-
|
|
14
|
-
<p align="center">
|
|
15
|
-
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
|
|
16
|
-
<img src="https://img.shields.io/badge/fork-hard%20fork-orange" alt="Hard fork" />
|
|
17
|
-
<img src="https://img.shields.io/badge/upstream-paperclipai%2Fpaperclip%407b7c4d417-lightgrey" alt="Upstream base" />
|
|
18
|
-
</p>
|
|
19
|
-
|
|
20
|
-
<br/>
|
|
21
|
-
|
|
22
|
-
<div align="center">
|
|
23
|
-
<video src="https://github.com/user-attachments/assets/773bdfb2-6d1e-4e30-8c5f-3487d5b70c8f" width="600" controls></video>
|
|
24
|
-
</div>
|
|
25
|
-
|
|
26
|
-
<br/>
|
|
27
|
-
|
|
28
1
|
# Paperclip Pro
|
|
29
2
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
It is maintained independently at [`tickernelz/paperclip-pro`](https://github.com/tickernelz/paperclip-pro). All 32 workspace packages are renamed under the `@tickernelz/paperclip-pro` scope, the CLI binary is `paperclip-pro`, and instance state lives under `~/.paperclip-pro` instead of `~/.paperclip` — so this fork installs and runs beside an upstream instance instead of replacing it.
|
|
3
|
+
Paperclip Pro is a self-hosted control plane that runs a team of AI coding agents as an organisation: an org chart, tasks and approvals, scheduled heartbeats, budgets, and an audit trail, with a Node.js server, an embedded PostgreSQL, and a React board.
|
|
33
4
|
|
|
34
|
-
|
|
5
|
+
It is a **hard fork** of [`paperclipai/paperclip`](https://github.com/paperclipai/paperclip), branched at upstream commit `7b7c4d417` and since diverged. It is not an upstream release and is not endorsed by Paperclip Labs, Inc. All workspace packages are renamed under the `@tickernelz/paperclip-pro` scope, the CLI binary is `paperclip-pro`, and instance state lives under `~/.paperclip-pro` instead of `~/.paperclip`, so this fork installs and runs beside an upstream instance instead of replacing it.
|
|
35
6
|
|
|
36
|
-
|
|
7
|
+
Report bugs in [this repository](https://github.com/tickernelz/paperclip-pro/issues), never in the upstream tracker.
|
|
37
8
|
|
|
38
|
-
|
|
9
|
+
## What this fork adds
|
|
39
10
|
|
|
40
|
-
|
|
|
11
|
+
| Addition | Where |
|
|
41
12
|
| --- | --- |
|
|
42
|
-
| **
|
|
43
|
-
|
|
|
44
|
-
| **
|
|
45
|
-
| **
|
|
46
|
-
| **
|
|
47
|
-
| **
|
|
48
|
-
|
|
|
49
|
-
|
|
|
50
|
-
| **
|
|
13
|
+
| **Built-in `omp_local` adapter.** Runs the local Oh My Pi (OMP) coding-agent CLI as a Paperclip agent runtime: server execution, CLI event formatting, model discovery through `omp models --json`, a UI transcript parser, and a startup-complete signal the run-concurrency gate reads. | [`packages/adapters/omp-local`](packages/adapters/omp-local), registered in `server/src/adapters/registry.ts` |
|
|
14
|
+
| **Server-hosted Paperclip MCP.** `POST /api/mcp/paperclip` exposes the Paperclip API as MCP tools generated from the OpenAPI document. 675 operations generate tools: the `core` toolset is the default and lists 61 tools (~36 KB, ~9k tokens of context), `core,extended` lists 442 (~210 KB), and an agent with company authority sees 719 (~344 KB). Toolsets are selected per run with `?toolsets=`. Adapters that can mount an MCP client get the endpoint; the others get a REST fallback prompt instead of tool names that do not exist. | `server/src/routes/paperclip-mcp.ts`, `packages/mcp-server/src/generated/api-tools.json` |
|
|
15
|
+
| **Role-based agent authority.** An agent actor carries work authority (`work:read`, `work:issues`, `work:routines`); an agent whose role is `ceo` additionally carries company authority over agents, projects, settings, members and approvals. Every generated MCP tool is tagged `agent` or `board` and gated on the same model. | `packages/shared/src/agent-authority.ts`, `server/src/services/authorization.ts` |
|
|
16
|
+
| **Per-task model and thinking overrides.** A task can run on a different model or thinking level than its assignee's stored configuration, validated against the adapter's own published config schema, with optional inheritance to new or existing subtasks. No new column and no migration: it reuses `issues.assignee_adapter_overrides`. | `server/src/services/issue-run-model-override.ts`, `server/src/services/issue-model-override-inheritance.ts` |
|
|
17
|
+
| **Batch model/thinking changes.** Select agents in the Agents list and change the model-selection fields their adapters share. The batch is atomic: one invalid value rejects the call with 422 and writes nothing. Up to 100 agents per call. | `POST /api/agents/batch/adapter-config`, `.../preview` |
|
|
18
|
+
| **Local CLI run concurrency caps.** Local adapters are memory-hungry while booting; the queued-run claim point caps total local runs and simultaneous startups, and shows held-back runs as "Waiting to start". | `server/src/services/heartbeat.ts` |
|
|
19
|
+
| **Mobile composer dock and bottom-sheet pickers.** The task and agent composers dock above the on-screen keyboard and reserve their own height, the bottom nav auto-hides while typing, and the model/thinking, agent and New Task pickers open as bottom sheets instead of being covered by the keyboard. | `ui/src/components/task-chat/composer-dock.ts`, `ui/src/components/ui/mobile-picker-sheet.tsx`, `ui/src/hooks/useMobileViewportInsets.ts` |
|
|
20
|
+
| **`service restart --drain` and a live-run guard.** Restart and stop refuse while agent runs are executing unless you drain or force. A per-instance `service.env` the CLI never overwrites carries operator environment across unit rewrites. | `cli/src/commands/service.ts`, `cli/src/services/service-manager.ts` |
|
|
21
|
+
| **Isolated home.** `PAPERCLIP_HOME` defaults to `~/.paperclip-pro`; config, embedded PostgreSQL, logs, storage and backups all resolve under `~/.paperclip-pro/instances/<id>`. | `packages/shared/src/home-paths.ts` |
|
|
22
|
+
| **One lean CI and a tag-triggered release.** A single `ci.yml` (policy, typecheck, build, runner, sharded tests, E2E, mobile shell) plus a documentation-only fast lane that runs the static gates and the docs-reading suites, and a `release.yml` that publishes the whole package set to npm when a `v*` tag is pushed. | `.github/workflows/` |
|
|
51
23
|
|
|
52
24
|
Operators: read [`docs/fork/OPERATIONS.md`](docs/fork/OPERATIONS.md).
|
|
53
25
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
Open-source orchestration for teams of AI agents.
|
|
57
|
-
|
|
58
|
-
**If OpenClaw is an _employee_, Paperclip is the _company_.**
|
|
59
|
-
|
|
60
|
-
Paperclip is a Node.js server and React UI that orchestrates a team of AI agents to run a business. Bring your own agents, assign goals, and track work and costs from one dashboard.
|
|
61
|
-
|
|
62
|
-
It looks like a task manager. Under the hood: org charts, budgets, governance, goal alignment, and agent coordination.
|
|
63
|
-
|
|
64
|
-
**Manage business goals, not pull requests.**
|
|
65
|
-
|
|
66
|
-
| | Step | Example |
|
|
67
|
-
| ------ | --------------- | ------------------------------------------------------------------ |
|
|
68
|
-
| **01** | Define the goal | _"Build the #1 AI note-taking app to $1M MRR."_ |
|
|
69
|
-
| **02** | Hire the team | CEO, CTO, engineers, designers, marketers — any bot, any provider. |
|
|
70
|
-
| **03** | Approve and run | Review strategy. Set budgets. Hit go. Monitor from the dashboard. |
|
|
71
|
-
|
|
72
|
-
<br/>
|
|
73
|
-
|
|
74
|
-
<div align="center">
|
|
75
|
-
<table>
|
|
76
|
-
<tr>
|
|
77
|
-
<td align="center"><strong>Works<br/>with</strong></td>
|
|
78
|
-
<td align="center"><img src="https://raw.githubusercontent.com/paperclipai/paperclip/185366d797dcf9fceeba036889b27bfddf783d56/doc/assets/logos/openclaw.svg" width="32" alt="OpenClaw" /><br/><sub>OpenClaw</sub></td>
|
|
79
|
-
<td align="center"><img src="https://raw.githubusercontent.com/paperclipai/paperclip/185366d797dcf9fceeba036889b27bfddf783d56/doc/assets/logos/claude.svg" width="32" alt="Claude" /><br/><sub>Claude Code</sub></td>
|
|
80
|
-
<td align="center"><img src="https://raw.githubusercontent.com/paperclipai/paperclip/185366d797dcf9fceeba036889b27bfddf783d56/doc/assets/logos/codex.svg" width="32" alt="Codex" /><br/><sub>Codex</sub></td>
|
|
81
|
-
<td align="center"><img src="https://raw.githubusercontent.com/paperclipai/paperclip/185366d797dcf9fceeba036889b27bfddf783d56/doc/assets/logos/cursor.svg" width="32" alt="Cursor" /><br/><sub>Cursor</sub></td>
|
|
82
|
-
<td align="center"><img src="https://raw.githubusercontent.com/paperclipai/paperclip/185366d797dcf9fceeba036889b27bfddf783d56/doc/assets/logos/bash.svg" width="32" alt="Bash" /><br/><sub>Bash</sub></td>
|
|
83
|
-
<td align="center"><img src="https://raw.githubusercontent.com/paperclipai/paperclip/185366d797dcf9fceeba036889b27bfddf783d56/doc/assets/logos/http.svg" width="32" alt="HTTP" /><br/><sub>HTTP</sub></td>
|
|
84
|
-
</tr>
|
|
85
|
-
</table>
|
|
86
|
-
|
|
87
|
-
<em>If it can receive a heartbeat, it's hired.</em>
|
|
88
|
-
|
|
89
|
-
</div>
|
|
90
|
-
|
|
91
|
-
<br/>
|
|
92
|
-
|
|
93
|
-
## Paperclip is right for you if
|
|
94
|
-
|
|
95
|
-
- ✅ You want to build **autonomous AI organizations**
|
|
96
|
-
- ✅ You **coordinate many different agents** (OpenClaw, Codex, Claude, Cursor) toward a common goal
|
|
97
|
-
- ✅ You have **20 simultaneous Claude Code terminals** open and lose track of what everyone is doing
|
|
98
|
-
- ✅ You want agents running **autonomously 24/7**, but still want to audit work and chime in when needed
|
|
99
|
-
- ✅ You want to **monitor costs** and enforce budgets
|
|
100
|
-
- ✅ You want a process for managing agents that **feels like using a task manager**
|
|
101
|
-
- ✅ You want to manage your autonomous businesses **from your phone**
|
|
102
|
-
|
|
103
|
-
<br/>
|
|
104
|
-
|
|
105
|
-
## The four pillars
|
|
106
|
-
|
|
107
|
-
Four things have to work for an organization of AI agents to actually produce: the tasks, the org, the training, and the infrastructure. Paperclip is built around exactly those four pillars.
|
|
108
|
-
|
|
109
|
-
<picture>
|
|
110
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/paperclipai/paperclip/1ec33ffd8b597f7e36aac3e2fbb4665b8c42dc3c/doc/assets/four-pillars-dark.png">
|
|
111
|
-
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/paperclipai/paperclip/1ec33ffd8b597f7e36aac3e2fbb4665b8c42dc3c/doc/assets/four-pillars-light.png">
|
|
112
|
-
<img src="https://raw.githubusercontent.com/paperclipai/paperclip/1ec33ffd8b597f7e36aac3e2fbb4665b8c42dc3c/doc/assets/four-pillars-light.png" alt="The four pillars of Paperclip">
|
|
113
|
-
</picture>
|
|
114
|
-
|
|
115
|
-
| Pillar | Built for | What it covers |
|
|
116
|
-
| --- | --- | --- |
|
|
117
|
-
| **Agentic Task Manager** — Declare intent. Agents work. You verify the output. | Everyone, daily | Tasks, approvals & review gates · proactive agent coworkers · auditable routines & workflows · verify from diffs, screenshots & tests |
|
|
118
|
-
| **Org Chart for Agents** — Roles, permissions & boundaries for humans and agents. | Managers | Mixed human + agent org chart · responsibilities, delegation, specialization · governance: who can do what · scoped secrets & company boundaries |
|
|
119
|
-
| **Agent Employee Training** — Design, train & evaluate your AI employees. | Enablers | Skill Studio & shared org-wide skills · evals & saved test runs · active learning loops & quality metrics · performance reviews for agents |
|
|
120
|
-
| **Agentic OS** — The infrastructure that makes the work run. | IT & platform | Cross-provider runtime: any model, any agent · sandboxing, integrations & MCP servers · SSO, GRC, RBAC & cost controls · data privacy, internal trace collection, compounding data value |
|
|
121
|
-
|
|
122
|
-
<br/>
|
|
123
|
-
|
|
124
|
-
## Features
|
|
125
|
-
|
|
126
|
-
<table>
|
|
127
|
-
<tr>
|
|
128
|
-
<td align="center" width="33%">
|
|
129
|
-
<h3>🔌 Bring Your Own Agent</h3>
|
|
130
|
-
Any agent, any runtime, one org chart. If it can receive a heartbeat, it's hired.
|
|
131
|
-
</td>
|
|
132
|
-
<td align="center" width="33%">
|
|
133
|
-
<h3>🎯 Goal Alignment</h3>
|
|
134
|
-
Every task traces back to the organization mission. Agents know <em>what</em> to do and <em>why</em>.
|
|
135
|
-
</td>
|
|
136
|
-
<td align="center" width="33%">
|
|
137
|
-
<h3>💓 Heartbeats</h3>
|
|
138
|
-
Agents wake on a schedule, check work, and act. Delegation flows up and down the org chart.
|
|
139
|
-
</td>
|
|
140
|
-
</tr>
|
|
141
|
-
<tr>
|
|
142
|
-
<td align="center">
|
|
143
|
-
<h3>💰 Cost Control</h3>
|
|
144
|
-
Monthly budgets per agent. When they hit the limit, they stop. No runaway costs.
|
|
145
|
-
</td>
|
|
146
|
-
<td align="center">
|
|
147
|
-
<h3>🏢 Multi-Organization</h3>
|
|
148
|
-
One deployment, many organizations. Complete data isolation. One control plane for your portfolio.
|
|
149
|
-
</td>
|
|
150
|
-
<td align="center">
|
|
151
|
-
<h3>🎫 Ticket System</h3>
|
|
152
|
-
Every conversation traced. Every decision explained. Full tool-call tracing and immutable audit log.
|
|
153
|
-
</td>
|
|
154
|
-
</tr>
|
|
155
|
-
<tr>
|
|
156
|
-
<td align="center">
|
|
157
|
-
<h3>🛡️ Governance</h3>
|
|
158
|
-
Approve hires, override strategy, pause or terminate any agent — at any time.
|
|
159
|
-
</td>
|
|
160
|
-
<td align="center">
|
|
161
|
-
<h3>📊 Org Chart</h3>
|
|
162
|
-
Hierarchies, roles, reporting lines. Your agents have a boss, a title, and a job description.
|
|
163
|
-
</td>
|
|
164
|
-
<td align="center">
|
|
165
|
-
<h3>📱 Mobile Ready</h3>
|
|
166
|
-
Monitor and manage your autonomous businesses from anywhere.
|
|
167
|
-
</td>
|
|
168
|
-
</tr>
|
|
169
|
-
</table>
|
|
170
|
-
|
|
171
|
-
<br/>
|
|
172
|
-
|
|
173
|
-
## Problems Paperclip solves
|
|
174
|
-
|
|
175
|
-
| Without Paperclip | With Paperclip |
|
|
176
|
-
| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
177
|
-
| ❌ You have 20 Claude Code tabs open and can't track which one does what. On reboot you lose everything. | ✅ Tasks are ticket-based, conversations are threaded, sessions persist across reboots. |
|
|
178
|
-
| ❌ You manually gather context from several places to remind your bot what you're actually doing. | ✅ Context flows from the task up through the project and company goals — your agent always knows what to do and why. |
|
|
179
|
-
| ❌ Folders of agent configs are disorganized and you're re-inventing task management, communication, and coordination between agents. | ✅ Paperclip gives you org charts, ticketing, delegation, and governance out of the box — so you run a company, not a pile of scripts. |
|
|
180
|
-
| ❌ Runaway loops waste hundreds of dollars of tokens and max your quota before you even know what happened. | ✅ Cost tracking surfaces token budgets and throttles agents when they're out. Management prioritizes with budgets. |
|
|
181
|
-
| ❌ You have recurring jobs (customer support, social, reports) and have to remember to manually kick them off. | ✅ Heartbeats handle regular work on a schedule. Management supervises. |
|
|
182
|
-
| ❌ You have an idea, you have to find your repo, fire up Claude Code, keep a tab open, and babysit it. | ✅ Add a task in Paperclip. Your coding agent works on it until it's done. Management reviews their work. |
|
|
183
|
-
|
|
184
|
-
<br/>
|
|
185
|
-
|
|
186
|
-
## Why Paperclip is special
|
|
187
|
-
|
|
188
|
-
Paperclip handles the hard orchestration details correctly.
|
|
189
|
-
|
|
190
|
-
| | |
|
|
191
|
-
| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
192
|
-
| **Atomic execution.** | Task checkout and budget enforcement are atomic, so no double-work and no runaway spend. |
|
|
193
|
-
| **Persistent agent state.** | Agents resume the same task context across heartbeats instead of restarting from scratch. |
|
|
194
|
-
| **Runtime skill injection.** | Agents can learn Paperclip workflows and project context at runtime, without retraining. |
|
|
195
|
-
| **Governance with rollback.** | Approval gates are enforced, config changes are revisioned, and bad changes can be rolled back safely. |
|
|
196
|
-
| **Goal-aware execution.** | Tasks carry full goal ancestry so agents consistently see the "why," not just a title. |
|
|
197
|
-
| **Portable company templates.** | Export/import orgs, agents, and skills with secret scrubbing and collision handling. |
|
|
198
|
-
| **True multi-organization isolation.** | Every entity is company-scoped, so one deployment can run many companies with separate data and audit trails. |
|
|
199
|
-
|
|
200
|
-
<br/>
|
|
201
|
-
|
|
202
|
-
## What's Under the Hood
|
|
203
|
-
|
|
204
|
-
Paperclip is a full control plane, not a wrapper. Before you build any of this yourself, know that it already exists:
|
|
205
|
-
|
|
206
|
-
```
|
|
207
|
-
┌──────────────────────────────────────────────────────────────┐
|
|
208
|
-
│ PAPERCLIP SERVER │
|
|
209
|
-
│ │
|
|
210
|
-
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
|
|
211
|
-
│ │Identity & │ │ Work & │ │ Heartbeat │ │Governance │ │
|
|
212
|
-
│ │ Access │ │ Tasks │ │ Execution │ │& Approvals│ │
|
|
213
|
-
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
|
|
214
|
-
│ │
|
|
215
|
-
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
|
|
216
|
-
│ │ Org Chart │ │Workspaces │ │ Plugins │ │ Budget │ │
|
|
217
|
-
│ │ & Agents │ │ & Runtime │ │ │ │ & Costs │ │
|
|
218
|
-
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
|
|
219
|
-
│ │
|
|
220
|
-
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
|
|
221
|
-
│ │ Routines │ │ Secrets & │ │ Activity │ │ Company │ │
|
|
222
|
-
│ │& Schedules│ │ Storage │ │ & Events │ │Portability│ │
|
|
223
|
-
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
|
|
224
|
-
└──────────────────────────────────────────────────────────────┘
|
|
225
|
-
▲ ▲ ▲ ▲
|
|
226
|
-
┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐
|
|
227
|
-
│ Claude │ │ Codex │ │ CLI │ │ HTTP/web │
|
|
228
|
-
│ Code │ │ │ │ agents │ │ bots │
|
|
229
|
-
└───────────┘ └───────────┘ └───────────┘ └───────────┘
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
### The Systems
|
|
233
|
-
|
|
234
|
-
<table>
|
|
235
|
-
<tr>
|
|
236
|
-
<td width="50%">
|
|
26
|
+
## Install
|
|
237
27
|
|
|
238
|
-
|
|
28
|
+
Requirements: Node.js 24.11 or newer, `npm`, macOS/Linux/WSL2. Nothing else — the published packages ship prebuilt.
|
|
239
29
|
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
30
|
+
```sh
|
|
31
|
+
npx @tickernelz/paperclip-pro@latest install --yes
|
|
32
|
+
paperclip-pro onboard --yes
|
|
33
|
+
```
|
|
244
34
|
|
|
245
|
-
|
|
246
|
-
</tr>
|
|
247
|
-
<tr>
|
|
248
|
-
<td>
|
|
35
|
+
`install` resolves one exact version — the `latest` dist-tag of `@tickernelz/paperclip-pro`, or `--version` — then verifies that all 31 packages of the release exist at that exact version before it downloads anything. A half-published release is refused with the missing package names; versions are never mixed across packages. It then installs the set into `~/.paperclip-pro/cli/installs/npm/<version>`, smoke-tests the payload, and only then atomically flips `~/.paperclip-pro/cli/current` and writes the `~/.local/bin/paperclip-pro` shim. Measured on a WSL2 box: 44 s, against 11 m 38 s for the same commit through the git path.
|
|
249
36
|
|
|
250
|
-
|
|
37
|
+
`latest` currently points at **2026.926.2**. Prefer it.
|
|
251
38
|
|
|
252
|
-
|
|
253
|
-
<td>
|
|
39
|
+
`2026.926.0` is an incomplete release: its run left `@tickernelz/paperclip-pro-server` in npm's staging queue, so `latest` was never moved and no GitHub release was created. npm has since published that package, so all 31 packages now exist at that version and the completeness check no longer refuses it — but the release was never validated end to end. Use `2026.926.2`.
|
|
254
40
|
|
|
255
|
-
|
|
41
|
+
Releases up to and including `2026.926.1` cannot bootstrap under npm 12, which changed the shape of `npm view --json` and denies dependency install scripts by default. Under npm 11 — the version Node 24.18.0 bundles — the same command works. `2026.926.2` and later handle both.
|
|
256
42
|
|
|
257
|
-
|
|
258
|
-
</tr>
|
|
259
|
-
<tr>
|
|
260
|
-
<td>
|
|
43
|
+
Pin a published version:
|
|
261
44
|
|
|
262
|
-
|
|
45
|
+
```sh
|
|
46
|
+
paperclip-pro install --version 2026.926.2 --yes
|
|
47
|
+
```
|
|
263
48
|
|
|
264
|
-
|
|
265
|
-
<td>
|
|
49
|
+
`--canary` follows the `canary` dist-tag, which the release workflow does not publish today; it uses `next` and `latest`.
|
|
266
50
|
|
|
267
|
-
|
|
51
|
+
`onboard --yes` writes `~/.paperclip-pro/instances/default/config.json` for trusted local loopback and starts the server on `http://127.0.0.1:3100`. An embedded PostgreSQL is created automatically. For a reachable instance, pick a bind preset:
|
|
268
52
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
53
|
+
```sh
|
|
54
|
+
paperclip-pro onboard --yes --bind lan
|
|
55
|
+
paperclip-pro onboard --yes --bind tailnet
|
|
56
|
+
```
|
|
273
57
|
|
|
274
|
-
|
|
58
|
+
### What an install replaces
|
|
275
59
|
|
|
276
|
-
|
|
277
|
-
<td>
|
|
60
|
+
An install or update only ever writes inside `~/.paperclip-pro/cli/` and the shim:
|
|
278
61
|
|
|
279
|
-
|
|
62
|
+
| Path | What happens |
|
|
63
|
+
| --- | --- |
|
|
64
|
+
| `~/.paperclip-pro/cli/installs/<npm\|git>/<id>/` | New payload directory; the two previous payloads are kept for rollback, older ones pruned |
|
|
65
|
+
| `~/.paperclip-pro/cli/current` | Symlink flipped atomically to the new payload |
|
|
66
|
+
| `~/.paperclip-pro/cli/install.json` | Install manifest, rewritten (previous records retained) |
|
|
67
|
+
| `~/.local/bin/paperclip-pro` | Managed shim, rewritten with the validated Node executable |
|
|
68
|
+
| `~/.bashrc` or `~/.zshrc` | A marked PATH block, only when `~/.local/bin` is not already on `PATH` |
|
|
280
69
|
|
|
281
|
-
|
|
282
|
-
</tr>
|
|
283
|
-
<tr>
|
|
284
|
-
<td>
|
|
70
|
+
Nothing under `~/.paperclip-pro/instances/` is touched: the instance database, `config.json`, `service.env`, secrets, logs, storage, backups and workspaces survive a payload switch in either direction.
|
|
285
71
|
|
|
286
|
-
|
|
72
|
+
### Installing an unreleased commit
|
|
287
73
|
|
|
288
|
-
|
|
289
|
-
<td>
|
|
74
|
+
The git path builds a GitHub commit from source. It needs pnpm 9.15.4, `git`, `curl`, `tar` and `corepack`, and takes minutes rather than seconds. Use it for development only:
|
|
290
75
|
|
|
291
|
-
|
|
76
|
+
```sh
|
|
77
|
+
paperclip-pro install --ref main --yes
|
|
78
|
+
paperclip-pro install --repo tickernelz/paperclip-pro --ref <commit-sha> --yes
|
|
79
|
+
```
|
|
292
80
|
|
|
293
|
-
|
|
294
|
-
</tr>
|
|
295
|
-
<tr>
|
|
296
|
-
<td>
|
|
81
|
+
`--repo` defaults to `tickernelz/paperclip-pro`. `--ref` cannot be combined with `--version` or `--canary`.
|
|
297
82
|
|
|
298
|
-
|
|
83
|
+
### Upgrade and rollback
|
|
299
84
|
|
|
300
|
-
|
|
301
|
-
|
|
85
|
+
```sh
|
|
86
|
+
paperclip-pro update --check
|
|
87
|
+
paperclip-pro update --latest
|
|
88
|
+
paperclip-pro update --rollback
|
|
89
|
+
```
|
|
302
90
|
|
|
303
|
-
|
|
91
|
+
`update` backs up the database first, installs the new payload, restarts the active service and validates it; a failed validation rolls the payload back automatically. `--rollback` returns to the retained previous payload instantly — it does not reverse database migrations.
|
|
304
92
|
|
|
305
|
-
|
|
306
|
-
</tr>
|
|
307
|
-
</table>
|
|
93
|
+
## Configuration
|
|
308
94
|
|
|
309
|
-
|
|
95
|
+
Instance configuration lives in `~/.paperclip-pro/instances/default/config.json` and is edited with `paperclip-pro configure`, not by hand while the service runs. `paperclip-pro doctor` prints the resolved paths, and `paperclip-pro env` prints the effective environment.
|
|
310
96
|
|
|
311
|
-
|
|
97
|
+
Operator environment — `PATH` entries for adapter binaries, provider API keys, proxy settings — belongs in `~/.paperclip-pro/instances/default/service.env`, one `KEY=value` per line. The systemd unit sources it with `EnvironmentFile=-`, and the CLI never rewrites it, while the unit file itself is re-rendered on every CLI-driven start.
|
|
312
98
|
|
|
313
|
-
|
|
|
314
|
-
|
|
|
315
|
-
|
|
|
316
|
-
|
|
|
317
|
-
|
|
|
318
|
-
|
|
|
319
|
-
|
|
|
320
|
-
|
|
|
99
|
+
| Variable | Default | Bounds | Meaning |
|
|
100
|
+
| --- | --- | --- | --- |
|
|
101
|
+
| `PAPERCLIP_MAX_CONCURRENT_LOCAL_RUNS` | 10 | 1–64 | Total local CLI runs this controller may have running at once. Never bypassed. |
|
|
102
|
+
| `PAPERCLIP_MAX_CONCURRENT_LOCAL_STARTS` | 4 | 1–64 | Local CLI runs allowed to be in their startup phase at once. |
|
|
103
|
+
| `PAPERCLIP_LOCAL_START_WAIT_BYPASS_SEC` | 120 | 1–3600 | A queued local run that has waited this long starts anyway, ignoring the startup cap but still inside the total cap. The same window bounds the startup phase, so a hung boot cannot block the gate forever. |
|
|
104
|
+
| `PAPERCLIP_PDF_CHROMIUM_PATH` | unset | — | Chromium-family executable used for PDF export. `PUPPETEER_EXECUTABLE_PATH` and `CHROME_PATH` are also consulted. |
|
|
105
|
+
| `PORT` | 3100 | — | HTTP listen port; overrides `server.port`. |
|
|
106
|
+
| `PAPERCLIP_HOME` | `~/.paperclip-pro` | — | Root of all instance state. |
|
|
107
|
+
| `PAPERCLIP_INSTANCE_ID` | `default` | — | Selects the instance under `PAPERCLIP_HOME/instances/`. |
|
|
108
|
+
| `PAPERCLIP_TELEMETRY_DISABLED` / `DO_NOT_TRACK` | unset | — | Disables anonymous usage telemetry, which is on by default and off automatically when `CI=true`. |
|
|
321
109
|
|
|
322
|
-
|
|
110
|
+
## Running as a service
|
|
323
111
|
|
|
324
|
-
|
|
112
|
+
```sh
|
|
113
|
+
paperclip-pro service install
|
|
114
|
+
paperclip-pro service status
|
|
115
|
+
paperclip-pro service logs -f
|
|
116
|
+
paperclip-pro service restart --drain
|
|
117
|
+
```
|
|
325
118
|
|
|
326
|
-
|
|
119
|
+
The unit is `paperclip-pro.service` for the `default` instance and `paperclip-pro-<id>.service` otherwise; on macOS the launchd label is `ing.paperclip.paperclip-pro`. `--drain` waits for executing agent runs; without it, `stop` and `restart` refuse while runs are in flight unless forced.
|
|
327
120
|
|
|
328
|
-
|
|
121
|
+
Day-two operation — state layout, safe restarts, backups, admin bootstrap, public hostnames, release mechanics, sandboxed test runs — is in [`docs/fork/OPERATIONS.md`](docs/fork/OPERATIONS.md).
|
|
329
122
|
|
|
330
|
-
|
|
123
|
+
## Development
|
|
331
124
|
|
|
332
|
-
|
|
125
|
+
Node 24.18.0 and pnpm 9.15.4 (`packageManager` in `package.json`). Work in a git worktree per change; never point a development instance at `~/.paperclip-pro`.
|
|
333
126
|
|
|
334
|
-
```
|
|
127
|
+
```sh
|
|
335
128
|
git clone https://github.com/tickernelz/paperclip-pro.git
|
|
336
129
|
cd paperclip-pro
|
|
337
130
|
pnpm install --frozen-lockfile
|
|
338
|
-
pnpm paperclip-pro --help
|
|
339
|
-
```
|
|
340
|
-
|
|
341
|
-
### 2. Install a managed payload from this repository
|
|
342
|
-
|
|
343
|
-
`install` builds the given git ref into `~/.paperclip-pro/cli` and writes the `paperclip-pro` shim to `~/.local/bin`. `--ref` is mandatory for a git install and `--repo` defaults to the upstream repository (`cli/src/commands/install.ts:27`), so both flags are required here:
|
|
344
|
-
|
|
345
|
-
```bash
|
|
346
|
-
node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts install --repo tickernelz/paperclip-pro --ref main --yes
|
|
347
|
-
```
|
|
348
|
-
|
|
349
|
-
Pin an exact commit instead of a branch when you want a reproducible install; `--ref` accepts a branch, tag, or SHA (`cli/src/commands/install.ts:139`-`cli/src/commands/install.ts:147`). `--ref` cannot be combined with `--canary` or `--version`, both of which resolve against npm and therefore do not work for this fork.
|
|
350
|
-
|
|
351
|
-
### 3. Onboard
|
|
352
|
-
|
|
353
|
-
```bash
|
|
354
|
-
paperclip-pro onboard --yes
|
|
355
|
-
```
|
|
356
|
-
|
|
357
|
-
`onboard` defaults to trusted local loopback. For authenticated/private mode choose a bind preset explicitly:
|
|
358
|
-
|
|
359
|
-
```bash
|
|
360
|
-
paperclip-pro onboard --yes --bind lan
|
|
361
|
-
paperclip-pro onboard --yes --bind tailnet
|
|
362
|
-
```
|
|
363
|
-
|
|
364
|
-
Rerunning `onboard` keeps an existing config; use `paperclip-pro configure` to edit settings. To install the background service, use `paperclip-pro onboard --install-service` or `paperclip-pro service install`.
|
|
365
|
-
|
|
366
|
-
### Or run straight from the checkout
|
|
367
|
-
|
|
368
|
-
```bash
|
|
369
131
|
pnpm dev
|
|
370
132
|
```
|
|
371
133
|
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
**How is Paperclip different from agents like OpenClaw or Claude Code?**
|
|
389
|
-
Paperclip _uses_ those agents. It orchestrates them into a company — with org charts, budgets, goals, governance, and accountability.
|
|
390
|
-
|
|
391
|
-
**Why should I use Paperclip instead of just pointing my OpenClaw to Asana or Trello?**
|
|
392
|
-
Agent orchestration has subtleties in how you coordinate who has work checked out, how to maintain sessions, monitoring costs, establishing governance - Paperclip does this for you.
|
|
393
|
-
|
|
394
|
-
(Bring-your-own-ticket-system is on the Roadmap)
|
|
134
|
+
| Command | What it does |
|
|
135
|
+
| --- | --- |
|
|
136
|
+
| `pnpm dev` | API and UI in watch mode on `:3100` |
|
|
137
|
+
| `pnpm dev:mobile` | Serves the prebuilt UI on `:3101` and proxies `/api` to `:3100` |
|
|
138
|
+
| `pnpm build` | Builds every package |
|
|
139
|
+
| `pnpm typecheck` | Type-checks every package |
|
|
140
|
+
| `pnpm test` | Vitest, the default gate (no Playwright) |
|
|
141
|
+
| `pnpm test:e2e` | Playwright browser suite |
|
|
142
|
+
| `pnpm db:generate` / `pnpm db:migrate` | Drizzle migrations |
|
|
143
|
+
|
|
144
|
+
Tests and manual trials must never touch a live instance. Use an isolated data directory:
|
|
145
|
+
|
|
146
|
+
```sh
|
|
147
|
+
node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts test-drive --data-dir /tmp/pcpro-trial --no-browser
|
|
148
|
+
```
|
|
395
149
|
|
|
396
|
-
|
|
397
|
-
By default, agents run on scheduled heartbeats and event-based triggers (task assignment, @-mentions). You can also hook in continuous agents like OpenClaw. You bring your agent and Paperclip coordinates.
|
|
150
|
+
Section 8 of [`docs/fork/OPERATIONS.md`](docs/fork/OPERATIONS.md) documents the sandbox rules for suite runs. The full development guide is [`doc/DEVELOPING.md`](doc/DEVELOPING.md); installation details are in [`doc/INSTALLING.md`](doc/INSTALLING.md) and the CLI reference in [`doc/CLI.md`](doc/CLI.md).
|
|
398
151
|
|
|
399
|
-
|
|
152
|
+
## Release
|
|
400
153
|
|
|
401
|
-
|
|
154
|
+
Pushing a `v<YYYY.MDD.P>` tag triggers `.github/workflows/release.yml`, which builds once, packs each package once, publishes the set under the `next` dist-tag in dependency order, waits for npm to expose all of it, moves `latest`, and opens a GitHub release.
|
|
402
155
|
|
|
403
|
-
```
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
pnpm dev:server # Server only
|
|
407
|
-
pnpm dev:mobile # Serve prebuilt UI on :3101 for phones/tablets (proxies /api → :3100)
|
|
408
|
-
pnpm dev:both # Run `pnpm dev` and `pnpm dev:mobile` together
|
|
409
|
-
pnpm build # Build all
|
|
410
|
-
pnpm typecheck # Type checking
|
|
411
|
-
pnpm test # Cheap default test run (Vitest only)
|
|
412
|
-
pnpm test:watch # Vitest watch mode
|
|
413
|
-
pnpm test:e2e # Playwright browser suite
|
|
414
|
-
pnpm db:generate # Generate DB migration
|
|
415
|
-
pnpm db:migrate # Apply migrations
|
|
156
|
+
```sh
|
|
157
|
+
./scripts/tag-release.sh --dry-run
|
|
158
|
+
./scripts/tag-release.sh
|
|
416
159
|
```
|
|
417
160
|
|
|
418
|
-
`
|
|
419
|
-
|
|
420
|
-
See [doc/DEVELOPING.md](doc/DEVELOPING.md) for the full development guide.
|
|
421
|
-
|
|
422
|
-
<br/>
|
|
423
|
-
|
|
424
|
-
## Roadmap
|
|
425
|
-
|
|
426
|
-
- ✅ Plugin system (e.g. add a knowledge base, custom tracing, queues, etc)
|
|
427
|
-
- ✅ Get OpenClaw / claw-style agent employees
|
|
428
|
-
- ✅ companies.sh - import and export entire organizations
|
|
429
|
-
- ✅ Easy AGENTS.md configurations
|
|
430
|
-
- ✅ Skills Manager, Skill Studio & Skills Store
|
|
431
|
-
- ✅ Scheduled Routines
|
|
432
|
-
- ✅ Better Budgeting
|
|
433
|
-
- ✅ Agent Reviews and Approvals
|
|
434
|
-
- ✅ Multiple Human Users
|
|
435
|
-
- ✅ Cloud / Sandbox agents (e2b, Cloudflare, Daytona, Modal, Novita, self-hosted Kubernetes)
|
|
436
|
-
- ✅ Artifacts & Work Products
|
|
437
|
-
- ✅ Deep Planning (planning mode, revisioned plans, plan approvals)
|
|
438
|
-
- ✅ Enforced Outcomes (watchdogs, recovery actions, review gates)
|
|
439
|
-
- ✅ MCP Tool Gateway & Apps (governed tool access)
|
|
440
|
-
- ✅ Secrets Manager with per-agent access
|
|
441
|
-
- ✅ Activity log & action attribution
|
|
442
|
-
- ✅ Self-healing runs & automatic recovery
|
|
443
|
-
- ✅ Agent evals & feedback
|
|
444
|
-
- ⚪ Memory / Knowledge
|
|
445
|
-
- ⚪ MAXIMIZER MODE
|
|
446
|
-
- ⚪ Work Queues
|
|
447
|
-
- ⚪ Self-Organization
|
|
448
|
-
- ⚪ Automatic Organizational Learning
|
|
449
|
-
- ⚪ CEO Chat
|
|
450
|
-
- 🟡 Cloud deployments (multi-tenant isolation & company Import/Export shipped)
|
|
451
|
-
- ⚪ Desktop App
|
|
452
|
-
- ⚪ Bring-your-own-ticket-system (Asana / Linear / Jira as on-ramps)
|
|
453
|
-
- ⚪ Connected Apps (one-click integrations, e.g. Vercel)
|
|
454
|
-
|
|
455
|
-
This is the short roadmap preview. See the full roadmap in [ROADMAP.md](ROADMAP.md).
|
|
456
|
-
|
|
457
|
-
<br/>
|
|
458
|
-
|
|
459
|
-
## Community & Plugins
|
|
460
|
-
|
|
461
|
-
Find Plugins and more at [awesome-paperclip](https://github.com/gsxdsm/awesome-paperclip)
|
|
161
|
+
`scripts/tag-release.sh` resolves the next free version, refuses a version whose tag already exists, and refuses to tag a commit whose `ci.yml` run is not green. The release job re-checks both: the tagged commit must be reachable from `origin/main` and must have a successful CI run. Reruns are idempotent, so a partial publish can be resumed. Section 9 of [`docs/fork/OPERATIONS.md`](docs/fork/OPERATIONS.md) has the dispatch inputs and the npm token setup.
|
|
462
162
|
|
|
463
163
|
## Observability
|
|
464
164
|
|
|
465
|
-
|
|
165
|
+
OpenTelemetry tracing activates when `OTEL_EXPORTER_OTLP_ENDPOINT` is set; the SDK, auto-instrumentation and exporter packages are optional peer dependencies. Sentry activates with `SENTRY_DSN_BACKEND` and `SENTRY_DSN_FRONTEND`. See [`doc/observability.md`](doc/observability.md).
|
|
466
166
|
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
## Telemetry
|
|
470
|
-
|
|
471
|
-
Paperclip collects anonymous usage telemetry to help us understand how the product is used and improve it. No personal information, issue content, prompts, file paths, or secrets are ever collected. Private repository references are hashed with a per-install salt before being sent.
|
|
472
|
-
|
|
473
|
-
Contributors changing emitted telemetry events should follow the [Telemetry Data Contract](packages/shared/src/telemetry/README.md).
|
|
474
|
-
For proposed first-party events that are not in the generated contract yet, follow [Telemetry Workflow](doc/TELEMETRY_WORKFLOW.md).
|
|
475
|
-
|
|
476
|
-
Telemetry is **enabled by default** and can be disabled with any of the following:
|
|
477
|
-
|
|
478
|
-
| Method | How |
|
|
479
|
-
| -------------------- | ------------------------------------------------------- |
|
|
480
|
-
| Environment variable | `PAPERCLIP_TELEMETRY_DISABLED=1` |
|
|
481
|
-
| Standard convention | `DO_NOT_TRACK=1` |
|
|
482
|
-
| CI environments | Automatically disabled when `CI=true` |
|
|
483
|
-
| Config file | Set `telemetry.enabled: false` in your Paperclip config |
|
|
484
|
-
|
|
485
|
-
## Contributing
|
|
486
|
-
|
|
487
|
-
We welcome contributions. See the [contributing guide](CONTRIBUTING.md) for details.
|
|
488
|
-
|
|
489
|
-
<br/>
|
|
490
|
-
|
|
491
|
-
## Community
|
|
492
|
-
|
|
493
|
-
This fork:
|
|
494
|
-
|
|
495
|
-
- [GitHub Issues](https://github.com/tickernelz/paperclip-pro/issues) — bugs and feature requests **for this fork**
|
|
496
|
-
|
|
497
|
-
Upstream project (do not file fork bugs there):
|
|
498
|
-
|
|
499
|
-
- [Discord](https://discord.gg/m4HZY7xNG3) — upstream community
|
|
500
|
-
- [Twitter / X](https://x.com/papercliping) — upstream updates
|
|
501
|
-
- [GitHub](https://github.com/paperclipai/paperclip) — upstream issues and discussions
|
|
502
|
-
|
|
503
|
-
<br/>
|
|
504
|
-
|
|
505
|
-
## License
|
|
167
|
+
## Licence and attribution
|
|
506
168
|
|
|
507
169
|
MIT. Upstream work is copyright Paperclip Labs, Inc ([paperclip.ing](https://paperclip.ing)); fork modifications are copyright the paperclip-pro maintainers. Both notices are in [`LICENSE`](LICENSE).
|
|
508
170
|
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
---
|
|
512
|
-
|
|
513
|
-
<p align="center">
|
|
514
|
-
<sub>Open source under MIT. Built for people who want to get work done, not babysit agents.</sub>
|
|
515
|
-
</p>
|
|
171
|
+
Upstream project, for reference only — do not file fork bugs there: [`paperclipai/paperclip`](https://github.com/paperclipai/paperclip), [docs.paperclip.ing](https://docs.paperclip.ing).
|