Building Paperclip: The AI agent orchestration platform that almost didn't happen

A year ago, I was drowning in AI tool sprawl.

Every week there was a new LLM provider, a new vector database, a new agent framework. My team was spending 40% of our engineering time just stitching together different AI services — writing glue code, managing API keys, handling rate limits, retrying failed calls, and trying to keep state consistent across half a dozen services.

The breaking point came when we lost three days of work because an agent workflow failed mid-execution and we had no way to resume from where it left off. No checkpointing, no recovery, no visibility into what went wrong.

That's when I started building Paperclip.

The problem

Most "AI agent frameworks" at the time were designed for demos, not production. You could chain a few LLM calls together in a Jupyter notebook, but deploying that to handle real users was a completely different beast. You'd need:

• Reliable task scheduling and retry logic
• State persistence across agent interactions
• Observability into what agents are actually doing
• A way to manage different LLM providers and swap between them
• Multi-agent coordination that doesn't fall apart under load

Existing tools handled maybe one or two of these. Nothing covered the full stack.

The early prototype

I started hacking on a prototype during nights and weekends. The core idea was simple: what if managing AI agents felt like using Kubernetes for containers? Declarative configs, automatic scaling, built-in resilience, and a CLI that makes the complex stuff feel simple.

The first version was terrible. I showed it to three friends who all nodded politely and changed the subject. But the concept was there — a YAML-based config where you define your agents, their tools, and how they communicate, then the platform handles the rest.

Going open source

After two months of iteration, I had something that worked for my own use cases. I made the call to open-source it with an MIT license. The reasoning was: AI infrastructure needs to be transparent. If you're building on top of AI, you need to know exactly what your stack is doing, and open source is the only way to guarantee that.

The launch on GitHub was quiet — just a README, some docs, and a working CLI. I posted it on Hacker News and went to bed expecting nothing.

I woke up to 2,000 stars and a hundred issues. People actually wanted this.

What we've built

Paperclip is now an open-source platform for managing AI agent teams. Here's what it does:

• Multi-agent orchestration — Define agents that can delegate tasks to each other, share context, and work in parallel
• Provider-agnostic — Swap between OpenAI, Anthropic, Google, open-source models, or your own fine-tuned models
• State management — Automatic checkpointing and recovery, so no work is ever lost
• Observability — Full logging of every agent action, thought, and decision
• CLI-first — Designed for developers who live in the terminal
• Extensible — Plugin system for adding custom tools, memory backends, and model providers

The project is at 73K+ GitHub stars and growing. We've had contributions from over 200 developers.

The hard lessons

Building Paperclip taught me things no blog post could:

1. APIs change constantly. By the time we shipped a feature for one LLM provider, their API had already changed. We learned to build abstraction layers that could absorb breaking changes without affecting users.

2. State is the hardest problem. Keeping agent state consistent across failures, retries, and parallel executions is genuinely difficult. We went through three state management architectures before landing on the right one.

3. Developers hate magic. Early on, we tried to make things "just work" with smart defaults. Users asked for explicitness — they wanted to configure everything, control everything, and understand everything. We shifted to being transparent by default.

4. Performance matters. Agent orchestration introduces latency. Every decision point, every context switch, every state save adds milliseconds. We optimized ruthlessly, but the complexity of coordination means there's always more to do.

5. Community expectations grow fast. When you're at 73K stars, people expect enterprise-grade reliability from what started as a side project. We're still catching up to those expectations.

What's next

We're focused on three things:

1. Stability — Making sure Paperclip can handle production workloads at any scale
2. Developer experience — The CLI should be delightful, not just functional
3. Ecosystem — Growing the plugin system so anyone can extend Paperclip

We're also working on a hosted version for teams that don't want to self-host, with managed infrastructure, team collaboration, and enterprise SSO.

If you're building something

The best advice I can give is: build for your own pain. If you're not a user of your own product, you'll lose motivation when things get hard. Paperclip exists because I needed it. Every feature we add solves a problem I've personally had.

Also: open source your infrastructure layer. It's scary because competitors can see your code, but the trust and community you build is worth more than any moat your code could create.

Join us

Paperclip is MIT-licensed at github.com/paperclipai/paperclip. We'd love your contributions, issues, and feedback.

Building in public has been the most rewarding experience of my career. If you're working on AI infrastructure or building developer tools, I'd love to connect.

— The Paperclip Team