Launch an AI Company with Paperclip
Orchestrate a multi-agent AI company with governance, budgets, and org charts.
Introduction
30 Second Summary
Imagine starting a company where every employee is an AI agent. You set the mission, approve key decisions, and watch your AI team get to work.
In this project, you will use Paperclip to launch an autonomous AI company called NoteGenius. You will hire AI agents, approve their strategies, build an org chart, and monitor everything from a dashboard.
What You'll Build
You will set up a locally running Paperclip server and configure a multi-agent AI company with structured governance, budgets, and task tracking.
By the end of this project, you'll have:
- A locally running Paperclip server with an embedded PostgreSQL database.
- A multi-agent org chart with a CEO, CTO, and engineer agents working toward a defined company goal.
- Hands-on experience with Paperclip's governance system, including approving strategies, reviewing hires, and setting per-agent budgets to control LLM spending.
- Configured heartbeat schedules so your agents wake up and work autonomously on a timer.
Are there any prerequisites?
You will need basic familiarity with the command line. You will also need an Anthropic API key for your agents to make LLM calls. Paperclip itself is free and open source.
Install Your Tools
Before you can launch your AI company, you need three tools installed on your machine.
Node.js runs the Paperclip server. pnpm manages its packages. Claude Code is the CLI that powers your AI agents.
In this step, get ready to:
- Install Node.js and pnpm.
- Install the Claude Code CLI.
- Configure your Anthropic API key.
Install Node.js and pnpm
Paperclip requires Node.js version 20 or higher to run its server. pnpm is the fast package manager that Paperclip uses to install and manage its dependencies.
- Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
- Type Terminal and press Enter to open it.
- Check if Node.js is already installed by running this command:
node --version
I see a version number
Node.js is installed. Confirm the version starts with v20 or higher (for example, v24.15.0).
If your version is below v20, follow the install steps in the other tab to upgrade.
Command not found
Node.js is not installed yet. The fastest way to install it on macOS is with Homebrew.
- Install Node.js by running this command:
brew install node
Don't have Homebrew?
You can also download Node.js directly from nodejs.org. Choose the LTS version and follow the installer.
- After installation, verify Node.js is working by running:
node --version
You should see a version number starting with v20 or higher.
Now that Node.js is ready, you can install pnpm. Paperclip requires pnpm version 9.15 or higher.
- Install pnpm globally by running this command:
npm install -g pnpm
- Verify pnpm is installed by running:
pnpm --version
You should see a version number like 9.15.0 or higher.
Seeing permission errors with npm install?
If you get an EACCES error, try running the command with sudo:
sudo npm install -g pnpm
Enter your Mac password when prompted. You will not see characters appear as you type.
help me fix permission errors when installing pnpm with npm
Install the Claude Code CLI
Paperclip uses Claude Code to give each AI agent its own local Claude session. When an agent "wakes up" during a heartbeat, Paperclip starts a Claude Code session in the agent's working directory.
- Install the Claude Code CLI by running this command:
curl -fsSL https://claude.ai/install.sh | bash
What does this command do?
This downloads the official Claude Code installer script from Anthropic and runs it. The CLI gets installed to ~/.local/bin/claude.
- After the installer finishes, verify Claude Code is working by running:
claude --version
I see a version number
Claude Code is installed and ready to go. Move on to the next substep.
Command not found
Your terminal cannot find the claude command because ~/.local/bin is not in your PATH. You need to add it.
- Add ~/.local/bin to your PATH by running this command:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
- Now try the version check again:
claude --version
You should now see a version number printed in your terminal.
Still not working after the PATH fix?
Close your terminal completely and open a fresh window. The PATH change sometimes needs a new terminal session to take effect.
If you use Bash instead of Zsh, replace ~/.zshrc with ~/.bashrc in the command above.
help me get the Claude Code CLI working on my machine
Set up your Anthropic API key
Claude Code agents send requests to Anthropic's API to generate responses. Your API key authenticates those requests so Anthropic knows which account to charge.
- If you do not have an Anthropic API key yet, go to console.anthropic.com/settings/keys and create one.
- Copy your API key. You will not be able to see it again after leaving the page.
- Back in your terminal, export your API key as an environment variable by running this command:
export ANTHROPIC_API_KEY=your-api-key-here
- Replace your-api-key-here with the actual key you copied from the Anthropic console.
Why an environment variable?
Paperclip's Claude Code adapter looks for the ANTHROPIC_API_KEY environment variable automatically. When an agent runs a heartbeat, Paperclip passes this key to the Claude Code CLI session so it can authenticate with Anthropic's API.
Pro tip: make your key persist across sessions
The export command only sets the key for your current terminal session. If you close the terminal, the key is gone. To make it persist, add the export line to your shell profile:
echo 'export ANTHROPIC_API_KEY=your-api-key-here' >> ~/.zshrc
Replace your-api-key-here with your actual key before running this command.
Your API key is the only cost in this project
Paperclip itself is free and open source (MIT license). The only costs come from LLM API usage through your Anthropic key. You will set up per-agent budgets in a later step to control spending.
Your tools are installed and your API key is configured. Next up, you will launch the Paperclip server and see its dashboard for the first time.
Launch Paperclip
Your tools are installed and ready to go. Now it's time to launch Paperclip and stand up the server that will power your AI company.
Paperclip bundles its own embedded PostgreSQL database, so no separate database installation is needed. One command handles the entire setup.
In this step, get ready to:
- Run the Paperclip onboarding command to initialize the server and database.
- Open the Paperclip dashboard and confirm the server is healthy.
Run the onboarding command
Paperclip's onboarding command handles the full setup in one shot. It downloads the package, creates a configuration file, sets up an embedded database, and starts the server.
- Launch Paperclip by running this command in your terminal:
npx paperclipai onboard --yes
What does this command do?
- npx paperclipai onboard downloads and runs the Paperclip setup.
- The --yes flag accepts all defaults and starts in local trusted mode. No authentication is needed for local access.
- A config file is created at ~/.paperclip/instances/default/config.json.
- An embedded PostgreSQL database is set up automatically. No external database installation required.
- Wait for the command to finish. You should see output confirming the server has started on port 3100.
Command not working?
- Make sure Node.js 20 or higher is installed by running node --version.
- If you see a port conflict, another process is already using port 3100. Close it or check for stale processes.
- If the download fails, check your internet connection and try running the command again.
- Help me troubleshoot the Paperclip onboarding command
Access the Paperclip dashboard
With the server running, you can access Paperclip's web interface. This is your control center for creating companies, hiring agents, and monitoring your AI workforce.
- Open your browser and navigate to http://localhost:3100.
You should see the Paperclip dashboard UI.
- Confirm the API is running by visiting http://localhost:3100/api/health in a new tab.
You should see a JSON response confirming the server is healthy.
The Paperclip server runs in the terminal where you launched it. Keep that terminal window open for the rest of the project and use a separate tab for any other CLI commands.
Dashboard not loading?
- Check the terminal where you ran the onboarding command. If the server crashed, re-run npx paperclipai onboard --yes.
- Make sure you are using http:// in the URL, not https://. The local server does not use SSL.
- Help me get the Paperclip dashboard working
What about the API?
The Paperclip API is also available at http://localhost:3100/api. You can use it for programmatic access, but the dashboard is all you need for this project.
Your Paperclip server is live. Next, you'll create your AI company and hire a CEO agent to lead it.
Create Your Company and Hire a CEO
Your Paperclip server is live and the dashboard is ready. A running server is just infrastructure without a purpose to drive it.
In this step, you'll create an AI company called "NoteGenius" and hire its first employee: a CEO agent powered by Claude Code. You'll then approve the CEO's opening strategy, which kicks off the entire autonomous workflow.
In this step, get ready to:
- Create a company with a specific, measurable goal.
- Hire a CEO agent using the Claude Code adapter.
- Approve the CEO's initial strategy proposal.
Create your company
In Paperclip, a company is the top-level container for your agents, tasks, budgets, and org chart. Every company starts with a goal that guides what its agents work toward.
- In the Paperclip dashboard at http://localhost:3100, click New Company.
- Enter NoteGenius in the Name field.
- Click Create to save your company.
You should see NoteGenius listed on the dashboard. Now you need to give it a goal.
- Navigate to the Goals section in the left sidebar.
- Create a new top-level goal by pasting the following text:
Build the #1 AI-powered note-taking app. Create a cross-platform app with real-time AI summarization, smart tagging, and voice-to-text. Reach 10,000 beta users in 6 months.
- Save the goal.
Why does the goal matter?
Paperclip injects the company goal into every agent's context. Each agent sees what the company is trying to achieve and plans its work accordingly. A specific, measurable goal like "Reach 10,000 beta users in 6 months" gives agents concrete targets to plan around.
You should see your NoteGenius company on the dashboard with the goal you just created.
Don't see your company?
Make sure your Paperclip server is still running in the terminal. If you closed it, run npx paperclipai onboard --yes again to restart it.
help me troubleshoot why my company didn't appear in the Paperclip dashboard
Hire a CEO agent
Your company needs leadership. The CEO is the first agent in the org chart, and every other agent will eventually report up to it.
The CEO agent needs a working directory on your file system where it can read and write files. Create that directory first.
- Create the CEO's working directory by running this command:
mkdir -p /tmp/notegenius/ceo
- Confirm the directory exists by running:
ls /tmp/notegenius/
You should see ceo listed in the output.
- In the Paperclip dashboard, click Agents in the left sidebar.
- Click Create Agent.
- Select claude_local as the Adapter type.
- Enter CEO in the Name field.
- Enter ceo in the Role field.
- Enter Strategic planning, delegation, goal tracking, team building in the Capabilities field.
- In the adapter configuration section, set cwd to /tmp/notegenius/ceo.
What is the claude_local adapter?
An adapter is how Paperclip connects to an LLM. The claude_local adapter runs the Claude Code CLI on your machine. It persists session IDs between heartbeats.
When the agent wakes up again, it resumes the same conversation instead of starting fresh. The cwd field tells the adapter which directory to work in.
- Click Test Environment to verify that the Claude Code CLI is installed, the working directory exists, and your API key is set.
- Once the test passes, click Create to add the agent.
Your CEO agent should now appear on the Agents page with a status of active or idle.
Test Environment failing?
- If it reports the CLI is missing, confirm that claude --version works in your terminal. You may need to restart the terminal or re-add ~/.local/bin to your PATH.
- If it reports the API key is missing, make sure you exported ANTHROPIC_API_KEY in the same terminal session where Paperclip is running.
- If the cwd check fails, confirm the directory exists by running ls /tmp/notegenius/ceo in your terminal.
help me fix my claude_local adapter test failure
Approve the CEO's strategy
Paperclip does not let agents act unchecked. The CEO's first move is to propose a strategy, and you (the board operator) must approve it before the CEO can start delegating work.
After you created the CEO, it runs its first heartbeat automatically. It reads the company goal, drafts a strategy proposal, and submits it for your review. This usually takes 30 to 60 seconds.
- Navigate to the Approvals page in the left sidebar.
- Find the CEO's strategy proposal. It has the type CEO strategy.
- Read through the proposed strategy to see how the CEO plans to achieve the NoteGenius goal.
- Click Approve to give the CEO the green light.
What is the governance system?
Paperclip's governance system ensures that no agent makes high-impact decisions without human oversight. Strategy proposals and hire requests both require your explicit approval before agents can act on them.
You can approve, reject, or request a revision. If you request a revision, the agent resubmits and the proposal returns to a pending state.
Once approved, the CEO's status changes and it begins planning its next moves. You may see it start proposing hire requests within a few minutes.
No strategy proposal showing up?
The CEO needs to complete its first heartbeat before a proposal appears. If nothing shows up after a minute or two, try triggering a manual heartbeat.
- Click Invoke on the CEO's agent page to manually trigger a heartbeat.
- Alternatively, run the following command in your terminal (replace the agent ID with your CEO's ID from the Agents page):
paperclipai heartbeat run --agent-id {agentId}
You can find the agent ID on the CEO's agent detail page, or by running paperclipai agent list in your terminal.
help me troubleshoot why my CEO agent hasn't proposed a strategy
Your CEO is approved and ready to lead. Next up, you'll set budgets to make sure your agents don't burn through your API credits.
Set Budgets and Control Costs
Your CEO is hired and its strategy is approved. NoteGenius now has a clear direction.
Every heartbeat triggers LLM API calls that cost real money. In this step, you will set budgets at two levels to keep spending under control.
In this step, get ready to:
- Set a company-wide monthly budget to cap total spending.
- Configure per-agent budgets for granular cost control.
Set a company-wide budget
A company-wide budget caps the total amount all agents can spend on LLM calls each month. Paperclip tracks every API call against this cap and enforces it automatically.
- In the Paperclip dashboard, open your NoteGenius company page.
- Find the Budget settings section.
- Set the monthly company budget to a value between 1000 and 2000 cents ($10-$20). This is a conservative limit for experimentation.
- Save the budget.
Why set the budget in cents?
Paperclip tracks all costs in cents for precision. A value of 1500 means $15.00 per month. This keeps calculations exact and avoids floating-point rounding issues with small per-token charges.
- Confirm your company page now displays the monthly budget you entered.
Set per-agent budgets
The company-wide budget sets a ceiling, but per-agent budgets let you control how much each individual agent can spend. This prevents a single agent from consuming the entire company budget.
- Navigate to the Agents page in the Paperclip dashboard.
- Click on your CEO agent to open its configuration page.
- Find the Budget section and set the monthly budget to 500 cents ($5/month).
- Save the agent configuration.
How does budget enforcement work?
Paperclip enforces per-agent budgets at two thresholds:
- At 80% usage, the agent receives a soft warning. It continues running but is instructed to focus on critical tasks only.
- At 100% usage, the agent is auto-paused. It stops running heartbeats entirely until the next billing cycle or until you override the budget.
This two-tier system gives agents a chance to wrap up important work before hitting the hard stop.
- Verify that the CEO agent's configuration page now shows the 500 cent monthly budget.
Pro tip: start small
When you approve additional agents in the next step, give each one a per-agent budget too. You can always increase budgets later, but you cannot un-spend tokens that have already been used.
Budget not saving?
- Make sure you are entering the value in cents, not dollars. $5 is 500 cents.
- Confirm your Paperclip server is still running. Visit http://localhost:3100/api/health in your browser to check.
- Try refreshing the page and re-entering the budget value.
Help me troubleshoot why my Paperclip budget settings are not saving.
Your spending guardrails are in place. Next up, you will grow the team by reviewing and approving the CEO's hire requests for a CTO and engineers.
Grow the Team
Your budgets are set, giving you guardrails for every agent's spending. Now it's time to grow beyond a solo CEO.
The CEO has a strategy and knows what roles the company needs. It will propose new hires through Paperclip's governance system, and your job is to review each proposal, approve the ones that make sense, and watch your org chart take shape.
In this step, get ready to:
- Review the CEO's hire requests on the Approvals page.
- Approve the CTO and at least one engineer.
- Explore your company's org chart to see the full hierarchy.
Review hire requests
After you approved the CEO's strategy in the previous step, the CEO begins proposing new hires. Each proposal is a hire_agent request that goes through Paperclip's approval system before any agent is created.
- Navigate to the Approvals page in the Paperclip dashboard.
- Look for approval requests with the type hire_agent.
- Review the details of each request, including the proposed agent's name, role, capabilities, adapter configuration, and budget.
What kind of roles does the CEO propose?
The CEO analyzes the company goal and proposes roles it believes are necessary. Common proposals include a CTO for technical leadership, engineers for building the product, and marketing roles for growth.
Don't see any hire requests?
- Make sure you approved the CEO's strategy in the previous step. Without an approved strategy, the CEO cannot propose hires.
- The CEO needs to run a heartbeat before it can submit proposals. Click Invoke on the CEO's agent page to trigger one manually.
- Help me troubleshoot why my CEO isn't proposing any hires.
Approve the CTO and an engineer
Each approval gives you three options: approve, reject, or request a revision with notes. You control exactly who joins the team.
- Select the CTO hire request on the Approvals page.
- Review the proposed role, capabilities, and adapter configuration.
- Click Approve to add the CTO to your company.
- Find at least one engineer hire request and click Approve for that as well.
What happens after you approve?
Paperclip creates the new agent, adds it to the org chart under the agent that proposed the hire, and begins scheduling heartbeats for it. The new agent starts working on its next heartbeat cycle.
Pro tip: Request revisions
You don't have to accept every proposal as-is. Select Request Revision to send the proposal back to the CEO with notes. For example, you might ask it to adjust an agent's capabilities or lower a proposed budget before approving.
Explore the org chart
With multiple agents approved, your company now has a real hierarchy. The org structure page gives you a visual overview of who reports to whom.
- Navigate to the org structure page in the Paperclip dashboard.
- Verify that the CEO is at the top of the hierarchy.
- Confirm that the CTO and any approved engineers appear underneath, reporting to the CEO.
Each agent displays its current status next to its name in the org chart.
What do the agent statuses mean?
- active: The agent is set up and ready to receive work.
- idle: The agent is between heartbeats, waiting for its next trigger.
- running: The agent is currently executing a heartbeat.
- error: Something went wrong during the agent's last run.
- paused: The agent has been stopped, either manually or because it hit its budget limit.
- terminated: The agent has been permanently shut down. This action is irreversible.
Agents not showing up in the org chart?
- Double-check that you clicked Approve on the hire requests. Requests left in a pending or revision_requested state will not create agents.
- Try refreshing the page. The org chart updates after Paperclip finishes creating the agent.
- Help me figure out why my approved agents are not appearing in the org chart.
Your AI company has a real team now. Next up, you'll monitor how they collaborate, track tasks across the org, and review LLM costs on the dashboard.
Monitor Your Running Company
Your AI company has a full team. In the last step, you approved hires for a CTO and engineers, and your org chart shows a structured hierarchy ready to tackle the NoteGenius goal.
Now it's time to see what your agents are actually doing. Paperclip gives you full visibility into task progress, agent activity, and spending from a single dashboard.
In this step, get ready to:
- Track tasks and their progress across your AI team.
- Trigger a manual heartbeat to watch an agent work in real time.
- Review the activity log and cost tracking for your company.
Track tasks and progress
Every piece of work in Paperclip is tracked as a task. Agents create tasks, assign them to each other, and move them through a defined lifecycle as work gets done.
- Click Tasks in the Paperclip dashboard sidebar.
You should see a list of tasks that your agents have created since you approved the CEO's strategy. Each task shows its title, assigned agent, and current status.
What is the task lifecycle?
- Tasks move through these stages: backlog, todo, in_progress, in_review, and done.
- There is also a blocked sub-state under in_progress for tasks waiting on dependencies.
- Terminal states are done and cancelled. Once a task reaches either of these, it cannot be reopened.
- Only one agent can own a task at a time. If two agents try to check out the same task, one gets a conflict error.
- Click on any task to see its details, including the assigned agent, current status, and any notes or output.
Trigger a manual heartbeat
Your agents work during heartbeats. Each heartbeat is a cycle where the agent wakes up, checks for assigned tasks, does work, and reports results.
If an agent is idle and you want to see it in action right now, you can trigger a heartbeat manually from the UI or the CLI.
- Navigate to the Agents page in the sidebar.
- Click on the agent you want to activate (for example, your CEO or CTO).
- Click the Invoke button on the agent's detail page.
The agent's status changes to "running" while it processes its heartbeat. Watch the Tasks page to see it pick up and work on tasks.
What happens during a heartbeat?
- The agent reviews its assigned tasks and picks up work.
- It uses the Claude Code CLI to think through the task, write code, or make decisions.
- When finished, it reports results back to Paperclip and updates the task status.
- The session persists between heartbeats, so the agent remembers its previous context when it wakes up again.
You can also trigger a heartbeat from the CLI instead of the UI.
- List your agents and find the agent ID by running this command:
paperclipai agent list
You should see a table of agents with their IDs, names, roles, and statuses.
- Copy the agent ID for the agent you want to trigger, then run this command:
paperclipai heartbeat run --agent-id [[AGENT_ID="your agent's ID from the list above"]]
Agent not doing anything?
- Make sure the agent's status is "active" or "idle" on the Agents page. Paused or terminated agents cannot run heartbeats.
- Check that your Anthropic API key is still set in your terminal session. Run echo $ANTHROPIC_API_KEY to confirm it prints a value.
- Verify the agent has tasks assigned to it. If the backlog is empty, the agent has nothing to work on.
- My Paperclip agent isn't picking up tasks when I trigger a heartbeat. How do I debug this?
Review the activity log and costs
Every decision your agents make is logged. The activity log gives you a full audit trail of what happened, who did it, and when.
- Click Activity Log in the sidebar.
You should see entries for every mutation and decision your agents have made. This includes strategy proposals, hire requests, task creation, and task completions.
- Now click Costs in the sidebar to open the cost tracking view.
The costs view shows current month spending versus budget for each agent and the company overall.
What does cost tracking show?
- Each cost entry shows the provider, model, input tokens, output tokens, and cost in cents.
- You can see which agents are consuming the most budget at a glance.
- At 80% of an agent's budget, Paperclip sends a soft warning telling the agent to focus on critical tasks.
- At 100%, the agent is auto-paused and stops running heartbeats entirely.
Pro tip: check costs after each heartbeat
During experimentation, check the costs page after each heartbeat you trigger. This helps you understand how much a single agent run costs and whether your budget limits need adjusting.
- Confirm that the spending amounts on the Costs page are within the budget limits you set in Step 4.
Secret mission
Set Up Autonomous Heartbeat Schedules
Right now, your agents only work when you manually invoke them or when specific events trigger activity. What if they could wake up on their own, check for work, and keep making progress while you step away? Configure scheduled heartbeats to make your AI company truly autonomous.
Before you go
Clean Up Your Resources
Decide whether to keep your resources running, pause them to come back later, or delete them entirely. Paperclip itself is free and open source, but your agents make LLM API calls that cost real money whenever they run a heartbeat.
Cost warning
If you configured heartbeat schedules (especially in the Secret Mission), your agents will continue waking up and making Anthropic API calls on a timer. This means ongoing charges to your Anthropic account even when you are not actively watching the dashboard. Pause or stop your agents before walking away to avoid unexpected costs.
Resources you used:
- Paperclip server running locally on http://localhost:3100.
- Embedded PostgreSQL database managed by Paperclip.
- Paperclip config file at ~/.paperclip/instances/default/config.json.
- NoteGenius company with CEO, CTO, and engineer agents.
- Agent working directories (e.g., /tmp/notegenius/ceo).
- Claude Code CLI installed at ~/.local/bin/claude.
- pnpm installed globally.
- Anthropic API key exported as an environment variable.
Keep everything running
No action needed. Choose this if you are still actively building and want your agents to keep working. Just keep an eye on your Anthropic API usage if heartbeat schedules are enabled.
- Leave the Paperclip server running in your terminal.
- Check the Costs section of the dashboard periodically to monitor spending against your budget.
- Your per-agent budget limits will auto-pause agents if they hit 100% usage, so you have a safety net.
Pause - I'll come back to this later
Shut down the Paperclip server and pause your agents to stop all LLM API calls. Your data stays intact so you can resume later.
- In the Paperclip dashboard, navigate to each active agent and click Pause. This stops their heartbeat schedules and prevents new LLM calls.
- Go to the terminal where Paperclip is running and press Ctrl+C to stop the server.
- When you are ready to come back, run npx paperclipai onboard --yes again. Your existing config and database will be preserved.
Delete - I don't want to use this again
Remove all project resources and start fresh. This deletes your Paperclip instance, company data, and agent working directories.
- Stop the Paperclip server by pressing Ctrl+C in the terminal where it is running.
- Delete the Paperclip config and database by removing the ~/.paperclip directory.
- Delete the agent working directories (e.g., /tmp/notegenius).
- Optionally, remove the ANTHROPIC_API_KEY export line from your ~/.zshrc file if you no longer need it.
- Optionally, uninstall pnpm by running npm uninstall -g pnpm and Claude Code CLI by removing ~/.local/bin/claude.
Mission accomplished
That's a Wrap!
Nice work! You just launched your first autonomous AI company using Paperclip. You went from zero to a fully operational multi-agent organization with structured governance, cost controls, and real tasks flowing across your team.
Here's what you learned:
- Built an autonomous AI company (NoteGenius) with a full org chart of AI agents, including a CEO, CTO, and engineers working in a hierarchy powered by the Claude Code adapter.
- Used Paperclip's governance system to review and approve CEO strategies, evaluate hire requests, and control the growth of your AI team.
- Set company-wide and per-agent budgets to enforce LLM cost limits, with automatic soft warnings at 80% and hard stops at 100%.
- Configured autonomous heartbeat schedules so your agents wake up and work on a timer without manual invocation.
Ready to quiz yourself?