The Problem

Enterprises that want to run fully autonomous AI “companies” need a single control plane that can hire agents, assign goals, track work, and enforce budgets. Building that plumbing from scratch requires a server, a UI dashboard, and a CLI for automation, all tied to a common data model.

What This Does

paperclip delivers a ready‑made orchestration stack:

  • Server – a Node/Express API (server/src/app.ts, server/src/services/*) that stores company, agent, and goal data in SQLite via the packages/db schema.
  • UI – a React front‑end (ui/src/*) that consumes the API, provides context providers (ui/src/context/CompanyContext.tsx, ui/src/context/DialogContext.tsx) and renders dashboards (ui/src/App.tsx).
  • CLI – a command‑line tool (cli/src/index.ts, adapters in cli/src/adapters/*) for provisioning agents, running health checks, and executing one‑off tasks such as cli/src/commands/onboard.ts or cli/src/commands/heartbeat-run.ts.

Common utilities (ui/src/lib/utils.ts, packages/adapter-utils/src/server-utils.ts) are heavily imported (47 and 18 modules respectively), making them stability anchors.

How It Is Wired

Execution begins at the CLI (cli/src/index.ts) or the server (server/src/app.ts).

  • cli/src/index.ts parses sub‑commands and dispatches to runCommand (cli/src/commands/run.ts). For the onboard workflow this eventually calls cli/src/commands/onboard.ts → onboard → db.execute (via packages/db/src/backup.ts), touching the SQLite DB (2 DB‑access functions).
  • The HTTP adapter (cli/src/adapters/http/index.ts) implements a thin wrapper around fetch; its post method is used by many checks (cli/src/checks/*) and by the UI when calling the server.
  • The server entry createApp (server/src/app.ts) wires Express routes (server/src/routes/*) to service layers (server/src/services/*). A request such as GET /api/companies/:id flows: route → server/src/services/agents.ts (e.g., hashToken, createToken) → packages/db/src/schema/companies → SQLite file I/O (fs.readFileSync paths appear in cli/src/config/store.ts).
  • Core “hub” modules: ui/src/lib/utils.ts (exporting cn, date formatters) and ui/src/lib/queryKeys.ts are imported by 45–47 other files; changes here have the widest blast radius.
  • Circular imports involve 17 modules (e.g., cli/src/checks/index.ts ↔ ui/src/adapters/index.ts ↔ ui/src/components/AgentConfigForm.tsx). These cycles increase cognitive load and risk of runtime undefined imports.

All external effects are limited to:

  • Filesystem – config loading (readConfigFile), temporary paths (cli/src/config/home.ts), Dockerfile builds.
  • Network – HTTP client calls from the CLI (cli/src/client/http.ts).
  • Crypto – token generation in server/src/services/agents.ts.

No other runtime hooks (e.g., background workers) are visible in the static call graph.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/paperclip
cd paperclip

# Install dependencies (pnpm is the lockfile format)
pnpm install

# Build the UI (Vite/Webpack config lives in ui/; the repo uses pnpm workspaces)
pnpm --filter ui run build

# Start the stack with Docker (Dockerfile builds the server, docker-compose.yml wires UI, server, and DB)
docker compose up --build

Configuration – copy .env.example to .env and adjust DATABASE_URL, PORT, and any agent credentials required by the adapters (packages/adapters/claude-local, codex-local).

Running the CLI – invoke the entry script directly:

node ./cli/src/index.js onboard --company MyCo

The command reads configuration (cli/src/config/store.ts), validates it (cli/src/checks/config-check.ts), and writes the company record to SQLite.

Real‑World Use

A SaaS startup can deploy paperclip as a Docker service behind their internal network. When a new product line is approved, a product manager runs:

node cli/src/index.js onboard --company "NewProductCo"

The CLI creates a company entry, spins up a Claude Code agent via the claude-local adapter, and the UI instantly shows the new org chart and budget dashboard, allowing the manager to monitor cost and progress without writing code.

Code Health & Issues

  • HIGH – No LICENSE file (root).
  • HIGH – No CI workflow; 465 source files are never built/tested automatically.
  • HIGH – No Docker build gate; Dockerfile is present but never validated in CI.
  • MEDIUM – Dependabot/Renovate missing (12 manifest files).
  • MEDIUM – Base image not pinned (node:20-bookworm-slim).
  • MEDIUM – Dockerfile runs as root; no non‑root USER.
  • LOW – Repository convention files missing (.editorconfig, .gitattributes, formatter config).

Additional observations from the hygiene report: tests exist (under cli/src/__tests__), a lockfile is present, but secrets are committed in docs (docs/api/secrets.md). The import graph shows 17 circular dependencies and several oversized files (e.g., ui/src/components/AgentConfigForm.tsx > 1200 lines), which increase change risk.

The Bottom Line

paperclip provides a functional, Docker‑ready stack for orchestrating AI agents, with a clear separation between server, UI, and CLI. However, the codebase suffers from missing legal and operational scaffolding (license, CI, hardened Docker images) and several high‑impact architectural smells (hub modules, import cycles, large files). It is suited for teams comfortable with TypeScript monorepos who can invest in tightening the build pipeline and refactoring the identified hotspots.