## Thinking Path > - Paperclip helps people manage AI agents for work. > - The sidebar helps people return to recent tasks. > - Recent parents need foldable child tasks. > - Busy companies must not refresh every child group for unrelated work. > - Exact unread counts must preserve personal reads and task access. > - This pull request adds child groups and bounds their refresh work. > - People can scan subtasks without repeated background requests. ## Linked Issues or Issue Description **Subsystem affected** Task navigation in the standard and Classic sidebars. **Problem or motivation** Recent parent tasks did not show their subtasks. The first implementation refreshed every previously viewed group. One unrelated update caused 52 child-page requests and one summary request after viewing 50 groups. Exact child counts also repeated privacy and unread checks per child. **Proposed solution** Show direct subtasks with independent folding and ten-row pages. Refresh affected groups and summary batches. Stop offscreen reads. Bound child-request concurrency. Aggregate viewer facts once and preserve the existing inbox unread rule. **Roadmap alignment** This extends existing task navigation. The existing feature PR is reused for its performance repair. No new PR duplicates it. ## What Changed - Add shared parent groups to both sidebar layouts. Preserve Classic row actions and active-child visibility. - Keep unread state personal to each task. Folding and paging do not mark tasks read. Counts include readable children beyond ten. - Target live refreshes with authorized current and previous parent IDs. Reuse parent metadata from the narrow run-binding read. Resolve fallback lookups once per delivery batch. Keep the previous summary fallback for older servers. - Limit child requests to three at a time. Cancel active and queued reads when groups leave the viewport. - Discard extra cached pages on Show less and collapse. - Compute exact navigation counts in one SQL statement. Materialize readable candidate IDs once. Use indexed participation sources and conservative unread candidates before the shared inbox rule. - Skip recursive privacy walks for standalone open tasks without a project. Keep the recursive rule for all restricted or inherited shapes and all delegated principals. - Add request-count, cancellation, reparenting, read-receipt, inbox-parity and privacy regressions. Include a disposable PostgreSQL benchmark. - Update product and API documentation. Retain the production Storybook states. ## Verification - Published head: `4148861437c1b6b635479ad92509dbc71155a232`. Its tree matches local `04be9d66d481d9bcd1c4d6158acf063a1e65ac7e`: `a23533e93d3d155918f0254d296a7fd2f0c7c12f`. - Rebased on master `ca23330c69b1f2b25bdadfcbda68317db97deaef`. Remote publication preserves prior feature commits. - The request regression failed before the fix and passes after it. An unrelated event now sends zero child requests. Current servers also avoid the unrelated summary request. Old-server events keep one summary fallback. - A relevant update after Show less reads one page. Reparenting refreshes two affected groups. Offscreen reads stay at zero and resume once on return. Active and queued cancellation tests pass. - The same synthetic authenticated HTTP workload with 50,000 read children improved from 767 ms to 92.84 ms median. Five warm samples per case. The all-unread case improved from 463.85 to 351.65 ms. Untouched children improved from 208.01 to 131.09 ms. The old-receipt case improved from 799.70 to 245.80 ms. These local measurements are not a production capacity guarantee. - Focused PostgreSQL routes, inbox-parity, privacy and WebSocket tests passed: 38 tests. - All 325 affected UI tests passed. All 38 focused PostgreSQL, privacy and WebSocket tests passed. UI typecheck and low-memory server declaration checks passed. - All 41 Chromium Storybook checks passed. They cover 20 states in both themes and keyboard, folding, paging and unread behavior. They use production components with HTTP fixtures. - Both new review findings failed as regressions before their fixes and pass afterward. Explicit child reads include waiting external conversations. Deleting a child publishes a separate parent-authorized update without deleted-child content. Both review threads are resolved. - `pnpm verify --explain` returned exit 2 because product documentation requires broader CI. [The prior CI run](https://github.com/paperclipai/paperclip/actions/runs/43711489306) found type errors in the new test fixtures. The same errors failed locally. The fixture fix passes `node server/scripts/typecheck-layers.mjs --layer test-tree-0` and all 21 issue summary route tests. Production code is unchanged. That CI run then found a live-delivery read regression. The existing test failed locally with eight statements against its six-statement budget. A new PostgreSQL regression also found three parent lookups for two same-batch calls. Run delivery now reuses parent metadata from its narrow run-binding query. Fallback lookups resolve to one promise. Both regressions pass without increasing the budgets. All 74 targeted route, WebSocket and privacy tests pass. The affected below, above and test-tree-0 typecheck layers pass. [CI attempt 2](https://github.com/paperclipai/paperclip/actions/runs/43715541480/attempts/2) passes on the published head. All 62 check runs are terminal and clean: 57 succeeded, two were neutral and three were skipped. Typecheck, build, policy, all general and serialized server suites, E2E and the [final verify gate](https://github.com/paperclipai/paperclip/actions/runs/43715541480/job/132829783231) pass. The separate security status passes. Attempt 1's server shard 7/12 reached its 20-minute job limit without a test verdict. One retry of that job passed without a source change. [Greptile completed successfully on this head](https://github.com/paperclipai/paperclip/runs/132816163906) with a [5/5 score](https://github.com/paperclipai/paperclip/pull/21649#issuecomment-6883916606). All five review threads are resolved. The final CI gate is complete. - A full local Storybook build exceeded available memory while server typechecking ran. Browser verification uses the current-source development server. Rebuilding stale Runner and SDK declarations resolved the initial server check errors. The first browser attempt lacked Chromium; all checks passed after installation. - Reproduce the database measurements with `pnpm --filter @paperclipai/server exec tsx scripts/benchmark-sidebar-subtasks.ts`. - Extra local shard diagnosis ran 164 suites. Under this shell's `0077` creation mask, 157 suites passed and three had fixture permission or timing failures. Rerunning those three with `0022` resolved the permission failures. The remaining ten cases passed with one worker: two workspace cases and eight archive cases. The eight archive cases also passed on the pre-performance-fix revision, whose archive source is identical. The broad local shard is not claimed as one passing execution. The same-head CI retry supplies complete final CI coverage. - Nothing is merged or deployed. ## Risks - Exact counts still grow with the readable hierarchy and comment history. The change reduces repeated work; it does not cap or approximate counts. - A relevant summary batch can contain several recent parents. Older servers retain a broader summary fallback until upgraded. - Live delivery adds bounded, permission-checked parent lookups. Short delivery-window reuse limits repeated reads. - The authorization fast path applies only to open tasks with no privacy parent and no project. Restricted cases retain the shared predicate. - No migration is required. ## Model Used OpenAI Codex, based on GPT-6. Used code execution, native GitHub tools, PostgreSQL and Chromium verification. ## 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 linked a public issue or described the issue in this PR - [x] I have not referenced internal or instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal issue id - [x] I have run focused tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation - [x] I have considered and documented risks - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open findings - [x] I will address all review comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
41 KiB
Paperclip — Product Definition
Reusable workflows stay inside the Cases experiment. A workflow is a company-shared name and Markdown prompt; a case may adopt, leave and revisit workflows without changing its primary task. The task's workflow document is the effective copy, so shared edits affect future adoptions and explicit refreshes. Existing handoffs record workflow/phase movement and document revisions, including names as they were at the time. Authoring starts with agents/APIs; the case UI reads current workflow information and history.
What It Is
Paperclip is the control plane for autonomous AI companies. One instance of Paperclip can run multiple companies. A company is a first-order object.
Core Concepts
Company
A company has:
- A goal — the reason it exists ("Create the #1 AI note-taking app that does $1M MRR within 3 months")
- Employees — every employee is an AI agent
- Org structure — who reports to whom
- Revenue & expenses — tracked at the company level
- Task hierarchy — all work traces back to the company goal
Employees & Agents
Every employee is an agent. When you create a company, you start by defining the CEO, then build out from there.
Each employee has:
- Adapter type + config — how this agent runs and what defines its identity/behavior. This is adapter-specific (e.g., an OpenClaw agent might use SOUL.md and HEARTBEAT.md files; a Claude Code agent might use CLAUDE.md; a bare script might use CLI args). Paperclip doesn't prescribe the format — the adapter does.
- Role & reporting — their title, who they report to, who reports to them
- Capabilities description — a short paragraph on what this agent does and when they're relevant (helps other agents discover who can help with what)
Example: A CEO agent's adapter config tells it to "review what your executives are doing, check company metrics, reprioritize if needed, assign new strategic initiatives" on each heartbeat. An engineer's config tells it to "check assigned tasks, pick the highest priority, and work it."
Then you define who reports to the CEO: a CTO managing programmers, a CMO managing the marketing team, and so on. Every agent in the tree gets their own adapter configuration.
Each person also has a personal primary agent per company. Their first human-created agent becomes primary automatically; they can choose another from its profile. An existing primary is replaced only after confirmation. The crown appears on the profile and roster, while the primary stays first in the Agents sidebar without a sidebar crown. Stars remain independent. Task drafts, explicit assignments, and recent choices take precedence over the primary; Chat similarly reopens a valid recent conversation before falling back to the primary. Opening Chat does not start execution. This preference does not change the org chart or permissions.
Agent Execution
Agents have an Advanced tab for editing their settings across all configuration tabs as a versioned YAML document. Instructions, skills, tools, channels, trust, secret operations, API keys, and revision restore use their existing domain APIs. It edits the same configuration as the regular settings pages, validates before saving, preserves masked secrets, and rejects stale edits. See Agent configuration YAML.
Existing Claude, Codex, and Grok Build agents can upgrade from the legacy runner on their Harness / Runtime page when Paperclip Runner is the qualified default for their environment. One action saves pending edits and translates compatible settings while keeping the harness, selected model, account bindings, instructions, and history. Unsupported settings produce an actionable error without changing the saved agent. Future runs start fresh sessions.
Qualifying an existing agent's sandbox for that upgrade uses the same agent configuration permission as saving the upgrade. The server checks the saved computer and its company binding. Company owners do not need instance-admin access for this step; general instance environment management remains restricted.
Paperclip supports several ways to run an agent's heartbeat:
- Local CLI/session adapters — Paperclip starts or resumes local coding-tool sessions such as Claude Code, Codex, Gemini, OpenCode, Pi, and Cursor, then tracks the run.
- Run a command — Paperclip kicks off a process (shell command, Python script, etc.) and tracks it. The heartbeat is "execute this and monitor it."
- Fire and forget a request — Paperclip sends a webhook/API call to an externally running agent. The heartbeat is "notify this agent to wake up." OpenClaw-style hooks work this way.
- External adapter plugins — Paperclip loads adapter packages through the plugin/adapter flow so self-hosted installs can add runtimes without hardcoding them in core.
Agent runs can use project and execution workspaces, managed runtime services such as preview/dev servers, adapter-specific session state, and HTTP/webhook-style execution. We provide sensible defaults, but the adapter is still the boundary: if a runtime can be invoked, observed, and authorized, Paperclip can coordinate it.
Task Management
Task management is hierarchical. At any moment, every piece of work must trace back to the company's top-level goal through a chain of parent tasks:
I am researching the Facebook ads Granola uses (current task)
because → I need to create Facebook ads for our software (parent)
because → I need to grow new signups by 100 users (parent)
because → I need to get revenue to $2,000 this week (parent)
because → ...
because → We're building the #1 AI note-taking app to $1M MRR in 3 months
Tasks have parentage. Every task exists in service of a parent task, all the way up to the company goal. This is what keeps autonomous agents aligned — they can always answer "why am I doing this?"
The current issue model includes stable issue identifiers, parent/sub-issues, blockers, a single assignee, comments, issue documents, attachments and work products, and review/approval handoffs. That structure keeps work inspectable by both the board and agents while still allowing agents to decompose work into smaller tasks.
When an agent creates a subtask or follow-up task, its source task's feed shows a linked card at creation time with the current title, task number, and status. The Tasks tab keeps the full relationship list and shows each task once. Project groups omit tasks already shown in the other sections and disappear when empty.
Sidebar Recents shows readable direct subtasks below a recent parent. Each group can fold independently, starts with at most ten children, and loads more on request. Waiting external chat children remain visible in explicit child lists. A selected child beyond the first ten replaces the last preview row. Children already in recent history appear once under their recent root parent. Orphans remain in the main list. Standard Recents and Classic Recent Tasks use the same groups; Classic keeps its existing parent action menus. Child reads stop when a group leaves the viewport. At most three child requests run together. Show less discards extra cached pages, so the next refresh reads one preview. Live updates refresh the affected child groups and recent summary batches; permission changes clear cached children before refetching.
Unread stays personal to each task. Folding, loading children, and Show more do not mark tasks read. A folded group shows its readable unread-child count, including children beyond ten, separately from the parent's own unread marker.
Agent-owned tasks show In Progress only while a task-linked run is queued or running. When execution ends, their visible status reflects recovery (Blocked), a pending response or review (In Review), monitoring, or remaining work (Todo). The stored lifecycle status still controls execution and recovery. Human-owned tasks retain their selected ownership status.
Tasks waiting between automatic checks show Monitoring with a blue clock. Task lists, board columns, filters, search, recent navigation and task properties use the same read-only display state. The task retains its execution lifecycle status, and the monitor banner shows when the next check is due.
Automatic monitor checks pause when a task is blocked. A person can use Check now to request one check of a retained monitor through normal execution admission. Dependencies, recovery, pause, budgets and ownership still apply. Provider-usage recovery stays paused until the task resumes. A check that cannot start reports that result instead of claiming it was queued.
The experimental Cases feature also supports persistent work records and
prompt-driven agent handoffs. Native case creation requires kickoff and creates
one primary task; later handoffs move that same task
between agents with a phase and instructions. The case retains facts, document references,
and history while normal task assignments form each agent's queue. Task sessions,
workspaces, private access, review rules, and human intervention remain part of
the ordinary execution model. Ordinary task completion leaves case status unchanged.
An explicit handoff to done closes the case when primary-task completion is
accepted through the existing gates; review and human waits keep it open.
Native agents can create, read and update case facts through dedicated tools.
Creation always includes a kickoff and either workflowId or explicit workflow_document_text.
The latter becomes the primary task's Markdown workflow document, describing
phase owners, routing, evidence and completion rules. Agents read it before
choosing their next step. Recommended authoring includes both a Mermaid
stateDiagram-v2 map and prose explaining each transition's conditions, evidence,
destination agent, human waits and correction limits. Transitions remain advisory. Initial documents belong to
the first task and are saved before its agent wakes; the case displays documents
from its primary and accessible linked tasks without copying them. Agents use
ordinary task document tools; historical case-owned documents remain readable.
Each phase receives its current handoff instructions;
compatible resumed sessions receive changed facts without repeating unchanged
case contents. Agents can read current persisted data whenever they need it.
Case pages are a lightweight read-only view: search or filter the list, open a record, read its findings and documents, and follow its current task and handoff history. Agents and APIs author the records; the pages have no editing controls.
When a task is assigned to the current human, the message composer defaults to the latest agent that assigned it to them. If no assignment is available, it uses the latest other commenter, or leaves the recipient empty. A manual recipient choice stays selected while task data refreshes.
Task reply and new-task composers submit with Enter by default; Shift+Enter adds a new line. Settings → Experimental → Command/Ctrl+Enter to Submit restores the previous behavior, where Enter adds a new line and Command/Ctrl+Enter submits.
New-task submission closes the composer immediately and saves in the background. The person can start another task while earlier requests are pending. A failed save restores its submitted draft and files. If another draft is open, it stays intact and offers a retry for the saved request. Each request retains its own creation key through retries and reloads.
Routine responsibility
The routine Overview shows its responsible user beside Default agent. People with
tasks:assign can select an active company member from the name's picker.
The change creates a routine revision and applies to future automatic tasks.
Existing tasks keep their responsibility. Manual runs use the person who starts
them. Agents cannot transfer routine responsibility.
Task collection creation filters
Tasks opens All tasks for new users. A saved view or an explicit view in the URL takes precedence over this default. The task table orders rows by Last updated, newest first, without highlighting a column header. Selecting a column sort activates its header and direction arrow; explicit sort URLs retain that selection.
The task Filters menu also offers Routine tasks. It selects tasks with
originKind=routine_execution, including manually triggered routine runs, even
when other automatic tasks are hidden. The routines list's View all tasks
link opens /issues?view=all&originKind=routine_execution&sortField=created&sortDir=desc with that checkbox
selected. The URL retains the selection across reloads and task navigation.
Coordinator task labels use repeated label URL parameters so selected labels survive reloads and shared task-list links.
Sort controls save sortField and sortDir in the URL. URL sorting overrides
saved collection sorting, and the routines link opens newest-created tasks first.
Shared sort links work across Coordinator, Streamlined UI, and Classic UI, including
sort fields without a visible column in the selected interface. Search relevance
and board-column membership keep their existing server order.
Search and pagination apply the routine origin filter on the server. Creation-time
sorting also runs before pagination, with task ID as a stable tie-breaker.
Tasks and project lists hide agent-created and system-created tasks by default. The Filters menu's Show agent-created tasks checkbox includes routine runs, recovery/watchdog tasks, chat-channel tasks, and other automation. Channel tasks remain bot-created for this filter even when a human starts the conversation. The choice is saved per company and collection; Clear filters restores the hidden default. Nested lists preserve ancestors and expandable subtasks as context without promoting unrelated automated work to independent results. Agent profiles, routine histories, and task-detail subtasks retain their full history.
Mine contains personal work. Channel tasks, routine tasks, and agent-created tasks stay outside Mine by default. This includes routines that a person starts manually. Linked accounts, creator IDs, responsible-user IDs, synchronized provider comments, and read markers do not establish participation in automatic work. Direct board or human API comments, human assignment, and deliberate user mutations do establish participation. Open requests addressed to the person also admit the task until resolution. Ordinary human-created tasks keep their creator's participation. These rules apply to existing tasks, Mine, unread counts, badges, and task toasts. Approvals retain their existing recipient and permission rules.
An advisory PR review does not require human completion approval because its rating is low, CI is pending or failing, or the PR is unmerged. After publication, the bot may stay in review with an authorized provider-event wait or a saved monitor. Neither wait enrolls a person in Mine. Human requests are for concrete dependencies of the assigned review, such as missing repository access. A later published review with no human dependency withdraws the same bot's earlier completion request for a published review when its result commits and independent gates are clear. Finish-report validation is read-only. Independent approval gates and requests without that review evidence remain unchanged.
New inbound comments retain their provider in metadata.sourceChannel. Historical
imports use inbound message links or the stored provider-sender metadata. These
checks preserve direct board comments on channel tasks. If both historical
records are absent, the comment remains unclassified and keeps its previous
behavior. A task origin alone cannot prove the source of an old comment.
Inbox discovery searches and Blocked hide unrelated automatic tasks unless the checkbox is checked. The checkbox does not subscribe a person to automatic work. Source feeds and project task lists retain their existing access rules.
Company Skills and Policy
Company skills are shared operating capabilities, not privileged objects by default. Every authenticated agent in a company can create, import, install, edit, update, test, reset, and remove that company's skills unless the company has configured an explicit restriction.
Paperclip-managed skills are immutable saved versions. Studio and API authoring publish complete content before acknowledging a save; stale edits return a version conflict and Studio retains the draft. Installed repository skills use the same version-based reads and execution selection. Web-server files are disposable caches and staging, so compatible replacement servers can read, edit and deliver protected versions from the same database and remote object storage. Explicit linked-local sources retain local behavior. Active or recovering run pins prevent deletion even after an agent detaches the skill. See ephemeral-server skills for conversion, compatibility and qualification boundaries.
The governing rule is: skill permissions are opt-in restrictions, not opt-in capabilities. Missing skill grants never create a denial in an otherwise unconfigured company, and ordinary skill work does not require board confirmation, a draft-only workflow, or an activation approval.
Core Paperclip owns the skill runtime, company-boundary enforcement, policy evaluation contract, API denials, validation, path containment, secret redaction, and activity logging. Those safety invariants cannot be disabled by policy. Open-by-default skill work never authorizes arbitrary host-path reads, unsafe executable content, or policy edits: local imports and scans must stay within Paperclip-known workspace or managed-skill roots, remote sources must resolve to validated immutable content, and platform safety denials must stay distinct from optional administrative restrictions. Paperclip EE may provide detailed administration for per-agent, per-role, per-action, per-source, and protected-skill rules, but EE is not required to use skills and is not an enforcement boundary. Without EE, companies remain open by default and any already-configured restrictions continue to be enforced by core.
GitHub repositories attached to new projects automatically become skill sources. Paperclip imports their skills and checks the configured branch every five minutes, using the setup person's authorized GitHub connection. New skills import automatically unless excluded. Existing projects can adopt their repositories from Skills → Sources; existing manually imported sources preserve their selections and gain automatic updates. Refresh remains available, and operators can pause automatic updates. Independent skill sources have a searchable branch picker with the repository's default branch marked. People can also enter a branch name that is not listed. Saving checks GitHub access and the selected ref before changing tracking; failed saves keep the selection and installed content. Project refs remain owned by project configuration so changing a source cannot redirect another project's tracking. If a repository exceeds the supported package size, Paperclip first packages its skill folders and referenced repository files, preserving their original paths. Missing references are advisory: a valid selected skill can still be imported. Unavailable files are listed, and existing installed dependencies are retained when a bounded refresh cannot preserve them. File limits and content validation still apply; importing never executes repository code. Authored and unproven legacy versions retain an independent recovery copy. Unused Git packages with an exact restore recipe may expire; later use requires access to that original repository and commit. External package storage keeps repository contents out of the control-plane database; per-turn checks reuse verified local files while rechecking current skill access. See automatic storage and recovery.
Project-derived skills inherit current project access. Access through any originating project is sufficient, including the responsible-user restrictions on agent execution. Existing explicit company imports retain their visibility. Editable copies inherit project restrictions; private content cannot be published or exported implicitly. Detachment retains installed content and access provenance. Deleting its last project never makes a skill company-visible.
Task and routine skill mentions remain stable references to the latest installed version. Each execution records the immutable versions it uses; resuming keeps those versions, while a new execution resolves latest again. Upstream failures and removals preserve installed snapshots. GitHub refresh does not delay task execution.
Old, unused skill-version disk caches expire automatically while current and in-use versions remain. Saved database snapshots rebuild an expired copy on demand, including when its upstream repository is unavailable. Recovery data has separate retention.
Disconnecting removes a repository from Sources after an explicit choice: keep independent editable copies in My Skills, or delete its imported skills. Kept copies and derived forks retain their project access restrictions. Copies preserve agent assignments; skills used by agents must be detached before deletion.
An explicit restricted policy may deny selected operations or switch to a default-deny preset with explicit allow rules. Core exposes a stable versioned policy API so EE and other administrative clients configure and simulate the same evaluator used by skill mutation routes. Core Skill Studio only needs to perform normal skill work, explain an explicit denial, and point administrators to EE when its richer policy UI is available; it must not recreate a partial enterprise permission editor.
Principles
-
Unopinionated about how you run your agents. Your agents could be OpenClaw bots, Python scripts, Node scripts, Claude Code sessions, Codex instances — we don't care. Paperclip defines the control plane for communication and provides utility infrastructure for heartbeats. It does not mandate an agent runtime.
-
Company is the unit of organization. Everything lives under a company. One Paperclip instance, many companies.
-
Adapter config defines the agent. Every agent has an adapter type and configuration that controls its identity and behavior. The minimum contract is just "be callable."
-
All work traces to the goal. Hierarchical task management means nothing exists in isolation. If you can't explain why a task matters to the company goal, it shouldn't exist.
-
Control plane, not execution plane. Paperclip orchestrates. Agents run wherever they run and phone home.
User Flow (Dream Scenario)
- Open Paperclip, create a new company
- Define the company's goal: "Create the #1 AI note-taking app, $1M MRR in 3 months"
- Create the CEO
- Choose an adapter (e.g., process adapter for Claude Code, HTTP adapter for OpenClaw)
- Configure the adapter (agent identity, loop behavior, execution settings)
- CEO proposes strategic breakdown → board approves
- Define the CEO's reports: CTO, CMO, CFO, etc.
- Each gets their own adapter config and role definition
- Define their reports: engineers under CTO, marketers under CMO, etc.
- Set budgets, define initial strategic tasks
- Hit go — agents start their heartbeats and the company runs
Guidelines
There are two runtime modes Paperclip must support:
local_trusted(default): single-user local trusted deployment with no login frictionauthenticated: login-required mode that supports both private-network and public deployment exposure policies
Canonical mode design and command expectations live in doc/DEPLOYMENT-MODES.md.
Further Detail
See TASKS.md for the task management data model.
Paperclip’s core identity is a control plane for autonomous AI companies, centered on companies, org charts, goals, issues/comments, heartbeats, budgets, approvals, and board governance. The public docs are also explicit about the current boundaries: tasks/comments are the built-in communication model, Paperclip is not a chatbot, and it is not a code review tool. The roadmap already points toward easier onboarding, cloud agents, easier agent configuration, plugins, better docs, and ClipMart/ClipHub-style reusable companies/templates.
What Paperclip should do vs. not do
Do
- Stay board-level and company-level. Users should manage goals, orgs, budgets, approvals, and outputs.
- Make the first five minutes feel magical: install, answer a few questions, see a CEO do something real.
- Keep work anchored to issues/comments/projects/goals, even if the surface feels conversational.
- Treat agency / internal team / startup as the same underlying abstraction with different templates and labels.
- Make outputs first-class: files, docs, reports, previews, links, screenshots.
- Provide hooks into engineering workflows: worktrees, preview servers, PR links, external review tools.
- Use plugins for edge cases like rich chat, knowledge bases, doc editors, custom tracing.
Do not
- Do not make the core product a general chat app. The current product definition is explicitly task/comment-centric and “not a chatbot,” and that boundary is valuable.
- Do not build a complete Jira/GitHub replacement. The repo/docs already position Paperclip as organization orchestration, not focused on pull-request review.
- Do not build enterprise-grade RBAC first. Paperclip now has authenticated mode, company memberships, instance roles, and permission grants, but fine-grained enterprise governance should remain secondary to the core company control plane.
- Do not interpret agent-profile privacy flags as project/issue privacy. Work remains company-open by default, while explicitly private issues and projects use their own task ACLs.
- Do not lead with raw bash logs and transcripts. Default view should be human-readable intent/progress, with raw detail beneath.
- Do not force users to understand provider/API-key plumbing unless absolutely necessary. There are active onboarding/auth issues already; friction here is clearly real.
Specific design goals
-
Time-to-first-success under 5 minutes A fresh user should go from install to “my CEO completed a first task” in one sitting.
-
Board-level abstraction always wins The default UI should answer: what is the company doing, who is doing it, why does it matter, what did it cost, and what needs my approval.
-
Conversation stays attached to work objects “Chat with CEO” should still resolve to strategy threads, decisions, tasks, or approvals.
-
Progressive disclosure Top layer: human-readable summary. Middle layer: checklist/steps/artifacts. Bottom layer: raw logs/tool calls/transcript.
-
Output-first Work is not done until the user can see the result: file, document, preview link, screenshot, plan, or PR.
-
Execution visibility without log worship Active runs, recovery issues, blockers, and work products should be first-class surfaces. Raw transcripts are available when needed, but they are not the primary product surface.
-
Local-first, cloud-ready The mental model should not change between local solo use and shared/private or public/cloud deployment.
-
Safe autonomy Auto mode is allowed; hidden token burn is not.
-
Thin core, rich edges Put optional chat, knowledge, and special surfaces into plugins/extensions rather than bloating the control plane.
Experimental iMessage Photon channel
A Photon Cloud project can represent one agent through the existing experimental channel subsystem. DMs and explicitly enabled groups create or continue task-bound conversations. Linked sender identity is the default; telephone numbers, email addresses, names, and group membership do not grant Paperclip authority. Photos/files and ordinary questions/confirmations use the existing attachment, interaction, continuation, and publication contracts. Pause and Disconnect govern runtime behavior independently of the UI gate. Local Mac access, unsolicited conversations, and SMS/RCS fallback are excluded. Live qualification is required before release readiness. Pro shared allocation supports DMs only, with sender enrollment in Photon and separate identity linking in Paperclip. Shared channels reserve one project, not a pool phone number; group admission and publication are disabled. Dedicated allocation retains one selected number and individually enabled groups.
See iMessage Photon for the implementation contract, setup, recovery, boundaries, and qualification status.
Persistent agent conversations
Agents can deliver proactive task and routine results into their own chat with the task's responsible human. A morning PR digest arrives as an agent message with a source-task link and unread indicators, even before the first human message. The person can reply using the digest as context. Publishing a message and completing work are separate actions; sending never starts or interrupts a chat turn. Delivery obeys membership, run authority and task privacy. This version delivers in-app only.
Coordinator is the standard workspace for everyone. Settings → Experimental offers a personal Classic workspace opt-in, off by default. Historical Coordinator experiment settings do not enable Classic. Agent Chat is available to everyone on new and existing instances. The retired enableAgentChat key remains accepted for compatibility; stored and managed off values are ignored. Each person has one persistent task-backed conversation per agent and company, with ordinary company task visibility. The shared task composer, transcript, tools, files, and document panel remain the interaction surface. Agents clarify goals and hand substantial execution to linked, assigned tasks; a reply ends a turn without completing the conversation. /new starts fresh provider context in the same conversation while preserving visible history and artifacts. Healthy idle conversations wait for a message and do not count as unfinished execution work. See doc/plans/2026-09-10-agent-chat.md for the implementation contract.
Slack task progress
Slack threads reuse one editable progress message for each active run. Native runtimes with an explicit public progress channel can supply a short completed commentary note, up to 400 characters, plus a task link when a public board URL is configured. The server coalesces bursts, suppresses repeated text, allows a 10-second initial grace period, and waits at least 30 seconds between updates. A pending note is recovered from run events and the publication outbox after a restart. Delivery receipts wake the progress owner; idle history does not poll.
Reasoning, unknown assistant channels, raw tool output, and provider diagnostics cannot supply progress prose. Providers without a public channel retain factual lifecycle fallbacks. Questions, approvals, and final answers bypass the progress cooldown. Slack final answers use a fresh reply, so users can see completion without watching message edits. After the answer is sent, a generic working message changes to “Response sent.” A useful public note stays in place. Registered run secrets are redacted before progress text is saved or sent. Other connectors retain their delivery policy.
Agent chat project handoff (2026-09-11)
Chat supports research and full plan drafting/revision in its existing plan document. On handoff, each ordinary assigned task receives the relevant plan in its own plan document, committed with task creation before execution is scheduled. The source plan remains in the conversation. Plan acceptance hands off execution; it never switches the conversation into implementation.
Chat instructions require selecting a suitable project, reusing an existing one where appropriate. The project requirement is prompt-only; ordinary projectless tasks remain supported. New parent relationships beneath conversation tasks are rejected by task services, including direct API creation and reparenting. Existing children remain readable/editable and can be moved elsewhere. The Subtasks panel is unchanged.
The create_project runtime tool uses the normal project API with durable idempotency. list_projects and list_project_repositories support selection. Multiple repositoryIds select authorized catalog entries; multiple HTTPS GitHub repositoryUrls register existing repositories absent from the catalog. IDs and URLs may be combined, but cannot accompany an explicit workspace. URLs do not create repositories on GitHub or grant credentials. Execution uses normal repository access rules. Repository IDs are revalidated against the authenticated run's responsible user and connection grants. Agents should consider proper available repositories, clarify material ambiguity, and use repository-free projects when appropriate for non-code work.
Confirmed project creation appears as a durable card in the shared task transcript, including selected repository links. Tasks are linked inline. Failed creation never produces a success card. Tool evals cover planning/handoff, project/repository selection, retries, permission and mode denials, and ordinary delegation regressions using the production chat directive.
In-app announcements
An optional announcement card shares product news with board users on opening or returning to Paperclip. Dismissals persist per user across companies and browsers within an instance. Operators can disable fetching independently of telemetry. See Announcements.
Agent chat discovery
With Agent Chat enabled, Chat is the first row of the Work section and opens a secondary sidebar beside the primary nav. It lists every agent you can chat with: pinned agents first in their saved order, then your conversations by recent activity, then the rest of the roster alphabetically. Pin controls appear on hover or keyboard focus. Drag a pinned agent's handle to change the order, or use Space, the arrow keys, and Space again. Pin order stays personal to the signed-in user in the current browser. Search filters the list without changing hidden pins. Terminated agents and agents you have left are omitted unless you have history with them. Search filters by name, title, or role; + starts or reopens a conversation. Selecting an agent opens their persistent conversation; it does not reset history or create a task until the existing first-write flow requires one.
Beside a conversation, the side panel opens on the agent's tasks: one card per task the agent created, was assigned, commented on, or acted on, newest first, with the task list's filters and a sort control. The agent's artifacts are a second card stack available from the panel's + menu. Both open in a new tab so the conversation stays open.
Coordinator Inbox and personal task views
Coordinator navigation uses Chat, Tasks, and Inbox. Inbox uses the
inbox icon and keeps the existing decision feed, its count, and decision history
at /decisions. The previous Inbox destination under More is removed.
Inbox opens with Assigned to you. Its assignee filter can show all accessible assignees, a particular person, ownerless requests, or company alerts. Cards for someone else prepend that person's name to the action label; your own cards omit your name. Routing validates who may reassign a request and whether its recipient may answer it.
Decision, problem, and update cards use the compact Paper design. Each type keeps its own context and supported actions, with the primary action at the right of the footer. Plans, documents, attachments, and approval details open in sidebar tabs and highlight their source card. Confirmation and approval revision drafts and pending submissions synchronize across review views. Other requests keep one editable form on the inbox card while their supporting artifact is open, so a second form cannot submit an older answer. Claim, transfer, personal archive/snooze, withdrawal, receipts, and personal history retain their multiplayer behavior and update open views through live events.
Tasks defaults to All tasks, with a saved view per person and company. Mine uses
the previous Inbox's personal participation rules, mixed attention items,
read/unread title weights, keyboard shortcuts, archive and undo, mobile
swipe-to-archive, grouping, and saved columns. Its existing preferences carry
over. Unread, Recent, Blocked, and Everything are also task views. Organization
views retain the task table and board. The table saves column selection and
order per person and company. Old /inbox/* links redirect to their Tasks view.
Combined Inbox + Task List
In the Classic workspace, an opt-in setting (enableCombinedInboxTasks, off by default)
folds Inbox into Tasks. The Inbox nav row goes away and its unread badge moves
to Tasks. A Views menu on the task list covers the inbox views (Mine, Unread,
Blocked, Recent, Everything) and the task-status views (All, Active, Backlog,
Done). Bare /issues opens the last-used view, defaulting to All tasks; links that
carry a task filter open All. Old /inbox links redirect to the matching view.
CSV file previews
Task attachment and workspace file tabs render CSV files as tables by default. The first record supplies column headers. Row numbers, row and column counts, and sticky headers help operators scan exports. Rendered and raw view icons remain next to download; raw view preserves the original source. The table shows up to 500 data rows and 100 columns, with a notice when the preview is limited. Download retains the complete file.
Filesystem access boundary (2026-10-20)
Filesystem isolation belongs to the OS, execution environment, and storage layout. Paperclip authorizes the current task/run, company, explicitly selected configuration, execution policy, and repository credentials. It does not infer file permissions from other tasks or agents that previously used the same directory, overlapping roots, symlink aliases, or shared Git storage. Existing files under an authorized task root may be read subject to OS access and API path containment.
Private task records, comments, attachments, run logs, full workspace metadata, and
operation logs retain their app authorization. Workspace _issuePrivacySources and
operation privacy metadata protect app-record disclosure; they do not grant or deny
filesystem execution or task-bound file browsing. Current trust and sandbox policy,
publication receipts, binding checks, and lifecycle locks remain authoritative.
Agent connection administration (2026-10-13)
Standard agents can configure connections through the same domain APIs used by the app, bounded by their grants and their responsible user's current authority. Fresh standard agents for default Operators can manage app/tool connections, chat/email channels, AI accounts and pools, profiles and gateways without additional grants. Existing grants are not backfilled; explicit restrictions persist. Gateway administration retains the responsible human's administrative permission and does not grant agents blanket tools:admin.
The agent performs authorized setup, reuses saved accounts and drafts, and hands off only required human authentication, consent, credential entry or identity confirmation. Saved handoffs resume through existing task continuation after current authority is rechecked. Management, tool execution and approval remain separate. Private accounts, host commands and stored credentials retain their boundaries; agent-issued gateway clients preserve issuer and responsible-user restrictions at use time.
Authorized policy administration includes user-requested changes that loosen the acting agent’s own tool controls. These writes remain bounded by management grants, resource scope and the responsible user’s current authority; they do not need an additional approval solely because the agent is a target. Subsequent tool calls obey the resulting policy. Agents cannot approve their own governed action requests or edit their own principal permission grants.
Ordinary tool approvals remain reviewable without an implicit one-hour deadline. Authenticated OAuth refresh preserves a pending approval for the same saved action and authorization. Sign-in repair retains an accepted decision and resumes through connection-change events after revalidation; changed consent, permissions, credentials or action targets require a new review. Current access, explicit deadlines, task closure and execution receipts remain enforced.
The implementation, operation inventory, permission matrix and fixture qualification are recorded in Agent API parity for connection configuration. Provider fixtures establish API behavior; they do not constitute live provider setup or an empirical agent-success claim.
Budget control behavior
Paperclip records paid-operation charges durably and avoids company-wide serialization during receipt ingestion and settlement. Budget checks and threshold enforcement are best effort. Concurrent operations can start from the same observed balance; estimates and provider caps do not replace the actual bill. A background worker applies threshold holds and scoped Stop intent. Manual Stop and authorization remain independently enforced. Unknown charges remain visible, and stale unevaluated accounting blocks new limited-budget work until reconciliation catches up.