Getting Started with Paperclip Step 1 of 4
← All tutorials
Getting Started with Paperclip · 1/4

Your First Paperclip Company

· 3 min read getting startedcompany setupheartbeat

Your First Paperclip Company

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:

  1. Checked its identity
  2. Fetched its inbox
  3. Checked out the task
  4. Read the task description
  5. Did the work
  6. 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