Files
DottaandPaperclip d1f3e7bb0d docs: refresh README capabilities and roadmap (#14741)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The README introduces the product and directs people to setup and
the roadmap.
> - The product now supports more harnesses, connections, skills, and
team workflows than the README shows.
> - Some copy still describes available features as future work or makes
claims broader than the implementation.
> - This pull request updates the README and matching roadmap entries
from current source evidence.
> - Readers can see what they can use, what requires setup, and what
remains experimental.

## Linked Issues or Issue Description

**Issue type**

Outdated information and missing documentation.

**Where is the issue?**

README.md feature descriptions, four pillars, setup, FAQ, and roadmap;
related entries in ROADMAP.md.

**What's wrong?**

The README omits supported adapters and major connection and skills
workflows. It presents Connected Apps and Agent Chat as wholly future
work. Some budget, audit, and approval descriptions also need more
precise wording.

**Suggested fix**

Keep the existing structure, four-pillars picture, and completed roadmap
milestones. Extend the four-pillars table without removing its existing
content. Add concise descriptions of supported features. Correct
capability and setup claims. Distinguish available, experimental, and
planned work, and explain that the roadmap follows the default branch.

Searched open README and roadmap PRs and related documentation issues.
Refs #14640, which proposes a separate launch-video update; this change
preserves the existing video.

## What Changed

- Expand adapter coverage and describe model choice alongside durable
team context.
- Add six feature cards: connections, personal identities for shared
agents, Skill Studio, routines, artifacts and feedback, and team
templates.
- Describe experimental agent conversations and external chat/email
entry points.
- Correct budget, audit, approval, goal, session, secret, portability,
and multi-organization claims.
- Qualify export portability: plain environment values and local paths
can remain, so packages need review before sharing.
- Retain the four-pillars image and all existing table content; add
connection identities, skill history, team templates, and run history.
- Correct mention wake behavior, persistent npx data, source-build
prerequisites, and hosting guidance.
- Retain all 18 completed README roadmap milestones and its original
closing sentence. Add seven completed milestones: Connected Apps,
personal/shared AI accounts, Shared Agents Use Personal GitHub
Identities, skill version history, document comments and revisions,
company-wide search, and mixed-model/harness teams.
- Keep the README’s yellow roadmap entries to their names. Expand the
new milestones in ROADMAP.md alongside the existing status updates for
agent chat, memory, recovery, evaluations, and queue scope.
- Preserve all existing top-level section headings and their order. No
runtime files change.

Research: reviewed 393 candidate change summaries from a 60-day history
of 1,274 non-merge commits, then checked relevant implementation,
feature defaults, contracts, and current public adapter documentation.
The main gaps span adapters, connections, responsible identities,
skills, routines, deliverables, teams, chat/memory status, governance
claims, and setup.

Suggested follow-up work: refresh the product demo; add three concrete
use cases; shorten Quickstart by moving secondary setup paths into the
docs.

## Verification

- Passed: `git diff --check`.
- Passed: local link and asset targets, Markdown anchors, and HTML table
nesting in both edited files.
- Passed on the earlier revision: rendered README inspection on GitHub,
including the new feature cards and roadmap status labels.
- Passed: exact restoration checks for the original picture and both
requested passages, preservation of every original pillar-table cell,
and all 18 original checked roadmap items.
- Passed on this revision: seven new green milestones synchronized
between README.md and ROADMAP.md, three short yellow labels, local link
targets, table markup, and verification that README edits are confined
to its roadmap.
- Verified new milestone claims against AI Connections and managed
GitHub identity contracts, Skill Studio restore behavior, document
annotation/revision routes, company search, and the adapter registry.
- Passed on the earlier revision: `pnpm -r typecheck`.
- Passed on the earlier revision: `pnpm build`. No runtime code changed
in this documentation follow-up.
- `pnpm test:run` reported a failure in unchanged native-session
recovery code. Stopped the broader local run after reproducing it with
`pnpm exec vitest run --project @paperclipai/server
server/src/services/native-runtime/native-session-resume.test.ts
--no-file-parallelism --maxWorkers=1`: 40 passed, 1 failed. The failing
case is “archives a damaged prior epoch before completing guarded
same-task replacement with real runnerd”;
`retainedNativeCleanupJournalMatches` returned false at line 1125. The
full local suite did not complete.
- Previous revision `4bef0af3da13b03875efacd9e1f165bc69932b25` received
Greptile 5/5; the export wording finding remains addressed. A fresh
review is pending for this documentation follow-up.
- CI remains pending. This PR remains a draft; local runtime tests are
not green.
- Checked feature claims against the adapter registry, feature catalog,
Connections contracts and action UI, skill and team services, task
semantics, deployment docs, and source startup code.
- Browser suites were not run. This change edits documentation only.

## Risks

Low runtime risk: only README.md and ROADMAP.md change. The default
branch can lead published packages, so the roadmap now links to release
notes. Provider setup and feature flags still affect availability. Live
provider integrations were not requalified for this documentation pass.

## Model Used

OpenAI GPT-6 via Codex. The exact model variant and context-window size
were not exposed in this session. Used repository research, reasoning,
shell tools, and documentation editing. No subagents were used.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-09-30 13:02:58 -05:00

11 KiB

Roadmap

This document expands the roadmap preview in README.md.

Paperclip is still moving quickly. The list below is directional, not promised, and priorities may shift as we learn from users and from operating real AI companies with the product.

Status tracks the default branch: ✅ available, 🟡 partial or experimental, ⚪ planned. Check release notes for packaged versions. Some capabilities require instance settings, plugins, or provider setup.

We value community involvement and want to make sure contributor energy goes toward areas where it can land.

We may accept contributions in the areas below, but if you want to work on roadmap-level core features, please coordinate with us first in Discord (#dev) before writing code. Bugs, docs, polish, and tightly scoped improvements are still the easiest contributions to merge.

If you want to extend Paperclip today, the best path is often the plugin system. Community reference implementations are also useful feedback even when they are not merged directly into core.

Milestones

✅ Plugin system

Paperclip should keep a thin core and rich edges. Plugins are the path for optional capabilities like knowledge bases, custom tracing, queues, doc editors, and other product-specific surfaces that do not need to live in the control plane itself.

✅ Get OpenClaw / claw-style agent employees

Paperclip should be able to hire and manage real claw-style agent workers, not just a narrow built-in runtime. This is part of the larger "bring your own agent" story and keeps the control plane useful across different agent ecosystems.

✅ companies.sh - import and export entire organizations

Reusable companies matter. Import/export is the foundation for moving org structures, agent definitions, and reusable company setups between environments and eventually for broader company-template distribution.

✅ Easy AGENTS.md configurations

Agent setup should feel repo-native and legible. Simple AGENTS.md-style configuration lowers the barrier to getting an agent team running and makes it easier for contributors to understand how a company is wired together.

✅ Skills Manager, Skill Studio & Skills Store

Agents need a practical way to discover, install, create, test, and share skills without every setup becoming bespoke. Skills Manager, Skill Studio, and the Skills Store make the skills layer reusable across an organization and easier to operate.

✅ Scheduled Routines

Recurring work should be native. Routine tasks like reports, reviews, and other periodic work need first-class scheduling so the company keeps operating even when no human is manually kicking work off.

✅ Better Budgeting

Budgets are a core control-plane feature, not an afterthought. Better budgeting means clearer spend visibility, safer hard stops, and better operator control over how autonomy turns into real cost.

✅ Agent Reviews and Approvals

Paperclip should support explicit review and approval stages as first-class workflow steps, not just ad hoc comments. That means reviewer routing, approval gates, change requests, and durable audit trails that fit the same task model as the rest of the control plane.

✅ Multiple Human Users

Paperclip needs a clearer path from solo operator to real human teams. That means shared board access, safer collaboration, and a better model for several humans supervising the same autonomous company.

✅ Cloud / Sandbox agent support

Sandbox provider plugins support remote execution while preserving the Paperclip control-plane model. Providers include E2B, Cloudflare, Daytona, Modal, Novita, and Kubernetes. Execution requires a configured provider and a compatible adapter; environment and isolated-workspace surfaces depend on instance settings.

✅ Artifacts & Work Products

Paperclip should make outputs first-class. That means generated artifacts, previews, deployable outputs, and the handoff from "agent did work" to "here is the result" should become more visible and easier to operate.

✅ Deep Planning (planning mode, revisioned plans, plan approvals)

Some work needs more than a task description before execution starts. Deeper planning means a dedicated planning mode, revisioned plans, and explicit plan approvals for strategy-heavy work before agents begin execution.

✅ Enforced Outcomes (watchdogs, recovery actions, review gates)

Paperclip should get stricter about what counts as finished work. Watchdogs, recovery actions, and review gates keep execution moving toward clear outcomes like merged code, published artifacts, shipped docs, or explicit decisions instead of vague status updates.

✅ MCP Tool Gateway & Apps (governed tool access)

MCP tools and apps should be available through a governed gateway instead of unmanaged direct access. Paperclip can apply company boundaries, approval gates, and activity attribution while giving agents the tools they need.

✅ Secrets Manager with per-agent access

Secrets need to be centrally managed without giving every agent every credential. Per-agent access, scoped bindings, and audited resolution keep sensitive integrations usable while preserving least privilege.

✅ Activity log & action attribution

Operators need a durable record of what changed and who initiated it. Activity history and clear action attribution make human, agent, and system actions inspectable across the control plane.

✅ Bounded run recovery

Recovery policies handle supported transient failures and interrupted runs, retain task ownership, and surface recovery actions when work needs human intervention. Retries are bounded and remain subject to budgets, approvals, and pause gates.

✅ Agent evals & feedback

Skill Studio provides saved test inputs, test runs, results, and version history. Task and document feedback helps people improve procedures. Automatic organizational learning remains a separate roadmap item below.

✅ Connected Apps

Apps and Connections provide a service catalog, custom MCP connections, personal and shared accounts, agent access controls, and per-action Allowed / Ask first / Off policies. Supported AI accounts also use Connections. Setup varies by provider and deployment; not every integration is one-click. Broader provider coverage and simpler setup remain ongoing work.

✅ Personal & Shared AI Accounts

Connect supported subscription accounts or API keys and choose personal defaults or shared accounts for compatible agents. Human access and agent eligibility are separate controls; account selection stays independent of the model and harness. See AI Connections.

✅ Shared Agents Use Personal GitHub Identities

Shared agents can use the GitHub identity of the person whose instructions they are executing. Managed Git and GitHub operations resolve that identity through delegation and follow-up work, subject to connection permissions. See GitHub identity during agent execution.

✅ Skill Version History & Restore

Save skill versions, inspect earlier contents, and restore a previous version as a new revision. Saved test inputs and results support comparison as procedures evolve.

✅ Document Comments & Revision History

Leave comments on specific passages in task documents, follow revision history, and restore previous document revisions. Annotations carry into agent review context so feedback stays attached to the work.

Search tasks, comments, documents, agents, projects, and artifacts within company access boundaries. Filters and matching excerpts help people find relevant work and its outputs.

✅ Multi-Model & Multi-Harness Teams

Choose models and supported harnesses per agent while keeping tasks, skills, and history in one organization. Built-in adapters cover Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Pi, Hermes, Grok, Kimi Code, OpenClaw, and process or HTTP integrations.

🟡 Memory / Knowledge

Experimental memory connections support Mem0, Zep, Supermemory, Cognee, and Honcho. The optional LLM Wiki plugin provides another knowledge workflow. A broader memory and knowledge surface for companies, agents, and projects remains a direction for future work. See memory connections for setup and availability.

⚪ MAXIMIZER MODE

This is the direction for higher-autonomy execution: more aggressive delegation, deeper follow-through, and stronger operating loops with clear budgets, visibility, and governance. The point is not hidden autonomy; the point is more output per human supervisor.

⚪ Work Queues

Paperclip should support queue-style work streams for repeatable inputs like support, triage, review, and backlog intake. That would make it easier to route work continuously without turning every system into a one-off workflow. Existing decision queues group items awaiting input; this milestone concerns continuous work intake and routing.

⚪ Self-Organization

As companies grow, agents should be able to propose useful structural changes such as role adjustments, delegation changes, and new recurring routines. The goal is adaptive organizations that still stay within governance and approval boundaries.

⚪ Automatic Organizational Learning

Paperclip should get better at turning completed work into reusable organizational knowledge. That includes capturing playbooks, recurring fixes, and decision patterns so future work starts from what the company has already learned.

🟡 Agent Chat (including CEO Chat)

Experimental Agent Chat provides persistent conversations with any agent, including leadership. Conversations keep their history and plans, then hand execution off to linked tasks. Agent Chat is off by default. Experimental chat and email connectors provide additional entry points through configured external services; they have separate setup and access controls.

🟡 Cloud deployments

Local-first remains important, but Paperclip also needs a cleaner shared deployment story. Teams should be able to run the same product in hosted or semi-hosted environments without changing the mental model.

Shipped so far: multi-tenant isolation with per-company JWT keys and company-scoped cloud tenants, portable company Import/Export (zip bundles that move a company between instances, local or cloud), and cloud-managed instance bootstrap. Next: a blob-store relay so large instances can move without a hand-carried bundle.

⚪ Desktop App

A desktop app can make Paperclip feel more accessible and persistent for day-to-day operators. The goal is easier access, better local ergonomics, and a smoother default experience for users who want the control plane always close at hand.

⚪ Bring-your-own-ticket-system (Asana / Linear / Jira as on-ramps)

Existing ticket systems should be able to feed work into Paperclip without becoming the agent control plane themselves. Asana, Linear, and Jira can act as familiar on-ramps while Paperclip owns execution, governance, and outcomes.