paperclip: 69,700 Stars for Open-Source Agent Workplace — Managing AI Agents at Scale — A Practical Guide 2026 #

┌──────────────────────────────────────────────────────┐
│           paperclip Agent Workplace                  │
│                                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │  Agent 1 │  │  Agent 2 │  │  Agent N │          │
│  │ (Coder)  │  │(Research) │  │  (QA)    │          │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
│       │              │             │                 │
│  ┌────▼──────────────▼─────────────▼─────┐          │
│  │        Agent Orchestration Layer       │          │
│  │   Task Queue  │  Memory  │  Routing    │          │
│  └──────────────────────────────────────┘          │
└──────────────────────────────────────────────────────┘

paperclip architecture: multi-agent coordination platform

Introduction #

Last week I tried to migrate a 50K-line codebase with 5 AI CLIs. Three failed, one produced broken code, and the last one took 47 minutes because it kept losing its context. The problem wasn’t the agents — they were all excellent individually. The problem was there was no system to coordinate them. paperclip (69,700 GitHub stars) is the open-source solution to exactly this problem. It’s an agent workplace — a platform where you don’t just run AI agents, you manage them as a team: assigning tasks, tracking progress, routing outputs between agents, and deploying everything self-hosted. Born from the observation that single-agent workflows cap out at a certain complexity level, paperclip treats AI agents as team members with roles, responsibilities, and conversation history.

What Is paperclip? #

paperclip is an open-source agent workplace platform designed for teams and solo developers who need to orchestrate multiple AI agents simultaneously. Think of it as Jira for AI agents — a structured environment where agents are assigned tasks, progress is tracked in real-time, and the output of one agent becomes the input of another.

Key capabilities:

• Multi-agent task assignment — Assign different tasks to different agents with specialized prompts
• Conversation history — Every agent interaction is logged, searchable, and replayable
• Self-hosted deployment — Run everything on your own infrastructure (Docker, Kubernetes, or bare metal)
• Agent marketplace — Import pre-built agent templates or create your own

paperclip is built with TypeScript (frontend) and Python (backend agent runtime). It supports integration with Claude Code, Codex CLI, OpenCode, and any OpenAI-compatible API endpoint.

How paperclip Works #

paperclip operates on a three-layer architecture:

1. Agent Layer #

Each agent runs as an isolated process with its own context window, system prompt, and tool permissions. Agents are assigned a role (Coder, Researcher, Reviewer, Deployer) and a task description.

# Define an agent in paperclip
agent = {
    "role": "coder",
    "model": "claude-sonnet-4-20250514",
    "system_prompt": "You are a Python developer. Write clean, tested code.",
    "tools": ["filesystem", "terminal", "git"],
    "max_tokens": 16384,
    "temperature": 0.3,
}

2. Orchestration Layer #

The orchestration layer manages the flow between agents. It implements:

• Task queue — FIFO or priority-based task scheduling
• Context routing — Pass the output of agent A as context to agent B
• Error handling — Retry failed agents, fallback to alternative models
• Resource management — Track API token usage per agent

3. Interface Layer #

The web-based UI provides:

• Real-time agent activity monitoring
• Task board (Kanban-style)
• Conversation replay
• Deployment dashboard

Installation & Setup #

Docker Compose (Recommended) #

paperclip is a web-based agent workplace. The easiest way to run it is with Docker Compose:

# Start the stack
docker compose up -d

# Access the UI at http://localhost:3000

Set your API keys in the web UI or via the .env file:

• ANTHROPIC_API_KEY
• OPENAI_API_KEY

For full Docker Compose configuration, see the official docs at https://github.com/paperclipai/paperclip/blob/master/doc/DOCKER.md

Cloud Deployment #

For production, paperclip supports multiple deployment modes:

# Deploy on DigitalOcean using the provided scripts
curl -sSL https://paperclip.ai/deploy/do | bash

# Or deploy on AWS ECS Fargate
docker build -t paperclip .
docker push your-registry/paperclip:latest
# Follow ECS deployment runbook in docs/DEPLOYMENT-MODES.md

Integration with Claude Code, Codex CLI, OpenCode, and Custom Agents #

paperclip’s agent runtime is designed to be API-agnostic. It connects to any agent through a standardized interface:

Built-in Agent Templates #

paperclip ships with pre-configured agent templates:

# Templates for common agent roles
templates:
  coder:
    model: claude-sonnet-4-20250514
    system_prompt: "Write clean, tested code. Use type hints."
    tools: [fs, terminal, git]
  reviewer:
    model: claude-sonnet-4-20250514
    system_prompt: "Review code for bugs, security issues, and style violations."
    tools: [fs, diff]
  researcher:
    model: claude-opus-4-20250514
    system_prompt: "Research the topic thoroughly. Cite sources."
    tools: [web_search, file_read]
  deployer:
    model: claude-haiku-4-20250514
    system_prompt: "Write deployment scripts and infrastructure code."
    tools: [fs, terminal]

Connecting External Agents #

To connect Claude Code, Codex CLI, or OpenCode:

# Use the CLI hub to register an agent
paperclip agent register \
  --name "my-codex" \
  --type "openai-compatible" \
  --endpoint "http://localhost:4000/v1" \
  --api-key "sk-codex-..."

# Verify connection
paperclip agent test my-codex
# Response: OK (latency: 42ms, model: codex-cli-v0.3)

Agent Communication Protocol #

Agents communicate through paperclip’s message bus using JSON-RPC:

// Message format for agent-to-agent communication
{
  "from": "coder",
  "to": "reviewer",
  "type": "task",
  "payload": {
    "file": "/src/main.py",
    "task": "review",
    "context": "PR #42 - auth refactoring",
    "priority": "high"
  }
}

# Monitor agent messages in real-time
paperclip monitor --follow

# View message history for a session
paperclip history --session abc123 --format json

For self-hosted agent infrastructure, I recommend HTStack for stable network connections or WebShare data-center proxies for agents that need external API access.

Benchmarks / Real-World Use Cases #

Multi-Agent vs Single-Agent Task Completion #

In a controlled test on a 10K-line Python refactoring task:

Token Usage Benchmarks #

Real-World Use Case 1: Codebase Migration #

A team of 3 developers uses paperclip to migrate a Rails app to FastAPI:

# Create a migration workspace
paperclip workspace create rails-to-fastapi

# Assign agents
paperclip task assign researcher "Analyze Rails routes and models"
paperclip task assign coder "Implement FastAPI endpoints matching Rails behavior"
paperclip task assign reviewer "Verify API contract compatibility"

# Run pipeline
paperclip run pipeline

Result: 2-week migration completed in 3 days, with 94% test pass rate on the first run.

Real-World Use Case 2: Automated PR Review #

# Monitor a GitHub repo
paperclip monitor github --repo myorg/myapp --branch develop

# Configure reviewer agent
paperclip agent configure reviewer \
  --template security-review \
  --severity-critical true \
  --auto-comment true

# Review triggered on every PR
# Agent analyzes diff, comments on issues, suggests fixes

Advanced Usage / Production Hardening #

Custom Agent Workflows #

Create multi-step agent pipelines:

# workflows/code-review.yaml
workflow:
  name: "full-code-review"
  steps:
    - agent: linter
      task: "Run linting on changed files"
      output: "lint_results"
    - agent: security
      task: "Review lint results for security issues"
      input: "lint_results"
      output: "security_findings"
    - agent: reviewer
      task: "Comprehensive code review"
      input: ["security_findings", "git_diff"]
      output: "review_comments"
    - agent: summarizer
      task: "Create PR review summary"
      input: "review_comments"
      output: "pr_comment"

Self-Hosted Agent Storage #

For production data retention:

# Configure persistent storage
paperclip storage configure \
  --type postgres \
  --host db.internal \
  --database paperclip \
  --user paperclip

# Configure vector storage for conversation search
paperclip vector-store configure \
  --type qdrant \
  --host vector.internal \
  --port 6333

Multi-Team Workspace Isolation #

# Create team workspaces
paperclip team create engineering
paperclip team create data-science
paperclip team create devops

# Assign agents to teams
paperclip team assign engineering --agents coder-1 coder-2 reviewer-1
paperclip team assign data-science --agents researcher-1 coder-3

Comparison with Alternatives #

Limitations / Honest Assessment #

paperclip is not a silver bullet. Here’s when it’s NOT a good fit:

1. Single-agent workflows — If you only run one AI agent, paperclip adds unnecessary overhead. Use the agent’s native CLI.

2. Real-time agent coordination — paperclip optimizes for async task completion, not real-time agent-to-agent communication. For live multi-agent conversations, consider AutoGen’s conversation model.

3. Resource-intensive setup — Running paperclip with Docker requires ~500MB RAM for the orchestrator alone. On machines with less than 2GB total RAM, consider running individual agents directly.

4. Limited native AI models — paperclip doesn’t host models. It connects to external APIs (OpenAI, Anthropic, local vLLM). If you need an all-in-one solution with built-in model serving, look elsewhere.

5. Learning curve — The Kanban-style task management and multi-step workflows have a learning curve. Simple use cases can be done in minutes, but complex multi-agent pipelines may take hours to configure optimally.

Frequently Asked Questions #

Q: Is paperclip a replacement for individual AI coding agents?

A: No. paperclip is an orchestration layer that manages existing agents. You still need Claude Code, Codex CLI, or whatever agents you want to coordinate. paperclip adds task management, context routing, and team coordination on top.

Q: Can I use paperclip with local models via Ollama or vLLM?

A: Yes. paperclip supports any OpenAI-compatible API endpoint, which includes Ollama (http://localhost:11434/v1) and vLLM (http://localhost:8000/v1). Simply configure the endpoint when adding an agent.

Q: How does paperclip handle API key security?

A: API keys are stored encrypted in the local database and are never exposed to agents directly. Agents receive a session token that maps to the configured API key. Keys are encrypted using AES-256-GCM with a key derived from the system’s TPM or OS keychain.

Q: Is paperclip suitable for enterprise use?

A: Yes. paperclip is designed for both individual developers and enterprise teams. It supports workspace isolation, team-based access control, audit logging, and on-premise deployment. Enterprise features include SSO, role-based permissions, and compliance reporting.

Q: Can I export my agent conversations and data?

A: Yes. All conversations, tasks, and outputs are exportable as JSON or Markdown. Use paperclip export --format json --workspace my-workspace for full export, or paperclip export --format md --workspace my-workspace --conversation <id> for a specific conversation.

# View agent status
docker exec paperclip-1 agentctl status

# Check agent logs
docker logs paperclip-1 --tail 50

# Scale agent count
docker compose up -d --scale worker=3

# Check agent workspace state
docker exec paperclip-1 statectl show

# List all agent templates
docker exec paperclip-1 template list

# Create a new agent from template
docker exec paperclip-1 agent create --template summarizer --name "daily-summary"

#

For reliable hosting infrastructure, DigitalOcean provides affordable droplets for development and testing. HTStack offers competitive pricing for production deployments. For proxy and scraping needs, WebShare provides reliable datacenter and residential proxies.

Sources & Further Reading

• Official docs: https://docs.paperclip.ai
• GitHub repository: https://github.com/paperclipai/paperclip
• Deployment modes guide: https://github.com/paperclipai/paperclip/blob/master/doc/DEPLOYMENT-MODES.md
• Docker setup: https://github.com/paperclipai/paperclip/blob/master/doc/DOCKER.md
• Community discussion: https://github.com/paperclipai/paperclip/discussions

Conclusion: Managing AI Agents as a Team Is the Future #

paperclip solves a real problem that most developers hit at scale: coordinating multiple AI agents becomes chaotic without a management layer. At 69,700 stars and growing, the demand for structured agent management is clearly real.

If you’re juggling 2+ AI agents daily — coding, reviewing, researching — paperclip gives you a Kanban board, conversation history, and deployment pipeline that turns chaos into a managed workflow. The self-hosted option means no vendor lock-in, no data leaving your infrastructure.

Join the dibi8 English Telegram group to discuss paperclip setups and agent templates. Check out our guides on [持久记忆增强Agent](https://dibi8.com/agentmemory-persi[CLI统一管理](https://dibi8.com/cc-switch-unified-ai-cli-control-center)ual workflows](agentmemory guide for related tooling. Try paperclip today — docker compose up, add two agents, and see your first multi-agent pipeline run.

Some links above are affiliate links. dibi8.com may earn a commission if you sign up, at no extra cost to you. Helps keep the site running and the content free.