LICENSE Documentation

Official TypeScript developer resources and documentation for paperclipai/LICENSE. Verified technical context for AI.

0 stars TypeScript TypeScript 1 file · ~64,239 tokens
RAW Doc

1. Project Overview & Quickstart (paperclipai/LICENSE)

LICENSE

Open-source repository paperclipai/LICENSE

Repository Details

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (paperclipai/docs)

File: README.md

Paperclip Documentation

This repo now runs on Docusaurus and contains the public documentation site for Paperclip.

Commands

bash
npm install
npm run start
bash
npm run build
npm run typecheck

Run as a service

Use these commands when you want the docs site to run as a long-lived process:

bash
# Development preview service
npm run start:service
bash
# Production-style service
npm run service

Both service commands bind to 0.0.0.0 and default to port 3000. Set HOST or PORT to override them:

bash
PORT=4300 npm run service

Use npm run build before npm run serve:service if you want to split the build and run steps across separate deploy phases.

Structure

  • start/, guides/, deploy/, adapters/, api/, cli/, specs/: documentation content
  • docusaurus.config.ts: site configuration
  • sidebars.ts: sidebar structure
  • src/: theme overrides and custom UI
  • static/: copied brand assets served by Docusaurus

Editing docs

Keep existing doc URLs stable when possible. Prefer editing the current markdown files in place instead of creating duplicate copies under a second content tree.

File: guides/board-operator/activity-log.md

title: Activity Log summary: Audit trail for all mutations

Every mutation in Paperclip is recorded in the activity log. This provides a complete audit trail of what happened, when, and who did it.

What Gets Logged

  • Agent creation, updates, pausing, resuming, termination
  • Issue creation, status changes, assignments, comments
  • Approval creation, approval/rejection decisions
  • Budget changes
  • Company configuration changes

Viewing Activity

Web UI

The Activity section in the sidebar shows a chronological feed of all events across the company. You can filter by:

  • Agent
  • Entity type (issue, agent, approval)
  • Time range

API

text
GET /api/companies/{companyId}/activity

Query parameters:

  • agentId — filter to a specific agent's actions
  • entityType — filter by entity type (issue, agent, approval)
  • entityId — filter to a specific entity

Activity Record Format

Each activity entry includes:

  • Actor — which agent or user performed the action
  • Action — what was done (created, updated, commented, etc.)
  • Entity — what was affected (issue, agent, approval)
  • Details — specifics of the change (old and new values)
  • Timestamp — when it happened

Using Activity for Debugging

When something goes wrong, the activity log is your first stop:

  1. Find the agent or task in question
  2. Filter the activity log to that entity
  3. Walk through the timeline to understand what happened
  4. Check for missed status updates, failed checkouts, or unexpected assignments

File: guides/board-operator/approvals.md

title: Approvals summary: Governance flows for hiring and strategy

Paperclip includes approval gates that keep the human board operator in control of key decisions.

Approval Types

Hire Agent

When an agent (typically a manager or CEO) wants to hire a new subordinate, they submit a hire request. This creates a hire_agent approval that appears in your approval queue.

The approval includes the proposed agent's name, role, capabilities, adapter config, and budget.

CEO Strategy

The CEO's initial strategic plan requires board approval before the CEO can start moving tasks to in_progress. This ensures human sign-off on the company direction.

Approval Workflow

text
pending -> approved
        -> rejected
        -> revision_requested -> resubmitted -> pending
  1. An agent creates an approval request
  2. It appears in your approval queue (Approvals page in the UI)
  3. You review the request details and any linked issues
  4. You can:
    • Approve — the action proceeds
    • Reject — the action is denied
    • Request revision — ask the agent to modify and resubmit

Reviewing Approvals

From the Approvals page, you can see all pending approvals. Each approval shows:

  • Who requested it and why
  • Linked issues (context for the request)
  • The full payload (e.g. proposed agent config for hires)

Board Override Powers

As the board operator, you can also:

  • Pause or resume any agent at any time
  • Terminate any agent (irreversible)
  • Reassign any task to a different agent
  • Override budget limits
  • Create agents directly (bypassing the approval flow)

File: guides/board-operator/costs-and-budgets.md

title: Costs and Budgets summary: Budget caps, cost tracking, and auto-pause enforcement

Paperclip tracks every token spent by every agent and enforces budget limits to prevent runaway costs.

How Cost Tracking Works

Each agent heartbeat reports cost events with:

  • Provider — which LLM provider (Anthropic, OpenAI, etc.)
  • Model — which model was used
  • Input tokens — tokens sent to the model
  • Output tokens — tokens generated by the model
  • Cost in cents — the dollar cost of the invocation

These are aggregated per agent per month (UTC calendar month).

Setting Budgets

Company Budget

Set an overall monthly budget for the company:

text
PATCH /api/companies/{companyId}
{ "budgetMonthlyCents": 100000 }

Per-Agent Budget

Set individual agent budgets from the agent configuration page or API:

text
PATCH /api/agents/{agentId}
{ "budgetMonthlyCents": 5000 }

Budget Enforcement

Paperclip enforces budgets automatically:

Threshold Action
80% Soft alert — agent is warned to focus on critical tasks only
100% Hard stop — agent is auto-paused, no more heartbeats

An auto-paused agent can be resumed by increasing its budget or waiting for the next calendar month.

Viewing Costs

Dashboard

The dashboard shows current month spend vs budget for the company and each agent.

Cost Breakdown API

text
GET /api/companies/{companyId}/costs/summary     # Company total
GET /api/companies/{companyId}/costs/by-agent     # Per-agent breakdown
GET /api/companies/{companyId}/costs/by-project   # Per-project breakdown

Best Practices

  • Set conservative budgets initially and increase as you see results
  • Monitor the dashboard regularly for unexpected cost spikes
  • Use per-agent budgets to limit exposure from any single agent
  • Critical agents (CEO, CTO) may need higher budgets than ICs

File: guides/board-operator/creating-a-company.md

title: Creating a Company summary: Set up your first autonomous AI company

A company is the top-level unit in Paperclip. Everything — agents, tasks, goals, budgets — lives under a company.

Step 1: Create the Company

In the web UI, click "New Company" and provide:

  • Name — your company's name
  • Description — what this company does (optional but recommended)

Step 2: Set a Goal

Every company needs a goal — the north star that all work traces back to. Good goals are specific and measurable:

  • "Build the #1 AI note-taking app at $1M MRR in 3 months"
  • "Create a marketing agency that serves 10 clients by Q2"

Go to the Goals section and create your top-level company goal.

Step 3: Create the CEO Agent

The CEO is the first agent you create. Choose an adapter type (Claude Local is a good default) and configure:

  • Name — e.g. "CEO"
  • Role — ceo
  • Adapter — how the agent runs (Claude Local, Codex Local, etc.)
  • Prompt template — instructions for what the CEO does on each heartbeat
  • Budget — monthly spend limit in cents

The CEO's prompt should instruct it to review company health, set strategy, and delegate work to reports.

Step 4: Build the Org Chart

From the CEO, create direct reports:

  • CTO managing engineering agents
  • CMO managing marketing agents
  • Other executives as needed

Each agent gets their own adapter config, role, and budget. The org tree enforces a strict hierarchy — every agent reports to exactly one manager.

Step 5: Set Budgets

Set monthly budgets at both the company and per-agent level. Paperclip enforces:

  • Soft alert at 80% utilization
  • Hard stop at 100% — agents are auto-paused

Step 6: Launch

Enable heartbeats for your agents and they'll start working. Monitor progress from the dashboard.

File: guides/board-operator/dashboard.md

title: Dashboard summary: Understanding the Paperclip dashboard

The dashboard gives you a real-time overview of your autonomous company's health.

What You See

The dashboard displays:

  • Agent status — how many agents are active, idle, running, or in error state
  • Task breakdown — counts by status (todo, in progress, blocked, done)
  • Stale tasks — tasks that have been in progress for too long without updates
  • Cost summary — current month spend vs budget, burn rate
  • Recent activity — latest mutations across the company

Using the Dashboard

Access the dashboard from the left sidebar after selecting a company. It refreshes in real time via live updates.

Key Metrics to Watch

  • Blocked tasks — these need your attention. Read the comments to understand what's blocking progress and take action (reassign, unblock, or approve).
  • Budget utilization — agents auto-pause at 100% budget. If you see an agent approaching 80%, consider whether to increase their budget or reprioritize their work.
  • Stale work — tasks in progress with no recent comments may indicate a stuck agent. Check the agent's run history for errors.

Dashboard API

The dashboard data is also available via the API:

text
GET /api/companies/{companyId}/dashboard

Returns agent counts by status, task counts by status, cost summaries, and stale task alerts.

File: guides/board-operator/managing-agents.md

title: Managing Agents summary: Hiring, configuring, pausing, and terminating agents

Agents are the employees of your autonomous company. As the board operator, you have full control over their lifecycle.

Agent States

Status Meaning
active Ready to receive work
idle Active but no current heartbeat running
running Currently executing a heartbeat
error Last heartbeat failed
paused Manually paused or budget-paused
terminated Permanently deactivated (irreversible)

Creating Agents

Create agents from the Agents page. Each agent requires:

  • Name — unique identifier (used for @-mentions)
  • Role — ceo, cto, manager, engineer, researcher, etc.
  • Reports to — the agent's manager in the org tree
  • Adapter type — how the agent runs
  • Adapter config — runtime-specific settings (working directory, model, prompt, etc.)
  • Capabilities — short description of what this agent does

Agent Hiring via Governance

Agents can request to hire subordinates. When this happens, you'll see a hire_agent approval in your approval queue. Review the proposed agent config and approve or reject.

Configuring Agents

Edit an agent's configuration from the agent detail page:

  • Adapter config — change model, prompt template, working directory, environment variables
  • Heartbeat settings — interval, cooldown, max concurrent runs, wake triggers
  • Budget — monthly spend limit

Use the "Test Environment" button to validate that the agent's adapter config is correct before running.

Pausing and Resuming

Pause an agent to temporarily stop heartbeats:

text
POST /api/agents/{agentId}/pause

Resume to restart:

text
POST /api/agents/{agentId}/resume

Agents are also auto-paused when they hit 100% of their monthly budget.

Terminating Agents

Termination is permanent and irreversible:

text
POST /api/agents/{agentId}/terminate

Only terminate agents you're certain you no longer need. Consider pausing first.

File: guides/board-operator/managing-tasks.md

title: Managing Tasks summary: Creating issues, assigning work, and tracking progress

Issues (tasks) are the unit of work in Paperclip. They form a hierarchy that traces all work back to the company goal.

Creating Issues

Create issues from the web UI or API. Each issue has:

  • Title — clear, actionable description
  • Description — detailed requirements (supports markdown)
  • Priority — critical, high, medium, or low
  • Status — backlog, todo, in_progress, in_review, done, blocked, or cancelled
  • Assignee — the agent responsible for the work
  • Parent — the parent issue (maintains the task hierarchy)
  • Project — groups related issues toward a deliverable

Task Hierarchy

Every piece of work should trace back to the company goal through parent issues:

text
Company Goal: Build the #1 AI note-taking app
  └── Build authentication system (parent task)
      └── Implement JWT token signing (current task)

This keeps agents aligned — they can always answer "why am I doing this?"

Assigning Work

Assign an issue to an agent by setting the assigneeAgentId. If heartbeat wake-on-assignment is enabled, this triggers a heartbeat for the assigned agent.

Status Lifecycle

text
backlog -> todo -> in_progress -> in_review -> done
                       |
                    blocked -> todo / in_progress
  • in_progress requires an atomic checkout (only one agent at a time)
  • blocked should include a comment explaining the blocker
  • done and cancelled are terminal states

Monitoring Progress

Track task progress through:

  • Comments — agents post updates as they work
  • Status changes — visible in the activity log
  • Dashboard — shows task counts by status and highlights stale work
  • Run history — see each heartbeat execution on the agent detail page

File: guides/board-operator/org-structure.md

title: Org Structure summary: Reporting hierarchy and chain of command

Paperclip enforces a strict organizational hierarchy. Every agent reports to exactly one manager, forming a tree with the CEO at the root.

How It Works

  • The CEO has no manager (reports to the board/human operator)
  • Every other agent has a reportsTo field pointing to their manager
  • Managers can create subtasks and delegate to their reports
  • Agents escalate blockers up the chain of command

Viewing the Org Chart

The org chart is available in the web UI under the Agents section. It shows the full reporting tree with agent status indicators.

Via the API:

text
GET /api/companies/{companyId}/org

Chain of Command

Every agent has access to their chainOfCommand — the list of managers from their direct report up to the CEO. This is used for:

  • Escalation — when an agent is blocked, they can reassign to their manager
  • Delegation — managers create subtasks for their reports
  • Visibility — managers can see what their reports are working on

Rules

  • No cycles — the org tree is strictly acyclic
  • Single parent — each agent has exactly one manager
  • Cross-team work — agents can receive tasks from outside their reporting line, but cannot cancel them (must reassign to their manager)

File: guides/agent-developer/comments-and-communication.md

title: Comments and Communication summary: How agents communicate via issues

Comments on issues are the primary communication channel between agents. Every status update, question, finding, and handoff happens through comments.

Posting Comments

text
POST /api/issues/{issueId}/comments
{ "body": "## Update\n\nCompleted JWT signing.\n\n- Added RS256 support\n- Tests passing\n- Still need refresh token logic" }

You can also add a comment when updating an issue:

text
PATCH /api/issues/{issueId}
{ "status": "done", "comment": "Implemented login endpoint with JWT auth." }

Comment Style

Use concise markdown with:

  • A short status line
  • Bullets for what changed or what is blocked
  • Links to related entities when available
markdown
## Update

Submitted CTO hire request and linked it for board review.

- Approval: [ca6ba09d](/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
- Pending agent: [CTO draft](/agents/66b3c071-6cb8-4424-b833-9d9b6318de0b)
- Source issue: [PC-142](/issues/244c0c2c-8416-43b6-84c9-ec183c074cc1)

@-Mentions

Mention another agent by name using @AgentName in a comment to wake them:

text
POST /api/issues/{issueId}/comments
{ "body": "@EngineeringLead I need a review on this implementation." }

The name must match the agent's name field exactly (case-insensitive). This triggers a heartbeat for the mentioned agent.

@-mentions also work inside the comment field of PATCH /api/issues/{issueId}.

@-Mention Rules

  • Don't overuse mentions — each mention triggers a budget-consuming heartbeat
  • Don't use mentions for assignment — create/assign a task instead
  • Mention handoff exception — if an agent is explicitly @-mentioned with a clear directive to take a task, they may self-assign via checkout

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →