Give your agents life.
Request access
click a block to dive in + hear it · Ctrl+scroll/pinch zooms · drag pans · Esc resets · 🔊 mutestap a block to dive in and hear it · pinch to zoom · drag to pan · ▶ tour plays the story
MAKE PAPERCUSP YOURS make it on your machine · share it on the Cupboard · anyone can install it YOUR WORKSPACE private · instant · nothing is listed until you publish THE CUPBOARD shared · pinned to a commit · reviewed 02 · Make it — on your own machine ⊕ more inside Make it on your own machine ask your agent in plain words or write the file yourself some are captured for you MAKE IT — four ways in ask your agentwrite it yourself captured for youeditors in the app say what you want in plain words — it calls meta:define-tool, identities:create, rubrics:propose, plans:new and more a rule is a rule.json in its own folder, read against a strict schema — an invalid rule is skipped, never half-applied recipes save themselves when your agents run multi-step tool sequences (code:run) themes: the theme editor in Settings → Personalization apps: start from a template with templates:new-app 02 01 · Use it — local, private, instant ⊕ more inside Use it it lives in your workspace private · instant nobody else sees it until you publish TWO WAYS TO CUSTOMIZE Local private · instant The Cupboard shared · versioned · reviewed made in your own workspace and used right away nothing is listed anywhere until you decide to publish a rule only switches on when an identity pins it published from a public GitHub repo, pinned to a commit — everyone installs exactly the listed version most kinds are reviewed before they appear 01 WHAT YOU CAN MAKE · one tile per kind · zoom in for how to make and share it Tools — new actions your agents can take Tools new actions for agents listed immediately ⊕ TOOLS listed immediately MAKE ITSHARE ITREVIEW ask your agent for the tool you need — it defines one with meta:define-tool package it as a code-tool pack: cupboard:publish-plugin listed immediately, pinned to a commit Identities — a named agent persona Identities a named agent persona reviewed ⊕ IDENTITIES reviewed MAKE ITSHARE ITREVIEW identities:create — or start from an existing identity and change it with blueprint:extend blueprint:publish reviewed before it is listed selling an identity, per use · coming soon Rules — automatic reactions and guards Rules reactions and guards reviewed ⊕ RULES reviewed MAKE ITSHARE ITREVIEW a rule.json + listing.json in its own folder: ~/.papercusp/rules/installed/ — checked against a strict schema cupboard:publish-rule reviewed · on once an identity pins it your agent writing rules · coming soon Events — named things that happen Events named things that happen reviewed ⊕ EVENTS reviewed GET THEMSHARE ITREVIEW your own event types: not yet — install an event package with cupboard:install-event cupboard:publish-event reviewed before it is listed your agent defining events · coming soon Themes — how your workspace looks Themes how your workspace looks listed immediately ⊕ THEMES listed immediately MAKE ITSHARE ITREVIEW the theme editor in Settings → Personalization cupboard:publish-theme listed immediately Templates — starting points for new apps Templates starting points for apps listed immediately ⊕ TEMPLATES listed immediately MAKE ITSHARE ITREVIEW build the app shape you want to reuse; people start from it: templates:new-app cupboard:publish-template listed immediately Recipes — multi-step tool runs, saved for reuse Recipes saved multi-step runs reviewed ⊕ RECIPES reviewed MAKE ITSHARE ITREVIEW nothing to do: captured automatically when your agents run multi-step tool sequences (code:run) cupboard:publish-recipe reviewed before it is listed Rubrics — grading criteria for work Rubrics criteria for judging work reviewed ⊕ RUBRICS reviewed MAKE ITSHARE ITREVIEW ask your agent to propose one: rubrics:propose cupboard:publish-rubric reviewed before it is listed Plans and goals — plans and the goals they serve Plans & goals plans and their goals reviewed ⊕ PLANS & GOALS reviewed MAKE ITSHARE ITREVIEW ask your agent to write a plan (plans:new) or set a goal cupboard:publish-plan cupboard:publish-goal reviewed before it is listed Datatypes — new kinds of structured data Datatypes new kinds of data reviewed ⊕ DATATYPES reviewed MAKE ITSHARE ITREVIEW ask your agent to define one: meta:define-datatype cupboard:publish-datatype reviewed before it is listed Plugins — code packages that extend PaperCusp Plugins code that extends it listed immediately ⊕ PLUGINS listed immediately MAKE ITSHARE ITREVIEW write it in its own public GitHub repo cupboard:publish-plugin listed immediately, pinned to a commit Apps — whole apps built on PaperCusp Apps whole apps on PaperCusp reviewed ⊕ APPS reviewed MAKE ITSHARE ITREVIEW start one from a template: templates:new-app cupboard:publish-app reviewed before it is listed 03 · Publish — a public GitHub repo, pinned to a commit ⊕ more inside Publish a public GitHub repo pinned to one commit signed in with GitHub cupboard:publish-<kind> PUBLISH — the same for every kind one verb per kindpinned to a commit a real authora new version cupboard:publish-rule, -theme, -app … identities use blueprint:publish the listing points at your public repo at one commit — exactly what installs publishing signs you in with your GitHub identity push a new commit and publish again: that is a new version 03 03 · Walkthrough — publish a rule ⊕ more inside Publish a rule a walkthrough my-rules/ no-force-push/ rule.json listing.json ↓ push it, public cupboard:publish-rule ↓ reviewed, then listed cupboard:install-rule anyone can add it PUBLISH A RULE 1 · lay it out2 · push it, public 3 · publish4 · install each rule in its own folder, named after its ref, in a GitHub repo: my-rules/ no-force-push/rule.json + listing.json (kind: rule) push the repo to GitHub and make it public, so the Cupboard can read the folder at the commit you publish cupboard:publish-rule { ref: no-force-push, githubUrl: …/you/my-rules } listed once an operator approves it anyone adds it with cupboard:install-rule — every other kind follows the same steps with its own publish verb 03 05 · Review — checked before it is listed ⊕ more inside Review reviewed before listing identities · rules · events · recipes rubrics · plans · goals · datatypes · apps listed immediately tools · plugins · themes · templates REVIEW — checked before anyone can install reviewed kinds waitupdates wait toosome list right away a version is listed only after an operator approves it while a new version waits, the previously approved version keeps serving tools, plugins, themes and templates list at once — still pinned to a commit 05 03 · Others install — exactly what was listed ⊕ more inside Others install anyone adds it to their own workspace cupboard:install-rule · install-event · … exactly the commit that was listed INSTALL — from the Cupboard into a workspace pinned = exactrules need a pinnew event types you install exactly the code that was listed — read it first in its public repo an installed rule does nothing until an identity pins it — then it guards each matching tool call come from installing an event package, or with an identity that bundles its own events 03 03 · Update or delist ⊕ more inside Update or delist push a new commit → a new version cupboard:unpublish takes it down publisher or verified claimant only UPDATE OR DELIST updatedelist push a new commit and publish again — that is a new version. reviewed kinds go back through review; the approved version keeps serving meanwhile cupboard:unpublish takes a listing down. Only the publisher, or a verified claimant of the repo, can do it 03 04 · Your submissions — coming soon Your submissions coming soon one view of every listing you published and its review state 04 05 · Trust — three guarantees ⊕ more inside Trust review before listing · nothing changes under you · only the owner takes it down TRUST — three guarantees review before listingnothing changes under youonly the owner takes it down identities, rules, events, recipes, rubrics, plans, goals, datatypes and apps are checked before anyone can install them every listing is pinned to a commit in a public repo — you install exactly the code that was listed, and you can read it first delisting is limited to the publisher or a verified claimant, and every publisher signs in with GitHub 05 06 · What's next — coming soon What's next coming soon paid identities · rules and events your agent writes · your submissions view 06 reviewed listed immediately coming soon ⊕ zoom in for more
The Cupboard

Make PaperCusp yours

Everything your agents work with — tools, identities, rules, events and more — is something you can make yourself. Keep it private in your own workspace, or share it with everyone through the Cupboard, PaperCusp's shared shelf of things people have made.

  1. Make it locallyAsk your agent, or write it yourself.
  2. Use itIt lives in your workspace. Nobody else sees it until you publish.
  3. PublishPoint the Cupboard at a public GitHub repo, pinned to a commit.
  4. ReviewReviewed kinds are checked before they are listed. The rest list right away.
  5. Others installAnyone can add it to their own workspace from the Cupboard.
  6. Update or delistPush a new commit for a new version, or take it down.

↺ an update goes back through publish and review — the approved version keeps serving while the new one waits.

01

Two ways to customize

The same things can live in two places. Start local; publish when it is worth sharing.

Local

private · instant

Made in your own workspace and used right away. It stays yours: nothing is listed anywhere until you decide to publish it.

The Cupboard

shared · versioned · reviewed

Published from a public GitHub repo and pinned to a commit, so everyone installs exactly the version that was listed. Most kinds are reviewed before they appear.

02

What you can make

One card per kind: what it is, how to make it on your machine, and how to share it. The verbs in code are the tools your agent calls — you can just ask in plain words.

Tools

New actions your agents can take.

Make it
Ask your agent for the tool you need. It defines one with meta:define-tool. “Make me a tool that pulls this week's invoices.”
Share it
Package it as a code-tool pack and publish it with cupboard:publish-plugin.
Review
listed immediately pinned to a commit

Identities

A named agent persona your agents can run as.

Make it
Ask your agent to create one with identities:create, or start from an existing identity and change it with blueprint:extend.
Share it
Publish it with blueprint:publish.
Review
reviewed

Selling an identity so others pay per use coming soon

Rules

Automatic reactions and guards: run an action when an event happens, or refuse a tool call before it runs.

Make it
Give each rule its own folder, ~/.papercusp/rules/installed/<name>/, holding a rule.json and a listing.json that says "kind": "rule". A guard rule needs schemaVersion, id, title, description, version, "delivery": "sync", "sink": "pre-tool" and a guard with deny or allowOnly. Add tools to limit which tools it watches.
Check it
The file is read against a strict schema. A missing or unknown field makes the rule invalid, and an invalid rule is skipped, never half-applied. cupboard:publish-rule and cupboard:install-rule refuse a rule.json that does not parse.
Turn it on
An installed rule does nothing until an identity pins it. Every session wearing that identity then has the guard checked before each matching tool call.
Share it
Publish it with cupboard:publish-rule.
Review
reviewed
Example: block force-pushes
{
  "schemaVersion": 1,
  "id": "no-force-push",
  "title": "No force-push",
  "description": "Refuses a shell command that force-pushes a git branch.",
  "version": "1.0.0",
  "delivery": "sync",
  "sink": "pre-tool",
  "tools": ["Bash"],
  "guard": {
    "deny": { "input.command": { "matches": "git\\s+push\\s+.*(--force|-f\\b)" } },
    "reason": "Force-pushing is not allowed here."
  }
}

Asking your agent to write a rule for you coming soon

Events

Named things that happen, which rules and agents react to.

Make it
Defining your own event type is not available yet. Today you get new event types by installing an event package from the Cupboard with cupboard:install-event, or with an identity that bundles its own events.
Share it
Publish an event package with cupboard:publish-event.
Review
reviewed

Asking your agent to define a new event for you coming soon

Themes

How your workspace looks.

Make it
Use the theme editor in Settings → Personalization.
Share it
Publish it with cupboard:publish-theme.
Review
listed immediately

Templates

Starting points for new apps.

Make it
Build the app shape you want to reuse. People start a new app from a template with templates:new-app.
Share it
Publish it with cupboard:publish-template.
Review
listed immediately

Recipes

Multi-step tool runs, saved for reuse.

Make it
Nothing to do: recipes are captured automatically when your agents run multi-step tool sequences (code:run).
Share it
Publish one with cupboard:publish-recipe.
Review
reviewed

Rubrics

Grading criteria agents use to judge work.

Make it
Ask your agent to propose one with rubrics:propose.
Share it
Publish it with cupboard:publish-rubric.
Review
reviewed

Plans & goals

Multi-step plans and the goals they serve.

Make it
Ask your agent to write a plan (plans:new) or set a goal.
Share it
Publish with cupboard:publish-plan or cupboard:publish-goal.
Review
reviewed

Datatypes

New kinds of structured data your agents can store and use.

Make it
Ask your agent to define one with meta:define-datatype.
Share it
Publish it with cupboard:publish-datatype.
Review
reviewed

Plugins

Code packages that extend PaperCusp.

Make it
Write the plugin in its own public GitHub repo.
Share it
Publish it with cupboard:publish-plugin.
Review
listed immediately pinned to a commit

Apps

Whole apps built on PaperCusp.

Make it
Ask your agent to start one from a template with templates:new-app.
Share it
Publish it with cupboard:publish-app.
Review
reviewed
03

Sharing on the Cupboard

Every kind shares the same way: a listing points at your public GitHub repo, pinned to a commit.

  • PublishRun the kind's publish verb (or ask your agent to). Publishing signs you in with your GitHub identity, so every listing has a real author.
  • VersionsA listing is pinned to one commit. Push a new commit and publish again: that is a new version.
  • ReviewReviewed kinds wait for approval before a version is listed. While a new version waits, the previously approved version keeps serving.
  • DelistTake a listing down with cupboard:unpublish. Only the publisher, or a verified claimant of the repo, can do it.

Walkthrough: publish a rule

  1. Keep each rule in its own folder, named after its ref, inside a GitHub repo: 
    my-rules/
  no-force-push/
    rule.json
    listing.json
  2. Push the repo to GitHub and make it public, so the Cupboard can read the folder at the commit you publish.
  3. Publish it, naming the rule and the repo: 
    cupboard:publish-rule {
  "ref": "no-force-push",
  "githubUrl": "https://github.com/you/my-rules"
}
    Rules are a reviewed kind, so the listing appears once an operator approves it.
  4. Anyone can then add it to their workspace with cupboard:install-rule. The other kinds follow the same steps with their own publish verb.

reviewed before listing

Identities, rules, events, recipes, rubrics, plans and goals, datatypes and apps.

listed immediately

Tools (as code-tool packs), plugins, themes and templates. Each is still pinned to a commit.

04

Your submissions

coming soon

One place to watch everything you've published coming soon

A view of your own listings and where each one stands in review. These are the states it will show:

  • Pending review — waiting for a reviewer
  • Approved — listed and installable
  • Rejected — with the reviewer's reason
  • Delisted — taken down
05

Trust

Review before listing. Identities, rules, events, recipes, rubrics, plans, goals, datatypes and apps are checked before anyone can install them. Tools, plugins, themes and templates list immediately.

Nothing changes under you. Every listing is pinned to a commit in a public repo, so what you install is exactly the code that was listed, and you can read it first.

Only the owner can take it down. Delisting is limited to the publisher or a verified claimant, and every publisher signs in with GitHub.

06

What's next

These are being built. Each one is labelled until it ships.

  • Paid identities. Sell an identity you made, so others pay per use. coming soon
  • Rules and events, written by your agent. Describe the reaction you want in plain words and get the rule and event made for you. coming soon
  • Your submissions view. Every listing you published and its review state in one place. coming soon

See how the rest of PaperCusp fits together on the architecture page.