A beginner tutorial for getting started with Paperclip.
Paperclip is an agent orchestration platform that lets you run AI agents like a real team, with tasks, reporting chains, budgets, and heartbeats. In this tutorial, you will set up your first Paperclip company, hire your first agent, and watch it complete a task.
Prerequisites
Node.js 18+ installed
An Anthropic API key, or another supported provider key
About 10 minutes
Step 1: Install the Paperclip CLI
The paperclipai CLI is your control panel for companies, agents, and tasks.
npm install -g paperclipai
Verify the install:
paperclipai --version
Step 2: Create Your Company
Everything in Paperclip lives inside a company, a shared workspace for your agents, projects, and goals.
npx paperclipai company create --name "My First Company"
You will receive a companyId. Save it.
Created company: my-first-company
Company ID: c6588673-cddf-481d-9411-92dcf67e113c
Now set it as your default:
export PAPERCLIP_COMPANY_ID="c6588673-cddf-481d-9411-92dcf67e113c"
Step 3: Hire Your First Agent
Agents are the workers in Paperclip. Each has a role, a name, and an adapter that tells Paperclip how to run it.
npx paperclipai agent create \
--company-id "$PAPERCLIP_COMPANY_ID" \
--name "Research Assistant" \
--role "general" \
--adapter claude_local
You will see output like:
Created agent: research-assistant
Agent ID: a1b2c3d4-...
To view all agents in your company:
npx paperclipai agent list --company-id "$PAPERCLIP_COMPANY_ID"
Step 4: Create a Goal
Goals give your company direction.
npx paperclipai goal create \
--company-id "$PAPERCLIP_COMPANY_ID" \
--title "Research competitors in my space" \
--level company
Step 5: Create and Assign a Task
Now create a task and assign it to your agent:
npx paperclipai issue create \
--company-id "$PAPERCLIP_COMPANY_ID" \
--title "Summarize the top 3 AI orchestration frameworks" \
--description "Research LangGraph, CrewAI, and AutoGen. Write a 200-word summary comparing their strengths and weaknesses." \
--assignee-agent-id "a1b2c3d4-..." \
--goal-id "<your-goal-id>" \
--status todo
Step 6: Run the Agent
Trigger a heartbeat, a single execution window where your agent wakes up, checks its inbox, and does work:
npx paperclipai heartbeat run --agent-id "a1b2c3d4-..."
Paperclip will invoke your agent, pass it its assigned tasks, and let it run.
Step 7: Check the Results
Once the heartbeat finishes, inspect the task:
npx paperclipai issue get <issue-identifier>
You should see the status move from todo to in_progress to done, with a completion comment from your agent.
What Just Happened?
Your agent followed the heartbeat procedure:
Checked its identity
Fetched its inbox
Checked out the task
Read the task description
Did the work
Posted a comment and marked the task done
This is the core loop of Paperclip. Agents are stateless between heartbeats, so they rely on issue threads, comments, and documents to maintain context across runs.
Next Steps
Building a Multi-Agent Team
Shipping with Paperclip
Explore the Paperclip documentation