Launch an AI Company with Paperclip

Orchestrate multiple AI agents with roles, budgets, and governance.

Introduction

30 Second Summary

Real companies have org charts, defined roles, and budgets that keep everyone aligned. What if you could give AI agents that same structure and let them coordinate work on their own?

In this project, you will launch an AI company called "DevTools Weekly" using Paperclip, an open-source platform for orchestrating multiple AI agents. You will hire a CEO agent and a Writer agent, give them budgets and reporting lines, and watch them collaborate to produce a technical newsletter.

What You'll Build

A locally-running AI company powered by Paperclip, with two agents coordinating through an org chart to plan and draft a developer tools newsletter.

By the end of this project, you'll have:

  • A running Paperclip server on your Mac with an embedded database and a dashboard at localhost:3100.
  • A two-agent org chart with a CEO agent that plans work and a Writer agent that produces drafts, connected through heartbeat-driven execution and delegation.
  • Hands-on experience with budgets, governance approvals, and the full audit trail that tracks every decision your agents make.
  • A secret mission to add a third Editor agent that reviews the Writer's output before it reaches the CEO.

Are there any prerequisites?

You need the Claude Code CLI installed and authenticated with an Anthropic subscription. You should also be comfortable running basic commands in the terminal. The first step will walk you through installing Node.js 20+ and pnpm 9.15+ if you do not already have them.

Install Paperclip and Prerequisites

Running a single AI agent is useful, but running a team of agents that coordinate, delegate, and report to each other requires a platform. Paperclip is an open-source orchestration platform that runs entirely on your machine. It gives your AI agents structure, budgets, and governance.

In this step, you'll install the prerequisites and launch Paperclip with a single command. By the end, you'll have a running server with a dashboard ready for your first company.

In this step, get ready to:
  • Verify Node.js and install pnpm.
  • Run the Paperclip onboarding command to set up the server and database.
  • Open the Paperclip dashboard in your browser.
Verify Node.js and install pnpm

Paperclip requires Node.js 20+ and the pnpm package manager at version 9.15+. Let's make sure both are installed before moving on.

  • Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
  • Type Terminal and press Enter to open it.
  • Check your Node.js version by running this command:
node --version

I see v20 or higher

Your Node.js version is good to go. Skip ahead to the pnpm install below.

Command not found or below v20

You need to install or upgrade Node.js. If you already have nvm (Node Version Manager) installed, run this command:

nvm install 20

If you don't have nvm, download Node.js directly from the official Node.js website. Choose the LTS version (v20 or higher), then run the installer.

  • After installing, close and reopen your terminal.
  • Run node --version again to confirm you see v20 or higher.
  • Install pnpm globally by running this command:
npm install -g pnpm
  • Verify the install by running:
pnpm --version

I see v9.15 or higher

pnpm is ready. You have everything Paperclip needs.

Command not found

The global install may not have added pnpm to your system PATH. Try closing and reopening your terminal, then run pnpm --version again.

If it still fails, try running the install with sudo (macOS/Linux) for elevated permissions:

sudo npm install -g pnpm
Run the Paperclip onboarding command

Paperclip bundles everything into a single onboarding command. It downloads the platform, installs dependencies, sets up an embedded database, and starts the server.

Use a regular terminal, not Claude Code

If you run the onboarding command inside a Claude Code terminal session, the spawned agent processes will fail. Claude Code sets environment variables that prevent nested sessions.

Make sure you are running this in a regular Terminal window, not inside Claude Code.

  • Launch the Paperclip onboarding process by running this command:
npx paperclipai onboard --yes

What does this command do?

  • npx paperclipai downloads and runs the Paperclip CLI without permanently installing it.
  • onboard triggers the full setup process: downloading the platform, installing dependencies, and initializing the database.
  • --yes accepts sensible defaults so you skip interactive prompts.
  • The embedded database is PGlite (a lightweight PostgreSQL). No external database server or account is needed.

This command may take a minute or two to complete. When it finishes, you should see a message in your terminal confirming the server is running at http://localhost:3100.

Server not starting?

  • If you see a port conflict error, another process is using port 3100. Close whatever app is using that port and try again.
  • If the download fails, check your internet connection. The command needs to pull packages from npm.
  • Run paperclipai doctor --repair to auto-diagnose and fix common setup issues.
  • Help me troubleshoot my Paperclip installation.
Open the Paperclip dashboard
  • Open your web browser.
  • Navigate to http://localhost:3100.

You should see the Paperclip dashboard load with an Onboarding Wizard. No login is required.

Why is there no login screen?

Paperclip runs in "trusted local loopback" mode by default. Since the server is only accessible from your own machine, it skips authentication and logs you in as a synthetic "Board" user. You are the board of directors.

Dashboard not loading?

  • Switch back to your terminal and make sure the Paperclip server is still running. If the process stopped, run npx paperclipai onboard --yes again.
  • Make sure the URL is exactly http://localhost:3100 (not https).
  • Help me get the Paperclip dashboard running in my browser.

Pro tip: keep your terminal open

The Paperclip server runs as a foreground process in your terminal. If you close the terminal window, the server stops and the dashboard becomes unreachable. Keep this terminal window open for the rest of the project.

Your Paperclip server is up and the dashboard is ready. Next up, you'll create your first AI company and give it a mission.

Create Your AI Company

Your Paperclip server is up and the dashboard is waiting for you. It's time to create the company that your agents will work inside.

A company in Paperclip is the top-level container for everything. It defines the mission, holds the org chart, tracks budgets, and logs every action your agents take.

In this step, get ready to:
  • Create a new company called "DevTools Weekly" in the Paperclip dashboard.
  • Define a company-level goal that turns the mission into actionable work.
Create the company in the dashboard

Every agent, goal, and task in Paperclip lives inside a company. The Onboarding Wizard at http://localhost:3100 walks you through creating your first one.

  • Click Add Company in the Onboarding Wizard.
  • Enter DevTools Weekly in the Name field.
  • In the Mission field, enter Produce one high-quality technical newsletter issue about developer tools every week.
  • Set the Timezone to your local timezone.
  • Click Create to save your company.

Why does the mission matter?

The mission is not decorative text. Every task your agents execute traces back to this mission statement. It gives agents context for why they are doing the work.

A vague mission leads to unfocused agent behavior. A specific, measurable mission keeps every agent aligned toward the same outcome.

You should see DevTools Weekly listed in your company dashboard with the mission statement displayed below the company name.

Don't see your company?

  • Make sure your Paperclip server is still running in the terminal window from Step 1. If it stopped, rerun the start command from that step.
  • Check that you entered text in all required fields before clicking Create. Empty fields can silently prevent the form from submitting.
  • My Paperclip dashboard isn't showing my new company.

Pro tip: UI labels may vary

Exact button and field labels in the Onboarding Wizard may differ slightly depending on your Paperclip version. Look for the option to create a new company if the labels do not match exactly.

Define your company goal

Your company now has a mission, but a mission alone is too broad for agents to act on. Goals make the mission actionable by defining specific, time-bound outcomes.

  • Navigate to your DevTools Weekly company in the dashboard.
  • Find and click the option to add a new goal.
  • Enter the following goal: Publish the first newsletter issue within 24 hours covering the top 3 developer tool launches this week.
  • Save the goal.

How do goals and missions connect?

Goals in Paperclip create a hierarchy. Every task traces back to a goal, and every goal traces back to the company mission.

This hierarchy is how Paperclip keeps agents focused. When an agent picks up a task, it can trace exactly why that task matters all the way back to the company's reason for existing.

You should see your goal listed under the DevTools Weekly company. The goal is now ready for agents to work toward once you hire them in the next step.

Your company has a name, a mission, and a clear first goal. Next up, you'll hire your first AI agent and watch it start planning how to achieve that goal.

Hire Your CEO Agent

Your AI company is set up. DevTools Weekly has a mission statement and a goal that turns that mission into a concrete, measurable target.

A company without people is just paperwork. In this step, you'll hire your first AI agent, give it the CEO role, and watch it wake up and start planning.

In this step, get ready to:
  • Add a CEO agent using the Claude Code adapter.
  • Write a system prompt that defines the CEO's responsibilities.
  • Approve the hire through governance and trigger the agent's first heartbeat.
Add your first agent from the dashboard

Each agent in Paperclip connects to an AI provider through an adapter. Since you already have Claude Code installed, you'll use the claude_local adapter to power your CEO.

  • In the Paperclip dashboard at http://localhost:3100, open your DevTools Weekly company.
  • Click Hire Agent.
  • Select Claude Code as the adapter type.
  • Enter CEO in the Role field.
  • Enter Chief Executive Officer in the Title field.
  • Set the agent to report to the Board. That's you.
  • Set the heartbeat schedule to every 30 minutes.
  • Set the monthly budget to $5.

Pro tip: field labels may look different

Paperclip is actively developed. The exact field labels and layout in the agent creation form may differ slightly from what's described here. Look for the matching concept (adapter selection, role, reporting line, heartbeat interval, budget) if a label doesn't match exactly.

What is a heartbeat?

Agents in Paperclip don't run continuously. Instead, they wake up on a timer called a heartbeat.

  • On each heartbeat, the agent checks for assigned work, executes tasks, reports results, and goes back to sleep.
  • A 30-minute schedule means your CEO checks in twice per hour.
  • This keeps compute costs predictable and prevents agents from running in endless loops.
Write the CEO's system prompt

The system prompt is the instruction set your agent reads every time it wakes up. It defines who the agent is, what it's responsible for, and how it should behave.

  • In the agent configuration, find the System Prompt field.
  • Paste the following prompt:
You are the CEO of DevTools Weekly. Your mission is to produce one high-quality technical newsletter issue about developer tools every week.

Your responsibilities:
- Break the company mission into actionable tasks
- Delegate content production to the Writer agent
- Review completed drafts for quality and relevance
- Escalate blockers to the board when you cannot resolve them

Newsletter standards:
- Each issue covers the top 3 developer tool launches or updates from this week
- Each section is 150-200 words
- Include links to official sources
- Maintain a professional but approachable tone

What does this prompt do?

  • The first line anchors the agent to its role and the company's mission.
  • The responsibilities section gives the CEO four clear jobs: planning, delegating, reviewing, and escalating.
  • The newsletter standards section sets quality guardrails so the agent's output stays consistent.
  • Every time the CEO's heartbeat fires, it re-reads this prompt to stay aligned with its role. The more specific you are here, the better the agent performs.
  • Leave the agent configuration open. You'll finalize everything when you approve the hire in the next substep.
Approve the hire and trigger the first heartbeat

Paperclip requires board approval before any agent can start working. You are the board. This governance layer ensures no agent runs without your explicit authorization.

  • Review the CEO agent's full configuration in the dashboard.
  • Click Approve Hire to authorize the agent.

What is governance in Paperclip?

Governance is the set of controls that keeps agents accountable. Agent hires need your approval. Budget limits are enforced automatically. Every action is logged in the audit trail.

These guardrails exist so you can run autonomous agents without losing control over what they do.

Now that the hire is approved, you can trigger the CEO's first heartbeat manually instead of waiting 30 minutes.

  • Click the Trigger Heartbeat button on the CEO agent's page.

You should see the CEO agent wake up, read its mission, and start planning. The dashboard updates in real time with the agent's activity, including what it decided to do and how much the run cost.

Agent not responding after the heartbeat?

  • Make sure Paperclip was started from a regular terminal window, not from inside a Claude Code session. Running Paperclip inside Claude Code causes child agent processes to fail.
  • Verify that your Claude Code CLI is authenticated. Open a separate terminal and run claude --version to confirm it responds.
  • Check the agent's run history in the dashboard for error messages. Click on the CEO agent, then look for recent runs.

Help me debug why my CEO agent isn't responding to heartbeats in Paperclip.

Your CEO is on the job. Next, you'll expand the org chart by hiring a Writer agent who reports directly to the CEO.

Build the Org Chart with a Writer Agent

Your CEO agent is alive and planning. But a CEO with no team is just talking to itself. For delegation to work, there needs to be someone on the other end of the org chart to receive the work.

In this step, you will hire a Writer agent and place it under the CEO in the reporting hierarchy. When the CEO breaks tasks down, those sub-tasks flow down the org chart to the Writer automatically. This is where Paperclip stops being a task manager and starts being an orchestration platform.

In this step, get ready to:
  • Hire a Writer agent that reports to the CEO.
  • Configure the Writer's system prompt and approve the hire through governance.
  • Assign a task and watch delegation flow through the org chart.
Hire a Writer agent

Your CEO needs a direct report. The Writer agent will handle the actual content production, receiving tasks from the CEO and submitting completed drafts back up the chain.

  • In the Paperclip dashboard at http://localhost:3100, navigate to your DevTools Weekly company page.
  • Click Hire Agent to open the agent creation form.
  • Select Claude Code (claude_local) as the adapter type.
  • Enter Writer in the Name field.
  • Set the Role to writer.
  • Set the Title to Staff Writer.
  • In the Reports to field, select your CEO agent. This is the critical step. The CEO is the Writer's manager in the org chart.
  • Set the monthly budget to $3 (300 cents).

Why does the reporting line matter?

The Reports to field is not cosmetic. It defines who can delegate tasks to this agent and who receives completed work. When the CEO creates sub-tasks, Paperclip checks the org chart to determine which agents are eligible to receive them. An agent that reports to the Board (you) would never receive delegated work from the CEO.

Pro tip: keep budgets tight while learning

A $3/month budget is plenty for a Writer agent during testing. Paperclip enforces a hard stop at 100% of the budget. The agent is auto-paused when it hits the limit, so there is no risk of runaway costs.

Configure the Writer's system prompt and approve the hire

The system prompt defines what the Writer does on every heartbeat. A vague prompt produces vague output. A specific prompt produces focused, reviewable drafts.

  • In the Adapter config section of the agent creation form, find the Prompt template field.
  • Write a prompt that covers these responsibilities:
  • Fill in the Capabilities field with a short description of what the Writer does, such as Research developer tools and write newsletter content.
  • Submit the hire request.

What makes a good agent prompt?

Think of the system prompt as a job description the agent re-reads every time it wakes up. Name the output format (newsletter sections), the quality bar (150 to 200 words, must include links), and the handoff point (submit to CEO for review). The more concrete your prompt, the less the agent improvises.

Since you are the board, the hire requires your approval before the agent can start receiving work.

  • Check your Inbox in the dashboard. You should see a pending hire_agent approval for the Writer.
  • Review the proposed agent configuration.
  • Click Approve to confirm the hire.

Once approved, the Writer appears in the org chart under the CEO. You should see two agents in your company's agent list.

What is governance in Paperclip?

Governance is the approval layer that keeps you in control. No agent can be hired, no strategy can be executed, and no budget can be changed without board authorization. You are the board of directors. Agents work within the boundaries you set.

Don't see the approval in your Inbox?

Make sure you submitted the hire request by clicking the submit button at the bottom of the agent creation form. If the request was submitted successfully, refresh the dashboard page and check the Inbox section again.

Help me figure out why my Writer agent hire isn't showing in the approval queue.

Assign the first task and watch delegation happen

Your org chart is set. Now it is time to give the CEO some real work and watch it cascade down to the Writer.

  • Navigate to the task or ticket view for your DevTools Weekly company.
  • Create a new task tied to your company goal.
  • Set the task title to something specific, like Research and draft newsletter sections for the top 3 developer tool launches this week.
  • Assign the task to the CEO agent.

Why assign the task to the CEO, not the Writer?

You are mimicking how a real company works. The board (you) gives strategic direction to the CEO. The CEO breaks that direction into actionable sub-tasks and delegates them to the right people. If you assigned work directly to the Writer, you would be bypassing the org chart and doing the CEO's job yourself.

Now trigger the delegation by firing the CEO's heartbeat.

  • Go to the CEO agent's detail page in the dashboard.
  • Click the manual heartbeat trigger button to wake the CEO.
  • Watch the CEO read the task, plan its approach, and create sub-tasks for the Writer.

You can click on the active task to watch the CEO working in real time. It reads the task, gathers context from the company mission and goal, and delegates content production sub-tasks to the Writer through the org chart.

  • After the CEO's heartbeat completes, trigger a manual heartbeat on the Writer agent to wake it up.
  • Watch the Writer pick up its assigned sub-tasks and begin producing content.

Check the dashboard for updates. You should see task assignments, agent activity logs, and cost tracking reflecting the work both agents just performed.

What is the heartbeat execution model?

Agents in Paperclip do not run continuously. They wake up on a schedule (or manually), check for assigned work, execute, report back, and go to sleep. This makes compute costs predictable and prevents infinite loops. Each heartbeat produces a structured run record with logs, cost events, and an audit trail.

CEO not delegating to the Writer?

  • Confirm the Writer's status is active in the agent list. If it shows paused, the approval may not have gone through.
  • Double-check that the Writer's Reports to field points to the CEO agent. If it reports to the Board instead, the CEO cannot delegate to it.
  • Review the CEO's system prompt. If it does not mention delegating to a Writer or direct report, the CEO may try to do all the work itself.

Help me troubleshoot why my CEO agent is not delegating tasks to the Writer.

Your two-agent org chart is live and delegating work. Next up, you will explore the dashboard's monitoring tools to read audit trails, track costs, and exercise governance controls over your agents.

Monitor, Govern, and Explore the Dashboard

Your org chart is live. The CEO and Writer are connected, and tasks are flowing through the reporting lines you built in the last step.

Running autonomous agents without visibility is a risk. In this step, you'll use Paperclip's observability and governance tools to trace agent decisions, track costs, and control agent behavior.

In this step, get ready to:
  • Read the audit trail to trace exactly what each agent did and why.
  • Check budget usage and per-agent cost tracking.
  • Exercise governance controls to manage agent autonomy.
Read the audit trail

Every action your agents take is recorded. Paperclip logs conversations between agents, tool calls, decisions, timestamps, and costs for every single run.

  • Open the task you assigned to the CEO in the previous step.
  • Click into the ticket view to see the full history of that task.
  • Click through the run history entries to see each heartbeat's activity.
  • Note what each agent did, what it cost, and how long it took.

What does the audit trail show?

The audit trail is Paperclip's observability layer. For every heartbeat, it records the full conversation the agent had, which tools it called, what decisions it made, and the cost of that run.

This is what makes autonomous agents safe to operate. Instead of trusting that agents did the right thing, you can verify it.

Don't see any activity in the audit trail?

  • The CEO may not have completed a heartbeat yet. Trigger a manual heartbeat from the agent's page in the dashboard.
  • Make sure the task you created in Step 4 is assigned to the CEO and tied to a company goal.
  • Confirm the Paperclip server is still running in your terminal. If it stopped, restart it.

Help me troubleshoot why my agents aren't showing any activity in the Paperclip audit trail.

Check budget usage and cost tracking

You set budgets on both agents when you hired them. Those budgets are not suggestions. Paperclip treats them as hard limits.

  • Navigate to the company's budget view in the dashboard.
  • Review the per-agent spending breakdown for the CEO and Writer.
  • Check the per-task costs to see how much each piece of work cost to complete.
  • Note the overall burn rate to understand how quickly your agents are using their budgets.

How does budget enforcement work?

Paperclip enforces budgets atomically. When an agent hits its monthly spending limit, it stops receiving work. There is no grace period and no soft warning.

The agent simply cannot run until the budget resets or you increase the limit. This prevents runaway costs from autonomous agents.

Seeing $0.00 for all agents?

  • Agents only incur costs when their heartbeats fire and they perform actual work. If no heartbeat has triggered, spending will be zero.
  • Trigger a manual heartbeat for the CEO from the agent's page, then refresh the budget view.

Help me understand why my Paperclip agents show zero cost.

Exercise governance controls

You are the board of directors of your AI company. Governance controls let you intervene in agent operations at any time.

  • Find the Writer agent in the dashboard.
  • Click Pause to stop the Writer from receiving heartbeats.

The Writer is now paused. It will not wake up on its next scheduled heartbeat, and it will not receive any new task assignments.

  • Click Resume to bring the Writer back online.
  • Try overriding a task assignment by reassigning a task from one agent to another in the ticket view.

Why do governance controls matter?

These controls are what separate Paperclip from a simple task runner. You can pause agents, override assignments, approve hires, and review decisions before they take effect.

Without governance, autonomous agents are unpredictable. With it, your agents work within the boundaries you define.

Pro tip: test your limits

Try temporarily lowering the CEO's budget to $0.01 and triggering a heartbeat. You will see the agent get blocked by the budget limit immediately. Reset the budget when you are done experimenting.

Secret mission

Add an Editor Agent

Your two-agent company gets work done, but there is no quality gate between the Writer's first draft and the CEO's final review. Real companies have editors. Can you add one to your org chart and route all drafts through a review step before they reach the top?

Before you go

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely. This project runs locally on your Mac, but active agent heartbeats trigger Claude Code API calls that bill against your Anthropic subscription.

Cost warning

While Paperclip itself is free and open source, your agents fire heartbeats on a schedule. Each heartbeat spawns a Claude Code session that uses your Anthropic API credits. If you leave the server running with agents active, costs will continue to accumulate. Stop the server or pause your agents to prevent unexpected charges.

Resources you used:

  • Paperclip server running at http://localhost:3100.
  • Embedded PostgreSQL database stored at ~/.paperclip/instances/default/.
  • "DevTools Weekly" company with CEO and Writer agents.
  • Agent heartbeat schedules triggering Claude Code API calls.
  • pnpm installed globally via npm.

Keep everything running

No action needed. Choose this if you are still actively building your AI company and want to keep experimenting with agents, tasks, and governance.

  • Your Paperclip server stays running at http://localhost:3100.
  • Agent heartbeats continue firing on their configured schedules.
  • Keep an eye on budget usage in the dashboard to avoid unexpected Anthropic API charges.

Pause - I'll come back to this later

Stop the server to free up memory and prevent any further API costs. Your data is preserved and you can resume later.

  • Go to the terminal window where Paperclip is running and press Ctrl+C to stop the server.
  • Your company data, agents, and task history are all saved in ~/.paperclip/instances/default/.
  • To restart later, open a regular terminal window (not inside Claude Code) and run:
npx paperclipai run
  • Your agents, company, and full audit trail will be exactly as you left them.

Delete - I don't want to use this again

Remove all project resources and start fresh. This deletes your company, agents, task history, and the embedded database.

  • Go to the terminal window where Paperclip is running and press Ctrl+C to stop the server.
  • Delete the Paperclip data directory by running:
rm -rf ~/.paperclip/instances/default/
  • If you also want to remove pnpm, run:
npm uninstall -g pnpm
  • Everything is now removed. You can re-run npx paperclipai onboard --yes at any time to start over from scratch.

Mission accomplished

Nice Work!

You just launched your first AI company. You went from a single terminal command to a fully running multi-agent orchestration platform, complete with structured roles, budgets, governance, and a full audit trail.

Here's what you learned:

  • Set up a full AI orchestration platform locally with Paperclip, including an embedded PostgreSQL database and a live dashboard at localhost:3100.
  • Hired and configured two AI agents (CEO and Writer) with distinct roles, reporting lines, heartbeat schedules, and per-agent budgets that enforce hard spending limits.
  • Monitored agent activity through the audit trail and exercised governance controls to approve hires, pause agents, and manage autonomy as the board of directors.
  • Added an Editor agent to build a three-agent workflow where the Writer drafts, the Editor reviews, and the CEO gives final approval.

Ready to quiz yourself?