docs: add README, draft README, and adapter logo assets

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-02 10:31:59 -06:00
parent 410164a632
commit b8bb7f0bbb
8 changed files with 383 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,265 @@
 <p align="center">
  <!-- TODO: replace with banner image -->
  <img src="doc/assets/header.png" alt="Paperclip" width="720" />
 </p>
 <h3 align="center">The control plane for autonomous AI companies.</h3>
 <p align="center">
  Open-source orchestration to manage teams of AI agents.<br/>
  Hire AI employees, set goals, automate jobs — your business runs itself.
 </p>
 <p align="center">
  <a href="#quickstart"><strong>Quickstart</strong></a> &middot;
  <a href="https://paperclip.dev/docs"><strong>Docs</strong></a> &middot;
  <a href="https://github.com/paperclip-dev/paperclip"><strong>GitHub</strong></a> &middot;
  <a href="https://discord.gg/paperclip"><strong>Discord</strong></a>
 </p>
 <p align="center">
  <a href="https://github.com/paperclip-dev/paperclip/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
  <a href="https://github.com/paperclip-dev/paperclip/stargazers"><img src="https://img.shields.io/github/stars/paperclip-dev/paperclip?style=flat" alt="Stars" /></a>
  <a href="https://discord.gg/paperclip"><img src="https://img.shields.io/discord/000000000?label=discord" alt="Discord" /></a>
 </p>
 <br/>
 <!-- TODO: replace with demo video / gif -->
 <p align="center">
  <code>[demo video placeholder]</code>
 </p>
 <br/>
 ## What is Paperclip?
 ### **If OpenClaw is an _employee_, Paperclip is the _company_**
 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 your agents' work and costs from one dashboard.
 It looks like a task manager — but under the hood it has org charts, budgets, governance, goal alignment, and agent coordination.
 **Three steps to an autonomous company:**
 |        | Step            | Example                                                            |
 | ------ | --------------- | ------------------------------------------------------------------ |
 | **01** | Define the goal | _"Build the #1 AI note-taking app to $1M MRR."_                    |
 | **02** | Hire the team   | CEO, CTO, engineers, designers, marketers — any bot, any provider. |
 | **03** | Approve and run | Review strategy. Set budgets. Hit go. Monitor from the dashboard.  |
 <br/>
 > **COMING SOON: Clipmart** — Download and run entire companies with one click. Browse pre-built company templates — full org structures, agent configs, and skills — and import them into your Paperclip instance in seconds.
 <br/>
 <table>
  <tr>
    <td align="center"><strong>Works<br/>with</strong></td>
    <td align="center"><img src="doc/assets/logos/openclaw.svg" width="32" alt="OpenClaw" /><br/><sub>OpenClaw</sub></td>
    <td align="center"><img src="doc/assets/logos/claude.svg" width="32" alt="Claude" /><br/><sub>Claude Code</sub></td>
    <td align="center"><img src="doc/assets/logos/codex.svg" width="32" alt="Codex" /><br/><sub>Codex</sub></td>
    <td align="center"><img src="doc/assets/logos/cursor.svg" width="32" alt="Cursor" /><br/><sub>Cursor</sub></td>
   <td align="center"><img src="doc/assets/logos/bash.svg" width="32" alt="Bash" /><br/><sub>Bash</sub></td>
    <td align="center"><img src="doc/assets/logos/http.svg" width="32" alt="HTTP" /><br/><sub>HTTP</sub></td>
  </tr>
 </table>
 _If it can receive a heartbeat, it's hired._
 <br/>
 ## Paperclip is right for you if
 - You want to build autonomous AI companies
 - You coordinate many different agents (OpenClaw, Codex, Claude, Cursor) toward a common goal
 - You have 20 simultaneous Claude Code terminals open and lose track of what everyone is doing
 - You want agents running autonomously 24/7, but still want to audit work and chime in when needed
 - You want to monitor costs and enforce budgets
 - You want a process for managing agents that feels like using a task manager
 - You want to manage your autonomous businesses from your phone
 <br/>
 ## Features
 ### Bring Your Own Agent
 Your Claude, Cursor, Codex, and OpenClaw — organized under one org structure, pointed at one goal. If it can receive a heartbeat, it's hired.
 ### Goal Alignment
 Every piece of work traces back to the company mission. Your agents know _what_ to do and _why_.
 ```
 Company Mission → Project Goal → Agent Goal → Task
 ```
 ### Heartbeats
 Agents wake up on a schedule, check their work, and act. Delegation flows up and down the org chart. Ticket assignments wake agents. Cross-team requests delegate to the best agent for the job.
 ### Cost Control
 Every agent gets a monthly budget. When they hit it, they stop. No runaway costs. No surprise bills. Track costs per agent, per task, per project, per goal.
 ### Multi-Company
 One deployment. Many companies. Run one AI company or fifty with complete data isolation. One control plane for your entire portfolio.
 ### Ticket System
 Every conversation traced. Every decision explained. Structured tickets with clear owners, full tool-call tracing, and an immutable audit log. Nothing happens in the dark.
 ### Governance
 You're the board. Approve hires. Approve strategy. Override anything. Agents can't hire new agents or execute strategies without your sign-off. Pause, resume, reassign, terminate — at any time.
 <br/>
 ## What Paperclip is not
 |                              |                                                                                                                      |
 | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
 | **Not a chatbot.**           | Agents have jobs, not chat windows.                                                                                  |
 | **Not an agent framework.**  | We don't tell you how to build agents. We tell you how to run a company made of them.                                |
 | **Not a workflow builder.**  | No drag-and-drop pipelines. Paperclip models companies — with org charts, goals, budgets, and governance.            |
 | **Not a prompt manager.**    | Agents bring their own prompts, models, and runtimes. Paperclip manages the organization they work in.               |
 | **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. |
 <br/>
 ## Quickstart
 Open source. Self-hosted. No Paperclip account required.
 ```bash
 npx paperclip onboard
 ```
 Or manually:
 ```bash
 git clone https://github.com/paperclip-dev/paperclip.git
 cd paperclip
 pnpm install
 pnpm dev
 ```
 This starts the API server at `http://localhost:3100` and the UI at `http://localhost:5173`. An embedded PostgreSQL database is created automatically — no setup required.
 ### With Docker
 ```bash
 docker compose up --build
 ```
 > **Requirements:** Node.js 20+, pnpm 9.15+
 <br/>
 ## Architecture
 ```
 ┌──────────────────────────────────────────────────────┐
 │                    You (the board)                    │
 ├──────────────────────────────────────────────────────┤
 │                  Paperclip (control plane)            │
 │                                                      │
 │   Dashboard · Org Chart · Tasks · Goals · Budgets    │
 │   Approvals · Activity Log · Cost Tracking           │
 ├──────────────────────────────────────────────────────┤
 │                    Adapters                           │
 │                                                      │
 │   Claude  ·  OpenClaw  ·  Codex  ·  Cursor  ·  HTTP │
 └──────────────────────────────────────────────────────┘
 ```
 Paperclip is the **control plane**, not the execution plane. Agents run wherever they run and phone home. Adapters connect Paperclip to any execution environment.
 **Stack:** TypeScript &middot; Express &middot; React 19 &middot; PostgreSQL &middot; Drizzle ORM &middot; TailwindCSS
 <br/>
 ## FAQ
 **How is Paperclip different from agents like OpenClaw or Claude Code?**
 Paperclip _uses_ those agents. It orchestrates them into a company — with org charts, budgets, goals, governance, and accountability.
 **Can I use my existing agents?**
 Yes. Paperclip is unopinionated about agent runtimes. Your agents can be Claude Code sessions, OpenClaw bots, Python scripts, shell commands, HTTP webhooks — anything that can receive a heartbeat signal. Adapters connect Paperclip to whatever execution environment you use.
 **What happens when an agent hits its budget limit?**
 The agent auto-pauses and new tasks are blocked. You get a soft warning at 80%. As the board, you can override the limit at any time.
 **Do agents run continuously?**
 By default, agents run on scheduled heartbeats and event-based triggers (task assignment, @-mentions). You can also hook in continuous agents like OpenClaw.
 **Can I run multiple companies?**
 Yes. A single deployment can run dozens of companies with complete data isolation. Useful for separate ventures, testing strategies in parallel, or templating org configs for reuse.
 **What does a typical setup look like?**
 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.
 <br/>
 ## Comparison
 |                            | Paperclip | Agent frameworks (LangChain, CrewAI) | Single-agent tools (Claude Code, Cursor) |
 | -------------------------- | --------- | ------------------------------------ | ---------------------------------------- |
 | Multi-agent orchestration  | Yes       | Partial                              | No                                       |
 | Org structure & hierarchy  | Yes       | No                                   | No                                       |
 | Cost control & budgets     | Yes       | No                                   | No                                       |
 | Goal alignment             | Yes       | No                                   | No                                       |
 | Governance & approvals     | Yes       | No                                   | No                                       |
 | Multi-company              | Yes       | No                                   | No                                       |
 | Agent-agnostic             | Yes       | Framework-locked                     | Single provider                          |
 | Ticket-based work tracking | Yes       | No                                   | No                                       |
 <br/>
 ## Development
 ```bash
 pnpm dev              # Full dev (API + UI)
 pnpm dev:server       # Server only
 pnpm dev:ui           # UI only
 pnpm build            # Build all
 pnpm typecheck        # Type checking
 pnpm test:run         # Run tests
 pnpm db:generate      # Generate DB migration
 pnpm db:migrate       # Apply migrations
 ```
 See [doc/DEVELOPING.md](doc/DEVELOPING.md) for the full development guide.
 <br/>
 ## Contributing
 We welcome contributions. See the [contributing guide](CONTRIBUTING.md) for details.
 <!-- TODO: add CONTRIBUTING.md -->
 <br/>
 ## Community
 - [Discord](https://discord.gg/paperclip) — chat, questions, show & tell
 - [GitHub Issues](https://github.com/paperclip-dev/paperclip/issues) — bugs and feature requests
 - [GitHub Discussions](https://github.com/paperclip-dev/paperclip/discussions) — ideas and RFC
 <br/>
 ## License
 MIT &copy; 2026 Paperclip
 <br/>
 ---
 <p align="center">
  <sub>Open source under MIT. Built for people who want to run companies, not babysit agents.</sub>
 </p>
--- a/doc/README-draft.md
+++ b/doc/README-draft.md
@@ -0,0 +1,78 @@
 # Instructions for writing the README.md
 The readme should be visually interesting, to the point, not too long.
 Use the copy from the website in cases where we need some.
 - gives the pitch why, e.g. from the homepage.
 ## Outline
 - image header up top
 - Paperclip
 - Manage autonomous AI Businesses
 - The open-source AI-agent orchestrator teams of agents that run companies
 - a video
 # What is it
 Paperclip is a node server & UI that orchestrates a team of agents to run businesses.
 Bring-your-own agents, assign goals, and track your agent's work and costs.
 It looks like a task manager but has specialized skills and agent coordination
 **It's high taste, and feels good to use**
 # Paperclip is right for you if:
 - You want to build autonomous companies
 - You want to coordinate many different types agents (OpenClaw, Codex, Claude, Cursor, etc.) to collaborate towards a common goal
 - You have 20 simultaneous Claude Code terminals open (and lose track of what everyone is working on)
 - You want to let your agents run autonomously 24/7, but still audit their work and chime in when needed
 - You want to monitor costs
 - You want a process for managing your agents that feels like using a task manager
 - You want to manage your autonomous businesses from your phone
 # What is not
 Paperclip is not:
 - a code review tool
 - opinionated about what agent you use
 # the problem
 If you want to be maximally effective with agents, you need to
 # quickstart
 # faq
 # comparison
 # contributing
 # community
 # license
 # footer
 ## Examples:
 - https://github.com/klawsh/klaw.sh - nice header, nice tables
  - what is it
  - the problem
  - quickstart
  - faq
  - comparison
  - contributing
  - community
  - license
  - footer
 - https://github.com/nearai/ironclaw - nice header
  - philosophy
 - https://github.com/TinyAGI/tinyclaw - nice header, nice video
 - https://github.com/ryoppippi/ccusage - nice header,
 - https://github.com/can1357/oh-my-pi - a little long
--- a/doc/assets/logos/bash.svg
+++ b/doc/assets/logos/bash.svg
@@ -0,0 +1,5 @@
 <svg viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
  <rect x="1" y="1" width="30" height="30" rx="6" fill="#2d2d2d"/>
  <polyline points="9,11 14,16 9,21" fill="none" stroke="#4af626" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
  <line x1="16" y1="21" x2="23" y2="21" stroke="#4af626" stroke-width="2" stroke-linecap="round"/>
 </svg>
--- a/doc/assets/logos/claude.svg
+++ b/doc/assets/logos/claude.svg
@@ -0,0 +1,3 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="#D97757">
  <path d="m3.127 10.604 3.135-1.76.053-.153-.053-.085H6.11l-.525-.032-1.791-.048-1.554-.065-1.505-.08-.38-.081L0 7.832l.036-.234.32-.214.455.04 1.009.069 1.513.105 1.097.064 1.626.17h.259l.036-.105-.089-.065-.068-.064-1.566-1.062-1.695-1.121-.887-.646-.48-.327-.243-.306-.104-.67.435-.48.585.04.15.04.593.456 1.267.981 1.654 1.218.242.202.097-.068.012-.049-.109-.181-.9-1.626-.96-1.655-.428-.686-.113-.411a2 2 0 0 1-.068-.484l.496-.674L4.446 0l.662.089.279.242.411.94.666 1.48 1.033 2.014.302.597.162.553.06.17h.105v-.097l.085-1.134.157-1.392.154-1.792.052-.504.25-.605.497-.327.387.186.319.456-.045.294-.19 1.23-.37 1.93-.243 1.29h.142l.161-.16.654-.868 1.097-1.372.484-.545.565-.601.363-.287h.686l.505.751-.226.775-.707.895-.585.759-.839 1.13-.524.904.048.072.125-.012 1.897-.403 1.024-.186 1.223-.21.553.258.06.263-.218.536-1.307.323-1.533.307-2.284.54-.028.02.032.04 1.029.098.44.024h1.077l2.005.15.525.346.315.424-.053.323-.807.411-3.631-.863-.872-.218h-.12v.073l.726.71 1.331 1.202 1.667 1.55.084.383-.214.302-.226-.032-1.464-1.101-.565-.497-1.28-1.077h-.084v.113l.295.432 1.557 2.34.08.718-.112.234-.404.141-.444-.08-.911-1.28-.94-1.44-.759-1.291-.093.053-.448 4.821-.21.246-.484.186-.403-.307-.214-.496.214-.98.258-1.28.21-1.016.19-1.263.112-.42-.008-.028-.092.012-.953 1.307-1.448 1.957-1.146 1.227-.274.109-.477-.247.045-.44.266-.39 1.586-2.018.956-1.25.617-.723-.004-.105h-.036l-4.212 2.736-.75.096-.324-.302.04-.496.154-.162 1.267-.871z"/>
 </svg>
--- a/doc/assets/logos/codex.svg
+++ b/doc/assets/logos/codex.svg
@@ -0,0 +1,4 @@
 <svg viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
  <circle cx="16" cy="16" r="15" fill="#000"/>
  <path d="M16 6L16 26M11 11L16 6L21 11M11 21L16 26L21 21" stroke="#fff" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/>
 </svg>
--- a/doc/assets/logos/cursor.svg
+++ b/doc/assets/logos/cursor.svg
@@ -0,0 +1,4 @@
 <svg viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg">
  <rect width="512" height="512" rx="128" fill="#14120b"/>
  <path d="m415.035 156.35-151.503-87.47c-4.865-2.81-10.868-2.81-15.733 0l-151.497 87.47c-4.09 2.36-6.615 6.73-6.615 11.46v176.38c0 4.73 2.525 9.1 6.615 11.46l151.504 87.47c4.865 2.81 10.868 2.81 15.733 0l151.504-87.47c4.089-2.36 6.614-6.73 6.614-11.46V167.81c0-4.73-2.525-9.1-6.614-11.46zm-9.516 18.53-146.255 253.32c-.988 1.71-3.599 1.01-3.599-.97V261.36c0-3.31-1.771-6.38-4.644-8.04l-143.645-82.93c-1.707-.99-1.01-3.6.968-3.6h292.509c4.154 0 6.75 4.5 4.673 8.1h-.007z" fill="#edecec"/>
 </svg>
--- a/doc/assets/logos/http.svg
+++ b/doc/assets/logos/http.svg
@@ -0,0 +1,7 @@
 <svg viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
  <circle cx="16" cy="16" r="14" stroke="#3b82f6" stroke-width="2"/>
  <ellipse cx="16" cy="16" rx="6" ry="14" stroke="#3b82f6" stroke-width="1.5"/>
  <line x1="2" y1="16" x2="30" y2="16" stroke="#3b82f6" stroke-width="1.5"/>
  <line x1="4" y1="9" x2="28" y2="9" stroke="#3b82f6" stroke-width="1" opacity="0.6"/>
  <line x1="4" y1="23" x2="28" y2="23" stroke="#3b82f6" stroke-width="1" opacity="0.6"/>
 </svg>
--- a/doc/assets/logos/openclaw.svg
+++ b/doc/assets/logos/openclaw.svg
@@ -0,0 +1,17 @@
 <svg viewBox="0 0 120 120" fill="none" xmlns="http://www.w3.org/2000/svg">
  <defs>
    <linearGradient id="lobster-grad" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" stop-color="#ff4d4d"/>
      <stop offset="100%" stop-color="#991b1b"/>
    </linearGradient>
  </defs>
  <path d="M60 10C30 10 15 35 15 55C15 75 30 95 45 100L45 110L55 110L55 100C55 100 60 102 65 100L65 110L75 110L75 100C90 95 105 75 105 55C105 35 90 10 60 10Z" fill="url(#lobster-grad)"/>
  <path d="M20 45C5 40 0 50 5 60C10 70 20 65 25 55C28 48 25 45 20 45Z" fill="url(#lobster-grad)"/>
  <path d="M100 45C115 40 120 50 115 60C110 70 100 65 95 55C92 48 95 45 100 45Z" fill="url(#lobster-grad)"/>
  <path d="M45 15Q35 5 30 8" stroke="#ff4d4d" stroke-width="3" stroke-linecap="round"/>
  <path d="M75 15Q85 5 90 8" stroke="#ff4d4d" stroke-width="3" stroke-linecap="round"/>
  <circle cx="45" cy="35" r="6" fill="#1a1a2e"/>
  <circle cx="75" cy="35" r="6" fill="#1a1a2e"/>
  <circle cx="46" cy="34" r="2.5" fill="#00e5cc"/>
  <circle cx="76" cy="34" r="2.5" fill="#00e5cc"/>
 </svg>