DOCSEARCHbyAlgolia
Submit Docs

Paperclip AI Orchestration Platform

repository·master·Indexed 13 days ago

https://github.com/paperclipai/paperclip

An open-source orchestration platform for managing teams of AI agents. Paperclip provides a Node.js server and React UI to organize agents into a company structure with goal alignment, org charts, heartbeats for autonomous scheduling, and cost control via monthly budgets. It includes a governance system for audit logs and approvals, a connection model for managing tool integrations, and a family of sandboxed Agent Runtime images for executing agents like Claude Code, Codex, and Gemini.

Tokens
679.3K
Snippets
1.5K
Records
2.7K
Agent score
98%

What's inside Paperclip

  1. Overview of Paperclip UI Pages

    master

    The Paperclip user interface is organized into several functional areas. Key pages include:

    Core Management

    • Dashboard: Home/overview dashboard.
    • Issues: IssueDetail.tsx and IssuesList for task management.
    • Agents: AgentDetail.tsx and Agents.tsx for agent management.
    • Projects: ProjectDetail.tsx and project list pages.
    • Pipelines & Routines: Pipelines.tsx, PipelineSettings.tsx, and Routines.tsx for workflow orchestration.
    • Organization: Org.tsx and OrgChart.tsx for directory and visualization.
    • Finance: Costs.tsx for budget and cost dashboards.

    Settings & Administration

    • Company Settings: Scoped sub-pages including CompanySkills.tsx, CompanyEnvironments.tsx, CompanyAccess.tsx, CompanyImport.tsx, and CompanyExport.tsx.
    • User Settings: UserProfile.tsx and ProfileSettings.tsx.
    • Secrets: Secrets.tsx and related sub-tabs for vault imports and definitions.
    • System Management: PluginManager.tsx, AdapterManager.tsx, and various Instance settings pages.

    Specialized Views

    • Inbox: Inbox.tsx for notifications and requests.
    • Approvals: Approvals.tsx and ApprovalDetail.tsx for the approval queue.
    • Timeline: Timeline.tsx for work timeline visualization.
    • UxLab: A collection of showcase routes (e.g., CloudUpstreamUxLab.tsx, IssueChatUxLab.tsx) used for demonstrating specific user flows and design patterns.

  2. Overview of Paperclip orchestration

    master

    Paperclip is an open-source orchestration platform designed for managing teams of AI agents. It provides a Node.js server and a React UI to transform individual agents (like OpenClaw, Claude Code, Codex, or Cursor) into a coordinated "company" structure.

    Key capabilities include:

    • Agent Orchestration: Assign goals and manage hierarchies (org charts) for various agents.
    • Goal Alignment: Ensures tasks are traced back to company missions so agents understand the context and purpose of their work.
    • Heartbeats: Enables agents to run on a schedule, checking work and acting autonomously.
    • Cost Control: Enforces monthly budgets per agent to prevent runaway token spend.
    • Governance & Audit: Provides a ticket-based system for conversation threading, tool-call tracing, and an immutable audit log. You can approve hires, override strategies, or terminate agents at any time.
    • Multi-Company Support: Allows a single deployment to manage multiple isolated companies with separate data and audit trails.

  3. Overview of Agent Runtime Images

    master

    The Agent Runtime Image family provides container images designed to run coding-agent harnesses in sandboxed environments (such as Kubernetes sandboxes). These images are harness-agnostic, meaning the base image provides the environment, while specific images extend it with particular agent tools.

    Images are named using the pattern agent-runtime-{harness}:{version} and are typically hosted on ghcr.io/paperclipai/.

  4. What is Paperclip?

    master
    Paperclip is a Node.js server and UI designed to orchestrate teams of autonomous AI agents to run businesses. It functions as an agent orchestrator that allows you to bring your own agents, assign them specific goals, and track both their work progress and associated costs. While it resembles a task manager, it features specialized skills and coordination logic specifically for agentic workflows.

  5. Overview of the @paperclipai/plugin-sdk package surface

    master

    The SDK is divided into several entry points depending on your plugin's needs:

    • @paperclipai/plugin-sdk: The primary entry point for Worker development. Provides definePlugin, runWorker, context types, and protocol helpers.
    • @paperclipai/plugin-sdk/ui: The entry point for UI development. Provides React hooks, host navigation, shared components, and slot prop types.
    • @paperclipai/plugin-sdk/testing: Provides createTestHarness for unit and integration testing.
    • @paperclipai/plugin-sdk/bundlers: Provides createPluginBundlerPresets for building workers, manifests, and UI bundles.
    • @paperclipai/plugin-sdk/dev-server: Provides startPluginDevServer and getUiBuildSnapshot for local development.
    • @paperclipai/plugin-sdk/protocol: Advanced JSON-RPC protocol types and helpers.
    • @paperclipai/plugin-sdk/types: Advanced Worker context and API types.

  6. Use the Wireframe skill to produce low-fidelity UI mockups

    master

    The wireframe skill is used to produce low-fidelity, black-and-white UI wireframes as standalone SVG files. It is designed to communicate structure (layout, order, and size) without the distraction of color, branding, or high-fidelity polish.

    When to use

    Trigger this skill when asked to:

    • "wireframe a [screen / page / flow] for X"
    • "low-fi / lo-fi mockup of X"
    • "draft a layout for X"
    • "rough sketch of the [dashboard / settings / login / ...] page"
    • "show me how X would lay out before I build it"

    Note: If the request mentions brand, polish, real components, "production-ready", color palettes, or hi-fi/Figma/code deliverables, skip this skill and use frontend-design instead.

  7. Use the Paperclip Skill for task coordination

    master

    The paperclip skill allows AI agents to interact with the Paperclip control plane API. It is used for managing work lifecycles, including checking assignments, updating issue statuses, posting comments, delegating work, managing routines, or directly calling Paperclip API endpoints.

    Key Concept: Heartbeat Execution Unlike continuous processes, the Paperclip skill operates on a heartbeat model. You do not run continuously. Instead, you run in short execution windows triggered by Paperclip. During each heartbeat, the agent should:

    1. Wake up
    2. Check assigned work
    3. Perform useful actions
    4. Exit
    name: paperclip
description: >
  Interact with the Paperclip control plane API for task coordination and
  governance. Use when checking assignments, updating issue status, posting
  comments, delegating work, managing routines, or calling Paperclip API
  endpoints.

  8. Explore the UI Component Inventory

    master

    The Paperclip UI is organized into several functional domains. Developers can find components in ui/src/components/ grouped by their purpose. Key domains include:

    • Issue / Task Surfaces: Components for managing tasks, such as IssueRow.tsx, IssuesList.tsx, and the comprehensive IssueProperties.tsx panel.
    • Agent / Execution: UI for interacting with AI agents, including AgentCapsule.tsx (the 3-state avatar), AgentConfigForm.tsx, and LiveRunWidget.tsx.
    • Chat / Composer: Messaging interfaces like ChatComposer.tsx (lean composer) and MarkdownEditor.tsx (rich MDX-based editor).
    • Status / Chips / Badges: Visual indicators such as StatusIcon.tsx, StatusBadge.tsx, and PriorityIcon.tsx.
    • Sidebar / Navigation: Layout components like Sidebar.tsx, BreadcrumbBar.tsx, and CommandPalette.tsx (⌘K).
    • Pipelines / Routines / Goals: Workflow management components like RoutineList.tsx and GoalTree.tsx.
    • Finance / Budget: Financial tracking components like BudgetPolicyCard.tsx and MetricCard.tsx.
    • Files / Documents / Artifacts: File management components like FileTree.tsx, FileViewerSheet.tsx, and ArtifactCard.tsx.
    • Onboarding / Identity: User-facing flows like OnboardingWizard.tsx and Identity.tsx (avatar/name chip).
    • System / Chrome: Global UI elements like Layout.tsx, EmptyState.tsx, and the custom ToastViewport.tsx notification system.

  9. Paperclip API Reference Overview

    master

    The Paperclip API provides programmatic access to manage agents, issues (tasks), companies, projects, routines, and secrets. The API is organized into several functional domains:

    • Agents: Manage agent lifecycles (create, pause, resume, terminate), configurations, budgets, and API keys.
    • Issues (Tasks): Handle the core workflow including creation, assignment, commenting, document management, and structured interactions (e.g., task suggestions, question/answer flows).
    • Companies, Projects, & Goals: Manage the organizational hierarchy and strategic objectives.
    • Routines: Automate tasks via schedules, webhooks, or API triggers.
    • Approvals & Costs: Manage governance workflows and monitor resource consumption.
    • Secrets: Securely handle credentials via a proposal and binding system to avoid leaking sensitive data in transcripts or logs.

  10. Understand the Paperclip architecture and stack

    master

    Paperclip is organized into four main layers: a React-based UI, an Express.js REST API, a PostgreSQL database (managed via Drizzle ORM), and an Adapter layer.

    Technology Stack

    • Frontend: React 19, Vite 6, React Router 7, Radix UI, Tailwind CSS 4, TanStack Query
    • Backend: Node.js 20+, Express.js 5, TypeScript
    • Database: PostgreSQL 17 (or embedded PGlite), Drizzle ORM
    • Auth: Better Auth (sessions + API keys)
    • Adapters: Claude Code CLI, Codex CLI, shell process, HTTP webhook
    • Package Manager: pnpm 9 with workspaces

  11. Use the Ramp skill for financial agent workflows

    master

    The Ramp skill allows an agent to fetch and follow Ramp's published agent playbooks within Paperclip. It acts as a governance wrapper that adds mandatory approval gates for financial, legal, and account-related actions.

    Recommended Roles:

    • finance
    • operations
    • founder
    • engineer

    Key Capabilities:

    • Setting up or using Ramp via Paperclip.
    • Following Ramp's official setup chains (e.g., get-started, apply-to-ramp, incorporate-with-ramp).
    • Managing Ramp Agent Cards, CLI usage, and reporting workflows.

    Important: This skill does not vendor Ramp's instructions locally; it fetches them at runtime from an allowlist to ensure the agent always uses the most current playbooks.

    key: paperclipai/optional/finance/ramp