@tickernelz/paperclip-pro 2026.925.0

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.
Files changed (5) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +515 -0
  3. package/dist/index.js +62291 -0
  4. package/dist/index.js.map +7 -0
  5. package/package.json +57 -0
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Paperclip AI
4
+ Copyright (c) 2026 Zhafron Adani Kautsar (paperclip-pro fork modifications)
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,515 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/paperclipai/paperclip/ee7f7f96509e491b711f542a15618644ab619c32/doc/assets/banner.jpg" alt="Paperclip Pro" width="720" />
3
+ </p>
4
+
5
+ <p align="center">
6
+ <a href="#quickstart"><strong>Quickstart</strong></a> &middot;
7
+ <a href="docs/fork/OPERATIONS.md"><strong>Operations</strong></a> &middot;
8
+ <a href="https://github.com/tickernelz/paperclip-pro"><strong>This fork</strong></a> &middot;
9
+ <a href="https://github.com/paperclipai/paperclip"><strong>Upstream</strong></a> &middot;
10
+ <a href="https://docs.paperclip.ing"><strong>Upstream docs</strong></a> &middot;
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
+ # Paperclip Pro
29
+
30
+ **Paperclip Pro is a hard fork of [`paperclipai/paperclip`](https://github.com/paperclipai/paperclip), branched at upstream commit `7b7c4d417`. It is not an upstream release and is not endorsed by Paperclip Labs, Inc.**
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.
33
+
34
+ The fork tracks no upstream release cadence and publishes nothing to the npm registry. Install it from this git repository; see [Quickstart](#quickstart). Report fork bugs in this repository, never in the upstream tracker.
35
+
36
+ ## What this fork changes
37
+
38
+ Everything below is on `main` and absent from upstream `7b7c4d417`.
39
+
40
+ | Change | Where |
41
+ | --- | --- |
42
+ | **First-party `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`, and a UI transcript parser. | [`packages/adapters/omp-local`](packages/adapters/omp-local); registered at `server/src/adapters/registry.ts:133` and `server/src/adapters/builtin-adapter-types.ts:16` |
43
+ | **`uiParserPath` for statically registered adapters.** `GET /api/adapters/:type/ui-parser.js` used to answer 404 for every built-in adapter because the loader only consulted the external plugin store. | `packages/adapter-utils/src/types.ts:462`, `server/src/adapters/plugin-loader.ts:74`, `server/src/routes/adapters.ts:768` |
44
+ | **Sandboxed transcript parser worker survives global lockdown.** Plain `self.fetch = undefined` assignments failed on read-only worker globals and took the worker down; denied globals are now installed through `Object.defineProperty` inside `try`/`catch`. | `ui/src/adapters/sandboxed-parser-worker.ts:46`–`ui/src/adapters/sandboxed-parser-worker.ts:55` |
45
+ | **A clean shutdown no longer parks issues.** A graceful stop has a known provider outcome, so only genuine process loss still earns a reconciliation hold. | `server/src/services/legacy-execution-recovery.ts:14`, `server/src/services/legacy-execution-recovery.ts:29` |
46
+ | **Runs this server interrupted during shutdown are rescheduled** instead of refused as process loss; native runtimes stay suspended. | `server/src/services/heartbeat.ts:14325`, `server/src/services/heartbeat.ts:14327` |
47
+ | **Interrupt acknowledgement is read from the full result JSON.** The safe 64 KiB projection strips `executionCancellation`, so a successful adapter interrupt on an oversized run was reported to the UI as a termination conflict. | `server/src/services/heartbeat.ts:28820` |
48
+ | **`service restart --drain` plus a live-run guard.** Restart and stop refuse while agent runs are executing unless you drain or force. | `cli/src/commands/service.ts:210`, `cli/src/commands/service.ts:282`–`cli/src/commands/service.ts:284`, `cli/src/services/instance-drain.ts:128` |
49
+ | **Isolated home.** `PAPERCLIP_HOME` defaults to `~/.paperclip-pro`; config, embedded Postgres, logs, storage, and backups all resolve under `~/.paperclip-pro/instances/<id>`. | `packages/shared/src/home-paths.ts:16`–`packages/shared/src/home-paths.ts:19`, `packages/shared/src/config-schema.ts:27` |
50
+ | **Per-instance `EnvironmentFile` in the systemd unit.** `ensureCurrent()` rewrites the unit on every install, start, and restart, so operator environment used to be lost; the unit now sources an optional `<instanceRoot>/service.env` the CLI never overwrites. | `cli/src/services/service-manager.ts:126`, `cli/src/services/service-manager.ts:149` |
51
+
52
+ Operators: read [`docs/fork/OPERATIONS.md`](docs/fork/OPERATIONS.md).
53
+
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/ee7f7f96509e491b711f542a15618644ab619c32/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/ee7f7f96509e491b711f542a15618644ab619c32/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/ee7f7f96509e491b711f542a15618644ab619c32/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/ee7f7f96509e491b711f542a15618644ab619c32/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/ee7f7f96509e491b711f542a15618644ab619c32/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/ee7f7f96509e491b711f542a15618644ab619c32/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%">
237
+
238
+ **Identity & Access** — Two deployment modes (trusted local or authenticated), board users, agent API keys, short-lived run JWTs, company memberships, invite flows, and OpenClaw onboarding. Every mutating request is traced to an actor.
239
+
240
+ </td>
241
+ <td width="50%">
242
+
243
+ **Org Chart & Agents** — Agents have roles, titles, reporting lines, permissions, and budgets. Adapter examples match the diagram: Claude Code, Codex, CLI agents such as Cursor/Gemini/bash, HTTP/webhook bots such as OpenClaw, and external adapter plugins. If it can receive a heartbeat, it's hired.
244
+
245
+ </td>
246
+ </tr>
247
+ <tr>
248
+ <td>
249
+
250
+ **Work & Task System** — Issues carry company/project/goal/parent links, atomic checkout with execution locks, first-class blocker dependencies, comments, documents, attachments, work products, labels, and inbox state. No double-work, no lost context.
251
+
252
+ </td>
253
+ <td>
254
+
255
+ **Heartbeat Execution** — DB-backed wakeup queue with coalescing, budget checks, workspace resolution, secret injection, skill loading, and adapter invocation. Runs produce structured logs, cost events, session state, and audit trails. Recovery handles orphaned runs automatically.
256
+
257
+ </td>
258
+ </tr>
259
+ <tr>
260
+ <td>
261
+
262
+ **Workspaces & Runtime** — Project workspaces, isolated execution workspaces (git worktrees, operator branches), and runtime services (dev servers, preview URLs). Agents work in the right directory with the right context every time.
263
+
264
+ </td>
265
+ <td>
266
+
267
+ **Governance & Approvals** — Board approval workflows, execution policies with review/approval stages, decision tracking, budget hard-stops, agent pause/resume/terminate, and full audit logging. Nothing ships without your sign-off.
268
+
269
+ </td>
270
+ </tr>
271
+ <tr>
272
+ <td>
273
+
274
+ **Budget & Cost Control** — Token and cost tracking by company, agent, project, goal, issue, provider, and model. Scoped budget policies with warning thresholds and hard stops. Overspend pauses agents and cancels queued work automatically.
275
+
276
+ </td>
277
+ <td>
278
+
279
+ **Routines & Schedules** — Recurring tasks with cron, webhook, and API triggers. Concurrency and catch-up policies. Each routine execution creates a tracked issue and wakes the assigned agent — no manual kick-offs needed.
280
+
281
+ </td>
282
+ </tr>
283
+ <tr>
284
+ <td>
285
+
286
+ **Plugins** — Instance-wide plugin system with out-of-process workers, capability-gated host services, job scheduling, tool exposure, and UI contributions. Extend Paperclip without forking it.
287
+
288
+ </td>
289
+ <td>
290
+
291
+ **Secrets & Storage** — Instance and company secrets, encrypted local storage, provider-backed object storage, attachments, and work products. Sensitive values stay out of prompts unless a scoped run explicitly needs them.
292
+
293
+ </td>
294
+ </tr>
295
+ <tr>
296
+ <td>
297
+
298
+ **Activity & Events** — Mutating actions, heartbeat state changes, cost events, approvals, comments, and work products are recorded as durable activity so operators can audit what happened and why.
299
+
300
+ </td>
301
+ <td>
302
+
303
+ **Company Portability** — Export and import entire organizations — agents, skills, projects, routines, and issues — with secret scrubbing and collision handling. One deployment, many companies, complete data isolation.
304
+
305
+ </td>
306
+ </tr>
307
+ </table>
308
+
309
+ <br/>
310
+
311
+ ## What Paperclip is not
312
+
313
+ | | |
314
+ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
315
+ | **Not a chatbot.** | Agents have jobs, not chat windows. |
316
+ | **Not an agent framework.** | We don't tell you how to build agents. We tell you how to run a company made of them. |
317
+ | **Not a workflow builder.** | No drag-and-drop pipelines. Paperclip models companies — with org charts, goals, budgets, and governance. |
318
+ | **Not a prompt manager.** | Agents bring their own prompts, models, and runtimes. Paperclip manages the organization they work in. |
319
+ | **Not a single-agent tool.** | This is for teams. If you have one agent, you probably don't need Paperclip. If you have twenty — you definitely do. |
320
+ | **Not a code review tool.** | Paperclip orchestrates work, not pull requests. Bring your own review process. |
321
+
322
+ <br/>
323
+
324
+ ## Quickstart
325
+
326
+ Open source. Self-hosted. No Paperclip account required.
327
+
328
+ This fork is not published to npm: `npm view @tickernelz/paperclip-pro` returns 404, and `https://paperclip.ing/install.sh` installs **upstream**, not this fork. Install from git.
329
+
330
+ **Requirements:** Node.js 24.11+ (`package.json` `engines`), pnpm 9.15.4 (`packageManager`), `git`, `curl`, `tar`, and `corepack`.
331
+
332
+ ### 1. Bootstrap the CLI from a source checkout
333
+
334
+ ```bash
335
+ git clone https://github.com/tickernelz/paperclip-pro.git
336
+ cd paperclip-pro
337
+ 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
+ pnpm dev
370
+ ```
371
+
372
+ This starts the API server at `http://localhost:3100`. An embedded PostgreSQL database is created automatically — no setup required.
373
+
374
+ Day-two operation of an installed instance (state layout, safe restarts, backups, new admins, sandboxed test runs) is documented in [`docs/fork/OPERATIONS.md`](docs/fork/OPERATIONS.md).
375
+
376
+ <br/>
377
+
378
+ ## FAQ
379
+
380
+ **What does a typical setup look like?**
381
+ Locally, a single Node.js process manages an embedded Postgres and local file storage. For production, point it at your own Postgres and deploy however you like. Configure projects, agents, and goals — the agents take care of the rest.
382
+
383
+ If you're a solo entrepreneur you can use Tailscale to access Paperclip on the go. Then later you can deploy to e.g. Vercel when you need it.
384
+
385
+ **Can I run multiple companies?**
386
+ Yes. A single deployment can run an unlimited number of companies with complete data isolation.
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)
395
+
396
+ **Do agents run continuously?**
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.
398
+
399
+ <br/>
400
+
401
+ ## Development
402
+
403
+ ```bash
404
+ pnpm dev # Full dev (API + UI, watch mode)
405
+ pnpm dev:once # Full dev without file watching
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
416
+ ```
417
+
418
+ `pnpm test` does not run Playwright. Browser suites stay separate and are typically run only when working on those flows or in CI.
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)
462
+
463
+ ## Observability
464
+
465
+ Paperclip ships with opt-in OpenTelemetry auto-instrumentation for the server (traces only). It activates when `OTEL_EXPORTER_OTLP_ENDPOINT` is set and supports `grpc`, `http/protobuf`, and `http/json` via the standard `OTEL_EXPORTER_OTLP_PROTOCOL` env var. `@opentelemetry/api` is a normal server dependency; the SDK, auto-instrumentation, and exporter packages are optional peer dependencies — install them only if you want tracing. See [doc/observability.md](doc/observability.md) for install commands and the full env-var reference.
466
+
467
+ Paperclip also ships with opt-in Sentry error monitoring for the server and the browser. Set `SENTRY_DSN_FRONTEND` to activate it for the browser and `SENTRY_DSN_BACKEND` to activate it for the server — each variable is optional, and the legacy `SENTRY_DSN` variable still works as a fallback for either component. The supported server SDK version is `@sentry/node@10.71.0`; it is an optional peer dependency for the server, so install it only if you want error monitoring. The browser SDK, `@sentry/browser`, is pinned to the same exact version. See [doc/observability.md](doc/observability.md#sentry-error-monitoring) for the install command, the privacy settings, and the full default capture set.
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
506
+
507
+ 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
+
509
+ <br/>
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>