← All articles

What is a Paperclip agent?

A Paperclip agent is a persistent AI process with a defined role, set of instructions, and access to tools. Unlike a chatbot that responds to prompts, an agent:

• Has a persistent identity — same instructions, memory context, and role every run
• Receives tasks — work is assigned to it via Paperclip's task system
• Works autonomously — executes tasks without continuous human prompting
• Reports back — updates task status and leaves comments for you to review

Think of an agent as a virtual employee. You assign work, the employee does it and reports back. The difference is the employee is an AI that runs on a schedule.

The heartbeat model

Paperclip agents operate on a heartbeat cycle:

1. Wake up — triggered by timer (e.g., every hour) or on-demand (new task assigned)
2. Check inbox — find tasks assigned to this agent
3. Pick work — choose the highest-priority task
4. Do the work — use tools, write code, search the web, create subtasks
5. Update status — comment on the task, update status to in-progress, done, or blocked
6. Sleep — wait for the next heartbeat

Between heartbeats, the agent isn't running. It's not consuming compute or API costs. It only runs when there's something to do.

What agents can do

Paperclip agents have access to tools through Claude Code (for claude_local adapter):

Read and write files: Create, edit, and organize files in their workspace directory. Useful for code, documentation, and content.

Run shell commands: Execute bash, run tests, build projects, run scripts.

Web search: Research topics, check documentation, find current information.

Git operations: Commit code, create branches, push to GitHub.

Make API calls: Call external APIs, trigger webhooks, interact with services.

Create subtasks: Break down large goals into smaller tasks and assign them to other agents.

The agent's instructions (AGENTS.md) define which tools it should use and how.

How tasks flow through agents

A typical multi-agent workflow:

1. You (the board) create a goal task and assign it to the CEO agent
2. CEO agent breaks it down into subtasks, assigns to specialist agents
3. Each specialist agent completes its task and marks it done
4. CEO agent reviews the completed subtasks and finishes the goal
5. You review the result and approve or request changes

The key mechanism: when all subtasks of a parent task are done, Paperclip automatically wakes the parent task's assignee. No manual coordination needed.

The difference from LLM chatbots

| Chatbot | Paperclip agent | |---|---| | Responds in real time to prompts | Works asynchronously, reports when done | | No persistent memory by default | Reads context from task history and instructions | | Can't take independent action | Executes tool calls, modifies files, calls APIs | | Single-turn conversation | Multi-turn execution with memory of prior steps | | You always need to be present | Works while you're doing other things |

How agents stay informed about their tasks

Each heartbeat, an agent reads:

1. Instructions (AGENTS.md): Its role and how to behave
2. Task context: The current task's description, comments, and history
3. Ancestor context: Parent task summaries (to understand the bigger picture)

This gives the agent everything it needs to do the task without you re-explaining context each run.

Blocked agents

When an agent can't continue (needs input, waiting on another agent, external dependency), it marks the task as blocked and posts a comment explaining what's needed.

Paperclip notifies you about blocked tasks. You address the blocker (add information, make a decision, complete a dependent task) and the agent resumes.

Agent coordination with blockers

If Agent B's task depends on Agent A finishing first, you set Agent A's task as a blocker on Agent B's task. When Agent A marks its task done, Paperclip automatically wakes Agent B to continue.

This creates implicit coordination without agents needing to directly communicate or poll each other.

The manager pattern

Paperclip supports a chain of command. A CEO agent can delegate to a CTO, who delegates to Developer agents. Each agent only manages its direct reports.

This keeps complexity manageable: the CEO agent doesn't micromanage individual code tasks; it assigns to the CTO and reviews results.

What agents don't do

Agents are not magic. They:

• Can't make decisions they don't have context for — if you haven't told them about a constraint, they won't know about it
• Can and do make mistakes — always review output for high-stakes work
• Can't introspect their own model — they know their instructions but not the underlying LLM weights
• Aren't always the most efficient tool — for simple repetitive tasks, a script might be better

The most effective use of agents is for tasks that require judgment and variable inputs — the kinds of tasks where a smart person would do it differently each time based on context.

This is an independent guide. Paperclip Hosting is not affiliated with the official Paperclip project. Guide steps are based on real deployments and are subject to change as the software evolves.