twinforgecli 0.3.3 → 0.4.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.
- package/README.md +81 -97
- package/dist/index.js +13617 -8183
- package/package.json +7 -6
- package/dist/index.js.map +0 -7
package/README.md
CHANGED
|
@@ -1,37 +1,27 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.svg" />
|
|
4
|
+
<img src="docs/images/logo-light.svg" alt="TwinForge" width="348" />
|
|
5
|
+
</picture>
|
|
3
6
|
</p>
|
|
4
7
|
|
|
5
8
|
<p align="center">
|
|
6
|
-
<
|
|
7
|
-
<a href="https://paperclip.ing/docs"><strong>Docs</strong></a> ·
|
|
8
|
-
<a href="https://github.com/paperclipai/paperclip"><strong>GitHub</strong></a> ·
|
|
9
|
-
<a href="https://discord.gg/m4HZY7xNG3"><strong>Discord</strong></a> ·
|
|
10
|
-
<a href="https://x.com/papercliping"><strong>Twitter</strong></a> ·
|
|
11
|
-
<a href="https://paperclip.ing"><strong>Website</strong></a>
|
|
9
|
+
<strong>TwinForge is the app people use to manage AI agents for work.</strong>
|
|
12
10
|
</p>
|
|
13
11
|
|
|
14
12
|
<p align="center">
|
|
15
|
-
<a href="
|
|
16
|
-
<a href="
|
|
17
|
-
<a href="https://
|
|
13
|
+
<a href="#quickstart"><strong>Quickstart</strong></a> ·
|
|
14
|
+
<a href="doc/"><strong>Docs</strong></a> ·
|
|
15
|
+
<a href="https://github.com/air-bizapps/twinf-forge"><strong>GitHub</strong></a>
|
|
18
16
|
</p>
|
|
19
17
|
|
|
20
18
|
<br/>
|
|
21
19
|
|
|
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 is the app people use to manage AI agents for work.
|
|
29
|
-
|
|
30
20
|
Open-source orchestration for teams of AI agents.
|
|
31
21
|
|
|
32
|
-
**If OpenClaw is an _employee_,
|
|
22
|
+
**If OpenClaw is an _employee_, TwinForge is the _company_.**
|
|
33
23
|
|
|
34
|
-
|
|
24
|
+
TwinForge 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.
|
|
35
25
|
|
|
36
26
|
It looks like a task manager. Under the hood: org charts, budgets, governance, goal alignment, and agent coordination.
|
|
37
27
|
|
|
@@ -64,7 +54,7 @@ It looks like a task manager. Under the hood: org charts, budgets, governance, g
|
|
|
64
54
|
|
|
65
55
|
<br/>
|
|
66
56
|
|
|
67
|
-
##
|
|
57
|
+
## TwinForge is right for you if
|
|
68
58
|
|
|
69
59
|
- ✅ You want to build **autonomous AI companies**
|
|
70
60
|
- ✅ You **coordinate many different agents** (OpenClaw, Codex, Claude, Cursor) toward a common goal
|
|
@@ -125,28 +115,28 @@ Monitor and manage your autonomous businesses from anywhere.
|
|
|
125
115
|
|
|
126
116
|
<br/>
|
|
127
117
|
|
|
128
|
-
## Problems
|
|
118
|
+
## Problems TwinForge solves
|
|
129
119
|
|
|
130
|
-
| Without
|
|
131
|
-
| ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
132
|
-
| ❌ You have 20 Claude Code tabs open and can't track which one does what. On reboot you lose everything.
|
|
133
|
-
| ❌ You manually gather context from several places to remind your bot what you're actually doing.
|
|
134
|
-
| ❌ Folders of agent configs are disorganized and you're re-inventing task management, communication, and coordination between agents.
|
|
135
|
-
| ❌ Runaway loops waste hundreds of dollars of tokens and max your quota before you even know what happened.
|
|
136
|
-
| ❌ You have recurring jobs (customer support, social, reports) and have to remember to manually kick them off.
|
|
137
|
-
| ❌ You have an idea, you have to find your repo, fire up Claude Code, keep a tab open, and babysit it.
|
|
120
|
+
| Without TwinForge | With TwinForge |
|
|
121
|
+
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
122
|
+
| ❌ 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. |
|
|
123
|
+
| ❌ 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. |
|
|
124
|
+
| ❌ Folders of agent configs are disorganized and you're re-inventing task management, communication, and coordination between agents. | ✅ TwinForge gives you org charts, ticketing, delegation, and governance out of the box — so you run a company, not a pile of scripts. |
|
|
125
|
+
| ❌ 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. |
|
|
126
|
+
| ❌ 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. |
|
|
127
|
+
| ❌ 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 TwinForge. Your coding agent works on it until it's done. Management reviews their work. |
|
|
138
128
|
|
|
139
129
|
<br/>
|
|
140
130
|
|
|
141
|
-
## Why
|
|
131
|
+
## Why TwinForge is special
|
|
142
132
|
|
|
143
|
-
|
|
133
|
+
TwinForge handles the hard orchestration details correctly.
|
|
144
134
|
|
|
145
135
|
| | |
|
|
146
136
|
| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
147
137
|
| **Atomic execution.** | Task checkout and budget enforcement are atomic, so no double-work and no runaway spend. |
|
|
148
138
|
| **Persistent agent state.** | Agents resume the same task context across heartbeats instead of restarting from scratch. |
|
|
149
|
-
| **Runtime skill injection.** | Agents can learn
|
|
139
|
+
| **Runtime skill injection.** | Agents can learn TwinForge workflows and project context at runtime, without retraining. |
|
|
150
140
|
| **Governance with rollback.** | Approval gates are enforced, config changes are revisioned, and bad changes can be rolled back safely. |
|
|
151
141
|
| **Goal-aware execution.** | Tasks carry full goal ancestry so agents consistently see the "why," not just a title. |
|
|
152
142
|
| **Portable company templates.** | Export/import orgs, agents, and skills with secret scrubbing and collision handling. |
|
|
@@ -156,11 +146,11 @@ Paperclip handles the hard orchestration details correctly.
|
|
|
156
146
|
|
|
157
147
|
## What's Under the Hood
|
|
158
148
|
|
|
159
|
-
|
|
149
|
+
TwinForge is a full control plane, not a wrapper. Before you build any of this yourself, know that it already exists:
|
|
160
150
|
|
|
161
151
|
```
|
|
162
152
|
┌──────────────────────────────────────────────────────────────┐
|
|
163
|
-
│
|
|
153
|
+
│ TWINFORGE SERVER │
|
|
164
154
|
│ │
|
|
165
155
|
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
|
|
166
156
|
│ │Identity & │ │ Work & │ │ Heartbeat │ │Governance │ │
|
|
@@ -238,7 +228,7 @@ Paperclip is a full control plane, not a wrapper. Before you build any of this y
|
|
|
238
228
|
<tr>
|
|
239
229
|
<td>
|
|
240
230
|
|
|
241
|
-
**Plugins** — Instance-wide plugin system with out-of-process workers, capability-gated host services, job scheduling, tool exposure, and UI contributions. Extend
|
|
231
|
+
**Plugins** — Instance-wide plugin system with out-of-process workers, capability-gated host services, job scheduling, tool exposure, and UI contributions. Extend TwinForge without forking it.
|
|
242
232
|
|
|
243
233
|
</td>
|
|
244
234
|
<td>
|
|
@@ -263,30 +253,59 @@ Paperclip is a full control plane, not a wrapper. Before you build any of this y
|
|
|
263
253
|
|
|
264
254
|
<br/>
|
|
265
255
|
|
|
266
|
-
## What
|
|
256
|
+
## What TwinForge is not
|
|
267
257
|
|
|
268
258
|
| | |
|
|
269
259
|
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
270
260
|
| **Not a chatbot.** | Agents have jobs, not chat windows. |
|
|
271
261
|
| **Not an agent framework.** | We don't tell you how to build agents. We tell you how to run a company made of them. |
|
|
272
|
-
| **Not a workflow builder.** | No drag-and-drop pipelines.
|
|
273
|
-
| **Not a prompt manager.** | Agents bring their own prompts, models, and runtimes.
|
|
274
|
-
| **Not a single-agent tool.** | This is for teams. If you have one agent, you probably don't need
|
|
275
|
-
| **Not a code review tool.** |
|
|
262
|
+
| **Not a workflow builder.** | No drag-and-drop pipelines. TwinForge models companies — with org charts, goals, budgets, and governance. |
|
|
263
|
+
| **Not a prompt manager.** | Agents bring their own prompts, models, and runtimes. TwinForge manages the organization they work in. |
|
|
264
|
+
| **Not a single-agent tool.** | This is for teams. If you have one agent, you probably don't need TwinForge. If you have twenty — you definitely do. |
|
|
265
|
+
| **Not a code review tool.** | TwinForge orchestrates work, not pull requests. Bring your own review process. |
|
|
276
266
|
|
|
277
267
|
<br/>
|
|
278
268
|
|
|
279
269
|
## Quickstart
|
|
280
270
|
|
|
281
|
-
Open source. Self-hosted. No
|
|
271
|
+
Open source. Self-hosted. No account required.
|
|
272
|
+
|
|
273
|
+
The fastest way to run TwinForge is the standalone installer — no repo clone, no toolchain:
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
curl -fsSL https://raw.githubusercontent.com/air-bizapps/twinforge-dist/main/install.sh | sh
|
|
277
|
+
twinforge enroll --instance https://twinforge.<your-org>.com
|
|
278
|
+
twinforge
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
This installs a self-contained app bundle and adds it to your `PATH` (the installer appends to your shell rc file). Once installed, TwinForge updates itself in the background — `twinforge update`, `twinforge rollback`, and `twinforge status` are available, with updates throttled to at most once every 6 hours. The channel manifest is signed, and the installer verifies the signature before downloading anything.
|
|
282
|
+
|
|
283
|
+
`twinforge enroll` links the machine to an instance through a browser approval flow; without enrollment the app runs in standalone mode. Available for macOS (arm64), Linux (x64), and Windows (x64) — Windows builds pass CI (build + test suite) but haven't been verified by hand yet; see [docs/windows-verification.md](docs/windows-verification.md) for what's covered and what isn't.
|
|
284
|
+
|
|
285
|
+
Prefer to run from source instead:
|
|
286
|
+
|
|
287
|
+
```bash
|
|
288
|
+
git clone https://github.com/air-bizapps/twinf-forge.git
|
|
289
|
+
cd twinf-forge
|
|
290
|
+
pnpm install
|
|
291
|
+
pnpm dev
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
This starts the API server at `http://localhost:3100`. An embedded PostgreSQL database is created automatically — no setup required.
|
|
295
|
+
|
|
296
|
+
> **Requirements:** Node.js 20+, pnpm 9.15+
|
|
297
|
+
|
|
298
|
+
To interact with a remote TwinForge instance from any machine — no repo clone needed — install the public CLI:
|
|
282
299
|
|
|
283
300
|
```bash
|
|
284
|
-
|
|
301
|
+
npm install -g twinforgecli
|
|
302
|
+
twinforgecli connect --api-base https://twinforge.<your-org>.com
|
|
303
|
+
twinforgecli whoami
|
|
285
304
|
```
|
|
286
305
|
|
|
287
306
|
> **Troubleshooting: private npm registry `.npmrc`**
|
|
288
307
|
>
|
|
289
|
-
> If
|
|
308
|
+
> If the install fails with an `E404` for `twinforgecli` and you use a private npm registry (for example GitHub Packages) via a global `~/.npmrc`, npm may be resolving the package against that private registry instead of the public npm registry.
|
|
290
309
|
>
|
|
291
310
|
> Diagnostic:
|
|
292
311
|
>
|
|
@@ -297,31 +316,10 @@ npx paperclipai onboard --yes
|
|
|
297
316
|
> Workaround (cross-platform; force the public npm registry for this command):
|
|
298
317
|
>
|
|
299
318
|
> ```bash
|
|
300
|
-
>
|
|
319
|
+
> npm install -g twinforgecli --registry https://registry.npmjs.org
|
|
301
320
|
> ```
|
|
302
321
|
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
```bash
|
|
306
|
-
npx paperclipai onboard --yes --bind lan
|
|
307
|
-
# or:
|
|
308
|
-
npx paperclipai onboard --yes --bind tailnet
|
|
309
|
-
```
|
|
310
|
-
|
|
311
|
-
If you already have Paperclip configured, rerunning `onboard` keeps the existing config in place. Use `paperclipai configure` to edit settings.
|
|
312
|
-
|
|
313
|
-
Or manually:
|
|
314
|
-
|
|
315
|
-
```bash
|
|
316
|
-
git clone https://github.com/paperclipai/paperclip.git
|
|
317
|
-
cd paperclip
|
|
318
|
-
pnpm install
|
|
319
|
-
pnpm dev
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
This starts the API server at `http://localhost:3100`. An embedded PostgreSQL database is created automatically — no setup required.
|
|
323
|
-
|
|
324
|
-
> **Requirements:** Node.js 20+, pnpm 9.15+
|
|
322
|
+
Use `twinforgecli configure` to edit settings after the first run. See [doc/CLI.md](doc/CLI.md) for the full CLI reference.
|
|
325
323
|
|
|
326
324
|
<br/>
|
|
327
325
|
|
|
@@ -330,21 +328,21 @@ This starts the API server at `http://localhost:3100`. An embedded PostgreSQL da
|
|
|
330
328
|
**What does a typical setup look like?**
|
|
331
329
|
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.
|
|
332
330
|
|
|
333
|
-
If you're a solo entrepreneur you can use Tailscale to access
|
|
331
|
+
If you're a solo entrepreneur you can use Tailscale to access TwinForge on the go. Then later you can deploy to e.g. Vercel when you need it.
|
|
334
332
|
|
|
335
333
|
**Can I run multiple companies?**
|
|
336
334
|
Yes. A single deployment can run an unlimited number of companies with complete data isolation.
|
|
337
335
|
|
|
338
|
-
**How is
|
|
339
|
-
|
|
336
|
+
**How is TwinForge different from agents like OpenClaw or Claude Code?**
|
|
337
|
+
TwinForge _uses_ those agents. It orchestrates them into a company — with org charts, budgets, goals, governance, and accountability.
|
|
340
338
|
|
|
341
|
-
**Why should I use
|
|
342
|
-
Agent orchestration has subtleties in how you coordinate who has work checked out, how to maintain sessions, monitoring costs, establishing governance -
|
|
339
|
+
**Why should I use TwinForge instead of just pointing my OpenClaw to Asana or Trello?**
|
|
340
|
+
Agent orchestration has subtleties in how you coordinate who has work checked out, how to maintain sessions, monitoring costs, establishing governance - TwinForge does this for you.
|
|
343
341
|
|
|
344
342
|
(Bring-your-own-ticket-system is on the Roadmap)
|
|
345
343
|
|
|
346
344
|
**Do agents run continuously?**
|
|
347
|
-
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
|
|
345
|
+
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 TwinForge coordinates.
|
|
348
346
|
|
|
349
347
|
<br/>
|
|
350
348
|
|
|
@@ -397,28 +395,21 @@ This is the short roadmap preview. See the full roadmap in [ROADMAP.md](ROADMAP.
|
|
|
397
395
|
|
|
398
396
|
<br/>
|
|
399
397
|
|
|
400
|
-
## Community & Plugins
|
|
401
|
-
|
|
402
|
-
Find Plugins and more at [awesome-paperclip](https://github.com/gsxdsm/awesome-paperclip)
|
|
403
|
-
|
|
404
398
|
## Observability
|
|
405
399
|
|
|
406
|
-
|
|
400
|
+
TwinForge 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. The `@opentelemetry/*` 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.
|
|
401
|
+
|
|
402
|
+
## Upstream Paperclip telemetry (disabled) <!-- rebrand:keep -->
|
|
407
403
|
|
|
408
|
-
|
|
404
|
+
TwinForge is a fork of `paperclipai/paperclip`, which ships its own vendor telemetry client (`packages/shared/src/telemetry/client.ts`, pointed at upstream ingest endpoints). <!-- rebrand:keep --> That client is **hard-disabled** in TwinForge: the resolver in `packages/shared/src/telemetry/config.ts` pins `enabled: false` regardless of env vars or config files, so no usage data ever leaves your install through it — no opt-out is needed, and no setting re-enables it.
|
|
409
405
|
|
|
410
|
-
|
|
406
|
+
This is unrelated to the AI/R WatchTower reporting described below, which is a separate, always-on mechanism.
|
|
411
407
|
|
|
412
|
-
|
|
408
|
+
## Usage telemetry to WatchTower
|
|
413
409
|
|
|
414
|
-
|
|
410
|
+
Every TwinForge install — including a local development clone — reports a `fleet-snapshot` to the AI/R WatchTower console every 15 minutes. This is the same payload the console already polls from managed instances: instance version and health, counters, run timings and outcomes, cost rollups, and names — company names, agent names and roles (for the live roster, active runs, recently-failed runs, and stale-heartbeat listings), the instance name, environment names, and plugin names. It also includes `hostLabel`, the machine's hostname (`os.hostname()`), so an operator can tell one reporting machine from another in the approval queue. It contains no issue titles, no run output, and no prompts. It is compulsory and has no opt-out flag. A new install is not counted until an operator approves it in the console.
|
|
415
411
|
|
|
416
|
-
|
|
417
|
-
| -------------------- | ------------------------------------------------------- |
|
|
418
|
-
| Environment variable | `PAPERCLIP_TELEMETRY_DISABLED=1` |
|
|
419
|
-
| Standard convention | `DO_NOT_TRACK=1` |
|
|
420
|
-
| CI environments | Automatically disabled when `CI=true` |
|
|
421
|
-
| Config file | Set `telemetry.enabled: false` in your Paperclip config |
|
|
412
|
+
To point a local install at a development WatchTower instead, set `WATCHTOWER_INGEST_URL` and `WATCHTOWER_INGEST_KEY`.
|
|
422
413
|
|
|
423
414
|
## Contributing
|
|
424
415
|
|
|
@@ -428,20 +419,13 @@ We welcome contributions. See the [contributing guide](CONTRIBUTING.md) for deta
|
|
|
428
419
|
|
|
429
420
|
## Community
|
|
430
421
|
|
|
431
|
-
- [
|
|
432
|
-
- [Twitter / X](https://x.com/papercliping) — Follow updates and announcements
|
|
433
|
-
- [GitHub Issues](https://github.com/paperclipai/paperclip/issues) — bugs and feature requests
|
|
434
|
-
- [GitHub Discussions](https://github.com/paperclipai/paperclip/discussions) — ideas and RFC
|
|
422
|
+
- [GitHub Issues](https://github.com/air-bizapps/twinf-forge/issues) — bugs and feature requests
|
|
435
423
|
|
|
436
424
|
<br/>
|
|
437
425
|
|
|
438
426
|
## License
|
|
439
427
|
|
|
440
|
-
MIT
|
|
441
|
-
|
|
442
|
-
## Star History
|
|
443
|
-
|
|
444
|
-
[](https://www.star-history.com/?repos=paperclipai%2Fpaperclip&type=date&legend=top-left)
|
|
428
|
+
MIT — see [LICENSE](LICENSE).
|
|
445
429
|
|
|
446
430
|
<br/>
|
|
447
431
|
|