xarmian
57820422a2
* feat(web): an ORDERED identity epoch, so a store can tell "still me" from "me again" (BUG-3005, unit 1)
Four singleton stores hold per-user state and none of them can currently ask
the question they need to ask when a response comes back: was this issued
under the identity that is signed in now.
The tree's existing answer is a captured user id compared at settle
(`workspace.svelte.ts`). That answers "is this a DIFFERENT user", which is a
weaker question and comes apart on sign out of A, in as B, back in as A: a
request issued during the first A session settles, compares equal, and commits
data from a session that has ended. An ordinal cannot be confused that way —
the epoch it captured is strictly lower than the one it settles into.
`authStore.identityEpoch` bumps on exactly the transitions `onIdentityChange`
already fires on, and `identityFence()` is the capture-and-compare helper, so
four stores do not hand-roll it four ways. That is not a hypothetical: this
store and `workspace.svelte.ts` hand-rolled the same three parts of a
single-flight loader and drifted three times in one afternoon, which is why
`singleFlight.ts` exists.
Two orderings are load-bearing and each has a test:
- NOT bumped on the baseline, matching `notifyIdentityChange`'s own early
return. The first resolution of the session is not a change from anything,
and a fence captured before an identity existed has nothing stale to refuse.
- Bumped BEFORE the listeners, not after. A listener's expected shape is "drop
state, reload it", and that reload captures a fence while the listener is
still running — under the old epoch it would refuse its own response.
Distinct from `generation`, which bumps only on `clear()` and fences this
module's own /auth/session fetches; a sign-in as a different user through
`load()` moves the identity without touching it, so it cannot serve as the
epoch.
Five tests. Mutants: fence on the user id instead of the epoch (2 fail,
including the A->B->A straggler this exists for), bump after the listeners
(1 fail, alone), bump on the baseline too (3 fail). Full web suite 2416 passed.
No consumer yet — the stores are unit 2. Nothing changes behaviour on its own.
* fix(web): starredStore drops the previous user's stars, and refuses a settle from a session that has ended (BUG-3005, unit 2a)
`starredStore` holds a PER-USER set and was only ever cleared inside `load()`,
which is keyed by workspace slug. A same-route account swap starts no new load,
so A's starred ids stayed rendered inside B's session with no request having
been made for them.
Two halves, because they fail independently:
- an `authStore.onIdentityChange` subscription clears the store when nothing is
racing at all, which is the common case;
- an identity fence on every settle, for the case where something is. Both
arms of `load` commit — the catch arm publishes an empty set and flips
`loaded` — so fencing only the success path would leave the store telling B
that B's stars are loaded.
The navigation fence stays and is not subsumed: a workspace switch under one
identity moves no epoch, and an account swap moves no workspace.
FIVE TESTS, AND ONE OF THEM TOOK THREE TRIES TO BE WORTH ANYTHING. The
toggle-revert mutant SURVIVED twice:
- first because the identity-change reset blanks `currentWs`, so the workspace
fence was doing the work — fixed by having B sign back into the SAME
workspace before the revert fires;
- then because the test reverted a failed STAR, which is a delete, and a
delete is invisible in an empty set. The write that actually leaks is the
revert of a failed UNSTAR, which is an ADD into the next user's set.
Both are recorded in the test's own comment, because "this assertion is
pointed the wrong way" is not visible from a green run. Mutants now: drop the
subscription (2 fail), drop the fence on load's success arm (1), on its catch
arm (1), on the toggle revert (1, and only against the corrected test).
All 291 store tests pass.
* fix(web): collectionStore drops the previous user's collections and items, and fences every settle (BUG-3005, unit 2b)
`collections`, `items`, `itemsWorkspace`, `collectionsWorkspace` and
`activeItem` all belong to a user and none of them is keyed by one. The loader
is keyed by workspace SLUG and the workspace layout drives it from a slug-keyed
effect, so a same-route sign-in as a different user starts no new load at all —
Roles, the item picker and the editor's link gate then render A's collection
names and item titles inside B's session.
The store's only fence was `isLatest`, which is a NAVIGATION fence and cannot
see this: a same-route account swap supersedes nothing, so A's load is still
the latest one for that workspace and commits.
Both halves, as with starredStore:
- an `onIdentityChange` subscription clearing the store, for the ordinary case
where nothing is racing;
- an identity fence captured before the first await on `loadCollections`,
`loadItems` (both arms — they assign through different branches and stamp
`itemsWorkspace` differently) and `loadItem`.
`loadItem` returns NULL rather than the fetched item when the identity moved.
The return value matters as much as the store write: the caller renders what it
is handed, so handing back A's item puts it on B's screen with `activeItem`
untouched.
The FRESHNESS STAMPS clear with the arrays, and that is load-bearing rather
than tidiness. Emptying `collections` while leaving `collectionsWorkspace` set
makes `collectionsAreFreshFor(ws)` answer true for an empty list — the one
answer that stops TASK-2200's recovery from re-fetching, so the new user's
sidebar would stay permanently empty. It has its own test and its own mutant.
`loadItems` and `loadItem` have no production callers today (the item list is
maintained through addItem/updateItemInList/removeItem from SSE, and
`activeItem` through setActiveItem). They are fenced anyway: they are public
API and this item names exactly that state as retained.
Seven tests, six mutants, five of them dying to exactly one test: drop the
subscription (2 fail), drop the fence on loadCollections (1), on each items arm
(1 each), make loadItem return the item anyway (1), leave the stamps set in
clear() (1). Full web suite 2428 passed.
Claude-Session: https://claude.ai/code/session_0115vpkjH5mmFdjRdRmZRuZt
* fix(web): localIndex and localSearch drop every workspace when the signed-in user changes (BUG-3005, unit 2c)
`localIndex` reset only when `bootstrap()` noticed a userId mismatch, which
makes the invalidation depend on somebody calling bootstrap. A route that does
not bootstrap the index on an identity change kept the previous user's rows in
RAM — and `localSearch`, whose only reset callers live inside `localIndex`,
kept a full-text index built from their item titles and bodies. That fourth
store is not named on the item; the enumeration this unit re-ran found it,
which is what CONVE-18 asks for.
The per-workspace shape is the other half. `reset(ws)` names one slug, so the
sign-out path dropped the workspace the layout happened to be looking at and a
tab that had visited two kept the other.
`localIndex.resetAll()` sweeps every workspace it holds and then calls
`localSearch.resetAll()`. The second call is not redundant with the per-
workspace resets it just performed: the two maps are keyed independently and
nothing keeps them in step, so an index whose workspace state is already gone
survives a sweep driven from localIndex's keys alone. It has its own test and
its own mutant.
The bootstrap mismatch check STAYS. It covers a different case — a first
bootstrap for a workspace whose cached state predates this tab's identity
signal, where nothing changed within this tab so nothing fired.
Four tests, three mutants: drop the subscription (3 fail), sweep only the first
workspace (1, alone), drop the localSearch.resetAll belt (1, alone). Full web
suite 2432 passed; svelte-check 0 errors.
Claude-Session: https://claude.ai/code/session_0115vpkjH5mmFdjRdRmZRuZt
* fix(web): the store fix routed the starred PAGE around its own filter, and three more singletons held user state (BUG-3005, codex round 1)
Round 1's largest finding is that the four stores were not the population, and
the sharpest instance is one my own fix made worse.
THE STARRED PAGE. `items` is `starredStore.loaded ? filter(fetchedItems) :
fetchedItems` — an unfiltered fallback for the pre-load window. The store's
identity reset sets `loaded = false`, so the fix routed the page around its
only filter and handed B the full `fetchedItems` array it had fetched as A. Its
load effect is keyed on the workspace slug, so a same-route swap started no
reload to correct it. The page now drops its own copy on the identity signal,
invalidates any load in flight, and reloads; its settle carries an identity
fence beside the `seq` one, which is a navigation fence and does not move on an
account swap.
THREE MORE STORES, none of which looks like per-user state to a sweep for
per-user FIELDS:
- `adminStore.stats` — instance-wide DATA, but authorization-scoped: only an
admin can read it, and it must not outlive the admin who did.
- `titleStore` — its parts are retired by a PATH stamp, and an account swap
moves no path, so A's workspace name and item ref stayed in the browser tab.
Cosmetic, and cheap enough that leaving one member of a class unfixed costs
more than fixing it.
- `editorStore` — `dirty` and `saveStatus` are read by GUARDS, not displayed:
A's dirty editor makes B's unsaved-draft prompt and SSE archive suppression
act on a document B never opened. Needs a WIDER clear than `resetForDoc`,
which keeps `saveStatus` on purpose because it handles a document change
within one session; an identity change ends the session. Its own test.
AND ONE FALSE CLAIM OF MINE. Unit 2b's message said every post-await write in
collectionStore was fenced. `finally { loading = false }` was not, so A's load
settling under B's in-flight one cleared B's flag and could flash empty-state
mid-load. Fenced, with `clear()` now owning the flag so nothing is stuck true.
THREE THINGS DOCUMENTED RATHER THAN CHANGED, each with the reasoning in the
code:
- The baseline exemption's residual. A request issued before `/auth/session`
resolves settles under a fence that still says current, so a cross-tab
identity change inside that window commits. It cannot be closed by refusing
pre-baseline settles: the root layout issues the workspace list CONCURRENTLY
with the session — that concurrency is why `identityEstablished` exists — so
refusing them empties the app on every cold start. Nothing inside the tab can
tell the two cases apart.
- The contract bumping-before-listeners places on listeners: a fence captured
inside a listener passes, so a listener must reload for the identity signed
in NOW. Every listener here clears and either stops or reloads from the
current route.
- The durable wipe `resetAll` inherits from `reset`. Not needed for isolation
(the cache is namespaced per user+workspace) and it costs a returning user
their warm cache, but it is what sign-out has done since TASK-1360 and
leaving a signed-out user's item titles on a shared browser's disk is the
wrong default to adopt silently. What this widens is the pre-existing race
between a fast re-login's hydrate and a wipe still in flight; that is a
persistence-layer fix, not a change to this sweep.
Six new tests. Five mutants, each dying to exactly one: unfence `loading`,
drop the admin subscription, drop the title subscription, use `resetForDoc`
instead of `clear` for the editor, drop the starred page's subscription.
The admin test loads REAL stats through a stubbed fetch first — asserting null
before and after would have passed against a store with no clear at all, which
is the failure this branch has already produced once.
Full web suite 2438 passed; svelte-check 0 errors.
Claude-Session: https://claude.ai/code/session_0115vpkjH5mmFdjRdRmZRuZt
* fix(web): a reset that dropped the data but not the in-flight slot, plus the layout that outlived the identity (BUG-3005, codex round 2)
Round 2 found four defects, one of which my round-1 reset CREATED, and the
lead's three folded rows land with them.
THE SINGLE-FLIGHT SLOT — the reset was actively harmful. `clear()` dropped the
collections but left the previous identity's promise published, so B's
`ensureCollections` JOINED A's request, A's identity fence then refused to
commit, and B was answered with no data and no request of its own. A
permanently empty sidebar, which is the exact failure the cleared freshness
stamp was there to prevent. `invalidate()` on the keyed single-flight abandons
the slot AND bumps the sequence; `workspaceStore` gets the same line, because
it is the same defect one file away and BUG-2991 did not have to be filed for
it to be true there too.
THE WORKSPACE LAYOUT outlived the identity. Its per-workspace effect is keyed
on the slug, so a same-route swap re-ran nothing and the layout kept every
connection it made for the previous user. Two halves:
- the SSE stream is a leak rather than staleness. `sseService.connect` is
idempotent per workspace, so B's tab kept the EventSource A opened — still
authorized, because signing in as B replaces the cookie without destroying
A's session row, which is precisely the case BUG-3007's server-side close
cannot see. Explicit `disconnect()` first. BUG-3011 tracks the server half.
- fourteen leaf route components own user-scoped state and key their reloads on
the slug. `{#key authStore.identityEpoch}` remounts them structurally rather
than fixing fourteen pages and leaving the fifteenth to be remembered.
AND THE REMOUNT SHIPPED BROKEN FIRST. `identityEpoch` was a plain `let`, so the
template never saw it change and the block never re-ran. Nothing about the code
looked wrong; a test that counted mounts is what found it. It is `$state` now,
with the reason in the comment, because it is the only value in that file read
from a template.
Also from round 2: `adminStore.loadStats` had no fence, so A's statistics landed
after the clear; `clear()` set `loading = true` and the admin layout loads only
on mount, which pinned the console on "Loading admin data…" forever; and the
starred page reloaded its private copy but not the shared store, so every OTHER
view showed all items unstarred.
MY BASELINE COMMENT WAS FACTUALLY WRONG and codex was right to call it. I wrote
that the root layout issues the workspace list concurrently with
/auth/session — taken from the neighbouring comment rather than read from the
layout. `loadAll()` is gated on `authReady`, and no children render until then,
so nothing can issue a fenced request before the baseline. The residual is
therefore currently UNREACHABLE rather than narrow, and the exemption stays for
a different reason: the bump and the listener notification are one event, and
firing listeners on the baseline is a live hazard. Corrected in place, with what
is actually true.
The lead's three folded rows: SSE (above), `toastStore` (the tray is a readable
log of A's actions — toast text names items), and the editor's
attachment-metadata memo, cleared from the ROOT layout rather than by
self-subscribing, because that module is deliberately rune-free and importing
the auth store breaks every `node`-project test with "$state is not defined"
before an assertion runs.
Eight new tests. Mutants, each dying to exactly one test: no flight
invalidation, invalidate without the sequence bump (pinned by an A->B->A leg in
`workspaceStore`, where the captured user id AGREES and the bump is the only
guard left), unfenced `loadStats`, toast history kept, the starred page not
reloading the store, no SSE disconnect, no remount.
Full web suite 2446 passed; svelte-check 0 errors.
Claude-Session: https://claude.ai/code/session_0115vpkjH5mmFdjRdRmZRuZt
* fix(web): stop enumerating surfaces — an identity change clears what a reload cannot drop, then reloads (BUG-3005, codex round 3 + lead ruling)
Three review rounds each found another layer of surfaces holding the previous
user's data: three stores, then fourteen route pages plus a connection and two
caches, then the console subtree, share pages, the command palette and an open
dialog. The population is "everything in the tab that ever held a fetch", and a
per-surface fix cannot terminate — it is a list somebody has to keep complete
forever. The lead's ruling, and it is the right one: reload.
`reloadForIdentityChange` clears the state a reload does NOT drop — the
palette's recent searches in localStorage, collab cursors in sessionStorage,
the attachment-metadata memo — and then reloads. What remains an enumeration is
bounded by STORAGE KEYS rather than by every module in the app, and a grep for
the storage APIs can check it. The clears run FIRST and that ordering has its
own test: reloading first tears the page down before they execute.
REMOVED, because one mechanism is the point: the `{#key}` remount added in
round 2, and the starred page's own listener. The starred page had three reload
paths on a single identity change. The remount's absence is pinned by a test
rather than left implicit, so re-adding it has to be deliberate.
KEPT, because none of it is redundant with the reload: the epoch, the four
store fences, and the SSE disconnect. They cover the window between the identity
changing and the page actually going away, during which in-flight responses are
still settling into live stores. The SSE close bounds that window to zero for a
stream that would otherwise stay authorized — signing in as B replaces the
cookie without destroying A's session row, which is the case BUG-3007's
server-side close cannot see (BUG-3011).
THE TWO WRITES NEED THEIR OWN RULE, AND THE RELOAD MAKES THEM WORSE rather than
better. A teardown that PERSISTS must discard when the identity moved, because
the reload's unload fires those handlers under the NEW cookie:
- `ItemDetail`'s raw-markdown saver flushes pending edits with `keepalive: true`
from three sites, a request deliberately built to outlive the page. It now
refuses when the epoch differs from the one captured when the item was
LOADED — the identity whose typing the editor contains.
- `openChildrenDialog` holds the fetched 409 child list AND continuations that
perform the mutation on confirm. It is mounted in the root layout, outside
everything the workspace layout controls. All pending requests now resolve
FALSE, so the producer takes its cancel path; rejecting would surface
unhandled rejections at call sites that only ever expected a boolean.
Grepped the class (`keepalive: true`): three sites, all funnelling through the
one saver callback that now carries the guard.
MY BASELINE COMMENT WAS WRONG A SECOND TIME. Round 2 corrected it to "no child
renders before authReady"; round 3 found the share-page branch sets `authReady`
WITHOUT calling `authStore.load()`, and the auth-failure path proceeds
deliberately. So the residual is narrow, not unreachable. Corrected again, and
this time the exceptions are named rather than the rule restated.
Nine tests across the new mechanism; every mutant dies to exactly one: reload
before clear, no palette clear, a collab clear that takes the whole of
sessionStorage, the dialog abandoning only its active entry, no SSE disconnect,
a reinstated remount.
Full web suite 2450 passed; svelte-check 0 errors.
Claude-Session: https://claude.ai/code/session_0115vpkjH5mmFdjRdRmZRuZt
* fix(web): the identity reload was firing the teardown writes it was meant to outrun (BUG-3005, codex round 4)
Round 4 found two P1s, and both are defects the RELOAD created — which is the
shape of this whole unit by now: each fix's own mechanism becomes the next
round's hazard.
THE UNLOAD HANDLER WAS PERSISTING UNDER THE NEW COOKIE. A reload fires
`beforeunload`, and both persistence paths there use `keepalive` — a request
deliberately built to outlive the page. Round 3's guard covered the raw saver
only. The collab flush was unguarded, and MY GREP FOR THE CLASS MISSED IT: I
grepped `keepalive: true`, and that call passes the flag positionally as
`flushNow(ctx, true)`. An enumeration by literal, in the unit whose entire
lesson is that enumerations by shape are wrong.
THE UNLOAD HANDLER COULD ALSO CANCEL THE RELOAD. `preventDefault()` on a dirty
editor raises the native "unsaved changes" prompt, and "Stay" cancels the
navigation. The identity has already changed and the stores are already
cleared, so the answer would be the new user sitting in the previous user's
page shell — with the `{#key}` remount removed in round 3, nothing left to
rebuild it. The prompt protects the author's unsaved work, and after an
identity change the author is not the one sitting there.
Both close the same way: when the epoch differs from the one captured at LOAD,
the handler returns before it flushes or prompts. The $effect cleanup is a third
door into the same write and is gated too.
Also from round 4: `pad-last-route-<ws>` and `pad-last-scroll-<ws>-<pathname>`
are keyed by WORKSPACE with no user in them. The scroll key embeds the pathname
in the KEY, so a private item slug is legible from a key listing without
reading a single value. Both are cleared now, and the test asserts an ordinary
UI preference SURVIVES, because a clear that took all of localStorage would be
a different and undocumented change.
ACCEPTED, NOT FIXED, with the reasoning: `persistWipe` is fire-and-forget, so
an IndexedDB database can outlive the reload if its delete has not landed. It
is residual data on disk rather than a cross-user read — the databases are
named `pad-local-index-{userId}-{workspace}`, so the next user cannot open the
previous one's — and making the reload await an unbounded IDB delete trades a
privacy-hygiene residual for a tab that may not reload at all.
Six tests. The ItemDetail ones are SOURCE guards, the pattern this directory
already uses for that file (~7,900 lines of collab, SSE and pane wiring), and
the header says what a source guard cannot do rather than leaving it implied.
Mutants: remove the beforeunload guard, remove the collab cleanup gate, remove
the route/scroll clear — each dies to exactly one test.
Full web suite 2456 passed; svelte-check 0 errors.
Claude-Session: https://claude.ai/code/session_0115vpkjH5mmFdjRdRmZRuZt
* fix(web): the reload now happens even if a clear throws, and a test that passed for the wrong reason (BUG-3005, codex round 5)
No P1s. Two P2s and a P3, all addressed.
THE RELOAD IS EXCEPTION-SAFE NOW. `clearPersistentIdentityState()` ran outside
any try/finally, so a throw on the way through would have skipped
`location.reload()` entirely — leaving the tab mounted with the previous user's
page under the new identity, which is the state this whole fix exists to
prevent, reached by the fix itself failing quietly. Latent today (the only
uncaught call is a `Map.clear()`), and the ordering is now structural rather
than incidental.
A TEST THAT REPORTED PASSED WHILE THE PAGE CRASHED. The starred-page leg used
`mockReturnValueOnce` with no default, so a later call resolved `undefined`,
`items.map` threw, and vitest showed a green test with an unhandled error beside
it — the assertion was reading a page that had crashed rather than a fence that
had refused. Every mock carries a default now, `vi.resetModules()` is gone (it
handed the test a different authStore instance than the component closed over),
and there is a counterfactual leg where the identity holds still and the data
DOES render.
AND THE SAME LEG'S MUTANT SURVIVES, which is in the file rather than left for
the next reader to discover. Removing the page's identity fence leaves it green:
the page's own `$effect` re-runs during the transition and advances `loadSeq`,
so the NAVIGATION fence refuses A's settle first and the identity fence never
decides anything there. The leg stands as an end-state regression fence — A's
items must not appear — and the identity fence's coverage of the pre-reload
window is an argument, not a measurement. Recorded because a surviving mutant
filed as a passing test is exactly how this file already shipped one assertion
pointed the wrong way.
P3: a trailing blank line `git diff --check` flagged.
Full web suite 2457 passed, no unhandled errors; svelte-check 0 errors;
`git diff --check` clean.
Claude-Session: https://claude.ai/code/session_0115vpkjH5mmFdjRdRmZRuZt
* fix(web): a sign-in from an unauthenticated tab must not reload (BUG-3005, E2E failure + lead ruling)
E2E failed on 3aebbb58 and the suite was right. `web/e2e/lib/collab-helpers.ts`
signs in by fetching `/api/v1/auth/login` FROM INSIDE a mounted page, which is
an identity change from `''` to a real user — and the reload took the page out
from under Playwright.
The narrowing is correct on its own terms, which is why it lands whatever the
log finally says. The reload exists so one user's data cannot be visible to the
next, so which transitions need it is a question about WHOSE data is being
dropped: an anonymous baseline holds nobody's private data. `user -> user` and
`user -> ''` reload; `'' -> user` does not.
It also takes a full page load out of the primary login path, where it was
racing the login flow's own navigation. That cost was never intended and would
have shipped unnoticed if the E2E suite had not been driving a real login.
`onIdentityChange` listeners now receive the PREVIOUS established user id.
Every other listener ignores it and drops state as before; only the root layout
needs to tell a sign-in from a sign-out or a swap, and reading it from the
signal is better than the alternative of a second store field that can disagree
with the one the notification was computed from.
Three legs, and the mutant that removes the guard kills all three — the swap and
sign-out ones on the exact CALL COUNT rather than on an absence, because
`afterEach` clears the store so every test starts from an established empty
identity and its own setup performs a sign-in. That is written into the test
file, since a leg failing for a reason other than its name is how a suite stops
meaning what it says.
Full web suite 2460 passed; svelte-check 0 errors.
Claude-Session: https://claude.ai/code/session_0115vpkjH5mmFdjRdRmZRuZt
* fix(web): sign-out clears and lets its own navigation leave; only a swap reloads (BUG-3005, E2E account-delete failure)
The E2E failure was `account-delete.spec.ts:147` with
`net::ERR_ABORTED; maybe frame was detached?` and
`Navigation to /console/settings is interrupted by another navigation to
/login`. A NAVIGATION RACE, not a rule about identity transitions — and not the
sign-in I had guessed at before the log was readable. Recording that because
the previous commit's narrowing was proposed on a wrong diagnosis; it is right
on its own terms, and it was not this.
Both sign-out sites already navigate away by themselves. Account deletion does
`authStore.clear()` then `window.location.href = '/login'`, deliberately and
with a comment saying so. My listener fires inside `clear()` and started a
reload of the current URL; the delete flow then set `location.href`. Two
navigations, one aborts.
So the split, per the lead's ruling:
- SWAP (user -> user): reload. Nothing else navigates, so the reload is the
whole mechanism.
- SIGN-OUT (user -> ''): run the persistent clears and return. The clears still
have to happen — a hard navigation drops the tab's memory, not localStorage,
sessionStorage or IndexedDB — but the reload is redundant with a navigation
that is already underway, and racing it is what broke the flow.
- and the console logout now navigates HARD. `goto('/login')` is an SPA
navigation that leaves every singleton, component and cache where it was,
which is this bug's original defect arriving through the sign-out path
itself. Account deletion has always done this; the two sites agree now.
The property is unchanged: every transition away from a real user drops that
user's in-tab state, by reload on a swap and by hard navigation on a sign-out.
Four legs in the root-layout test (swap reloads and does NOT take the clear-only
branch; sign-out clears and does NOT reload; sign-in does neither) and a source
guard on the console logout, since jsdom does not perform an assignment to
`window.location`. Mutants: sign-out reloading again, sign-out doing neither,
and the logout reverting to `goto` — each dies.
Full web suite 2464 passed; svelte-check 0 errors; `git diff --check` clean.
Claude-Session: https://claude.ai/code/session_0115vpkjH5mmFdjRdRmZRuZt
Pad
Project Management for the agent era.
Website · Docs · Blog · Changelog · Reddit · X · Bluesky
One binary. Local-first. No accounts required. Pad gives you a CLI, a web UI, and an AI agent skill — all backed by SQLite, all running on your machine. Your project data stays on your laptop — unless you take it to Pad Cloud.
Quick Start
brew install PerpetualSoftware/tap/pad
cd your-project
pad init # configure, auth, workspace, AI skill — all in one
pad server open # opens the web UI at localhost:7777
pad init is the smart entry point — it auto-detects what's needed, walks you through each step, and is safe to re-run anytime (it skips finished steps and prints a status summary).
Then, in a fresh agent session in your project, say:
/pad onboard
Your new workspace ships with the canonical onboard playbook auto-activated. The agent walks an interview, inspects your codebase if it has shell access, and adapts your workspace's collections, conventions, roles, and playbooks to match the project. It's the fastest way to go from empty workspace to "okay, this is mine."
Why Pad?
Tools like Linear, Jira, and Notion are built for teams on the cloud. Pad is built for developers on their machine — and for the AI agents working alongside them. When you do want your projects on every device or a teammate on the board, Pad Cloud hosts the same product with sync, workspace invites, and role-based access.
| Pad | Linear / Jira | Notion | |
|---|---|---|---|
| Setup | pad init |
Create account, invite team, configure | Create account, pick template |
| AI agents | Native /pad skill for 7+ tools |
Third-party integrations | Third-party integrations |
| Data | Local SQLite you own — or opt-in Pad Cloud | Their cloud | Their cloud |
| Offline | Full functionality | Read-only cache at best | Limited |
| CLI | First-class | Afterthought | None |
| Price | Free, open source | Per-seat pricing | Per-seat pricing |
Features
For Developers
CLI that doesn't get in your way. Create tasks, search items, check status — without leaving the terminal.
pad item create task "Fix OAuth redirect" --priority high
pad item create idea "Real-time collaboration" --category infrastructure
pad item list tasks --status in-progress
pad item search "authentication"
pad project dashboard # Project dashboard
pad project next # What should I work on?
pad server info # How this client is connected to Pad
Web UI that stays out of your way. A clean, dark-themed interface at localhost:7777 with:
- Board, list, and table views — drag-and-drop between status columns
- Keyboard navigation —
j/kto move,Enterto open,Escto go back,Cmd+Kto search - Rich text editor — Tiptap-based with markdown, formatting toolbar, and auto-save
- Wiki-links — type
[[Title]]to link between items - Real-time updates — agent creates a task in the terminal, it appears in the browser instantly (via SSE)
- Dashboard — collection overview, active work, plan tracking, activity feed
For AI Agents
Your agent becomes a project partner. Install the /pad skill once, and your AI coding tool can read, create, and update project items through natural language.
pad agent install # Auto-detects your tools and installs the skill
Works with Claude Code, Cursor, Windsurf, Codex, OpenCode, GitHub Copilot, Amazon Q, and JetBrains Junie.
Then just talk to your project:
> /pad what should I work on next?
> /pad I finished the OAuth fix
> /pad create a task to add rate limiting
> /pad let's brainstorm about the API redesign
Conventions and playbooks teach agents how your project works:
- Conventions — trigger-based rules like "run tests before marking a task done" or "use conventional commits"
- Playbooks — multi-step workflows like "when implementing a feature: read the spec, create a branch, write tests first, then implement". Playbooks can declare a kebab-case
invocation_slugso users can invoke them directly:/pad ship PLAN-42,/pad release 0.5.0. Freshstartupworkspaces ship a genericshipplaybook out of the box.
pad item create convention "Run tests before completing tasks" \
--field trigger=on-task-complete \
--field scope=all \
--field priority=must
Agents load relevant conventions automatically, and every agent action is attributed in the activity feed — so you can see what the AI changed rather than finding it later in a diff.
Name your agents:
An agent that identifies itself gets its name shown on its writes — in the activity feed's Live and Audit views, on the dashboard's recent activity, on item timeline activity entries, and in the admin console's audit log and per-user activity views. With more than one agent working a project, that is the difference between "something automated touched this" and knowing which one.
Pad takes the first of these it finds:
# 1. Per-workspace, committed with the project — the deliberate choice.
# In .pad.toml:
# agent_name = "reviewer"
# 2. Per-process, runtime-agnostic. Any harness can set it.
export PAD_AGENT=reviewer
# 3. Otherwise Pad detects the runtimes it knows — Claude Code reports
# "claude-code" — and that detected id is used as the name.
# 0. Per-session, and ahead of all three: the name this session REGISTERED
# as. `pad session register --agent rook` re-attributes every later write
# from that session to "rook", whatever .pad.toml or $PAD_AGENT say — the
# registry row and the write stamp are one value, not two.
pad session register --agent rook
If none of these produce a name, the write is not marked as an agent's at all — it is recorded as the person whose credentials it used, which is the case the caveat below is about. The generic agent label you may see on older entries is a write that identified itself before Pad stored names, or an event type that records the actor without the name (workspace membership changes, sign-ins).
The name is rendered exactly as sent — Pad keeps no list of approved names, and does not re-case or rewrite what you choose.
Sessions carry the name too, locally. A session with the Claude Code plugin records itself in ~/.pad/sessions on start (best effort — the plugin monitor is silent by contract, so a registration that fails, e.g. on a malformed pid variable, is only visible by running pad session register by hand) — the harness session's pid, the agent name above, and its working directory — and pad session list reads that back with a liveness verdict per row (alive, dead, or unknown where the platform cannot probe). It is a local, deterministic answer to "which of my sessions on this machine are running, and as which agent" — no server round-trip, no guessing from process names. What a row says about who is self-declared, like the name itself; on Linux the pid claim is additionally checked against the registering process's ancestry and reported as session_pid_verified. Any other harness gets the same by calling pad session register from its session-start hook with PAD_SESSION_PID (the session process) and PAD_AGENT exported. Records of sessions the register can see are dead are pruned on every register; pad session prune --older-than 72h also clears ones whose liveness cannot be determined. The record never leaves the machine.
Reading the output as a decision — "is this name in use here right now?" — takes a rule, and pad session list --help spells it out: count only rows that are alive, not legacy/malformed, and session_pid_verified; treat unknown, legacy, or malformed rows in the same directory as indeterminate rather than free (so list without --agent and filter yourself); read an empty result as "no registered row", not "nobody" — a harness that never registers is invisible; and never pick between two alive rows by registered_at, which is each session's own clock. The registry is per OS user.
Not every entry can show it. Activity entries store it, and comments (replies included) read it through the activity each one links to — so a comment written by an agent that sent a name shows that name in its chip, next to the person whose credentials it used. Version snapshots and implementation-note/decision entries record only that an agent acted, because nothing links them to a named row — they still read Agent.
What this does not claim. The name is supplied by the client and self-declared, so it records honesty, not identity. From ResolveAgentName's own contract in internal/cli/agent_identity.go:
- an agent that omits it is indistinguishable from the human whose credentials it is using;
- a human running
! pad ...inside an agent's terminal inherits that terminal's environment and will be attributed to the agent.
So it is not a basis for machine-verifiable provenance: treat it as a label an actor chose, useful for reading a trail, not as evidence about who acted. Because the credentials belong to a person either way, surfaces that exist for provenance show both — the admin audit log renders reviewer (via Dana) rather than picking one.
Since the name is chosen by whoever is writing, it is displayed as an isolated unit: it is shown as sent, but it cannot re-order or restyle the text around it, and the account half of name (via account) is rendered separately so a chosen name cannot forge it.
Onboard agents to a new codebase:
Open an agent session in the workspace directory and run /pad onboard. The agent walks an interview, detects your build/test/CI tooling, and adapts your workspace's collections, conventions, roles, and playbooks to match the project. Works for any agent that speaks Pad — Claude Code, MCP-only agents, etc.
Collections & Custom Fields
Pad organizes work into collections — typed containers with structured fields.
Built-in collections:
| Collection | Purpose |
|---|---|
| Tasks | Work items with status, priority, assignee, effort, due date |
| Ideas | Feature ideas with impact and category |
| Plans | Project milestones with progress tracking |
| Docs | Documentation, decisions, reference material |
| Conventions | Project rules that guide agent behavior |
| Playbooks | Multi-step workflows for agents to follow |
Create your own with typed fields — select, text, date, number, url, relation, checkbox:
pad collection create "Bug Reports" \
--fields "severity:select:low,medium,high,critical; browser:text; reproducible:checkbox"
Items get reference numbers automatically (TASK-5, BUG-12) and can be moved between collections with field migration.
Installation
Homebrew (macOS and Linux)
brew install PerpetualSoftware/tap/pad
Build from Source
git clone https://github.com/PerpetualSoftware/pad
cd pad
make build
cp pad ~/.local/bin/ # or /usr/local/bin/
Requires Go 1.26+ and Node.js 22+. Alternatively, nix develop provides a shell with the exact Go and Node versions pinned — see the Nix section below.
The go install github.com/PerpetualSoftware/pad/cmd/pad@latest path is not supported for the full Pad binary, because the web UI must be built and embedded during the source build.
Docker
docker run -p 127.0.0.1:7777:7777 -v pad-data:/data ghcr.io/perpetualsoftware/pad
This publishes Pad to localhost:7777 on the host machine, which is the recommended default for local use.
First run — create the first admin. Open http://localhost:7777 and you'll hit a setup page asking for a bootstrap token. On first start with no users, Pad logs a one-time setup URL to stderr (captured by docker logs) — grep it and open the printed link:
docker logs <container> 2>&1 | grep -A6 'Pad first-run setup'
# → http://<your-host>:7777/setup#token=<one-time-token>
Open that URL, create your admin account, and the token is consumed (the banner stops appearing). If you'd rather stay on the CLI, docker exec -it <container> pad auth setup works too — running inside the container counts as loopback, which the bootstrap gate allows. On a network you already trust, set PAD_BYPASS_SETUP_TOKEN=true to skip the token and create the admin straight from http://<your-host>:7777/setup (only safe when the port isn't reachable from the open internet).
Single user, more than one device? Publish to all interfaces so you can reach Pad from your phone, tablet, or another machine on the same LAN, Tailscale network, or home VPN:
docker run -p 7777:7777 -v pad-data:/data ghcr.io/perpetualsoftware/pad
For multi-instance deployments, Pad supports Postgres + Redis via docker-compose.yml — see docs/deployment.md for the full setup.
Nix
Run without installing:
nix run github:PerpetualSoftware/pad
Or install into your profile:
nix profile install github:PerpetualSoftware/pad
A flake devShell (Go, Node, and friends, pinned to the same versions CI uses) is also available for contributors:
nix develop
A
nixpkgspackage (nix-shell -p pad/environment.systemPackages) is planned but not yet merged upstream. Until then, use thegithub:PerpetualSoftware/padflake reference above.
Binary Download
Pre-built binaries for macOS, Linux, and Windows are available on the releases page.
Pad Cloud (hosted)
Don't want to run anything? Pad Cloud is the managed option — same product, same CLI, same /pad skill, free during beta. Sign up on the web, then connect a project directory:
pad init --url https://app.getpad.dev --workspace my-workspace
Self-hosting stays first-class: the binary is unchanged and no features are Cloud-only.
Upgrading Pad
Pad ships a new binary on a roughly weekly cadence. Upgrades are designed to be boring: install the new binary and restart. Database migrations run automatically at startup, only the ones your database is missing are applied, and each migration commits atomically (a failed migration rolls back cleanly and is retried next boot).
The one rule: only ever move forward. Newer binaries know how to migrate an older database; older binaries do not understand a newer schema. Since Pad added its schema-ahead guard, a downgraded binary that finds a database newer than itself refuses to start rather than silently running old code against a newer schema (which can corrupt data):
database schema is newer than this pad binary: ... This almost always means the
binary was DOWNGRADED (e.g. brew/docker rollback) ... Upgrade pad back to a build
that includes those migrations, or re-run with `pad start --force`.
To recover, reinstall the newer binary (brew upgrade pad, pull the newer Docker tag, etc.). If you have intentionally downgraded and accept the risk, start with pad start --force (or set PAD_ALLOW_SCHEMA_AHEAD=1) to override the guard.
Automatic pre-migration snapshot (SQLite). Whenever a SQLite-backed instance has pending migrations to apply, Pad first copies the database file to pad.db.pre-<version> next to it. If an upgrade ever goes wrong, stop the server and copy that snapshot back over pad.db. This is a convenience net, not a backup strategy — keep your own backups (see docs/backup.md). PostgreSQL instances are skipped here; use pg_dump or a provider snapshot before upgrading.
Recommended upgrade flow:
# 1. Back up first (SQLite shown; see docs/backup.md for Postgres)
pad db backup -o pad-backup-$(date +%Y%m%d).db
# 2. Stop the server, install the new binary, restart
# (migrations + the pre-migration snapshot run automatically on start)
brew upgrade pad # or: docker pull, binary download, make install
# 3. Confirm it's healthy
pad --version
curl -s localhost:7777/api/v1/health
Getting Started
1. Set up Pad
cd ~/projects/myapp
pad init "My App"
pad init is the smart entry point that handles everything in one command:
- Configures this client's connection (local server, remote, or Docker)
- Auto-starts the local server
- Creates the first admin account on a fresh local install (Docker / remote hosts run
pad auth setupon the server instead) - Logs you in if needed
- Creates or links a workspace for the current directory (writes
.pad.toml) - Installs the
/padskill for any AI tools detected in the project
Run from your project root. Safe to re-run anytime — it skips finished steps and prints a status summary if nothing's needed.
Choose a template with --template, or omit it for an interactive picker grouped by category (Software / People / …):
pad workspace init --list-templates # See the full catalog grouped by category
pad init "My App" --template scrum # Scrum-style with sprints
pad init "My App" --template product # Product management focused
pad init "My Hiring" --template hiring # Company-side: requisitions, candidates, interview loops, feedback
pad init "Job Search" --template interviewing # Candidate-side: applications, interviews, companies, contacts
pad init "My App" --template blank # Custom: system collections only — let /pad onboard build the rest
Pad ships templates for software (startup / scrum / product), people workflows (hiring, interviewing), and a custom blank template — system collections (Conventions, Playbooks) only, with the /pad onboard playbook as its sole seeded content. blank is the entry point for the agent-driven /pad onboard flow: it walks you through shaping collections, conventions, and roles to match your actual project. Reserved categories for research, content, operations, and personal use await their first templates, so the same project-management primitives fit well beyond code projects. There's also a hidden demo template — the startup layout pre-loaded with realistic sample data — that's kept out of the picker but can be built explicitly with --template demo.
2. Start working
# From the CLI
pad item create task "Set up CI pipeline" --priority high
pad item create idea "Add WebSocket support" --category infrastructure
pad project dashboard
# From the web UI
pad server open # Opens localhost:7777 in your browser
# From your AI agent
# Just use /pad in Claude Code, Cursor, etc.
3. Teach your agents the rules
In an agent session inside the workspace:
/pad onboard
The agent walks an interview, detects your tooling, and adapts the workspace's collections, conventions, roles, and playbooks. To browse the library directly:
pad library list --type conventions # Pre-built conventions you can adopt
pad library list --type playbooks # Pre-built multi-step workflows
4. Optional — connect a desktop AI app via MCP
Pad ships an MCP (Model Context Protocol) server so Claude Desktop, Cursor, Windsurf, Claude Code, or Codex can manage items, plans, ideas, and dependencies as native tools, read workspace state by URL, and load multi-step workflows as prompts.
pad mcp install claude-desktop # or: cursor, windsurf, claude-code, codex, --all
# Restart the client; pad shows up as the "pad" MCP server.
pad mcp install writes each client's native config: JSON mcpServers for
Claude Desktop / Cursor / Windsurf, a project-local .mcp.json in the current
directory for claude-code, and an [mcp_servers.pad] table in
~/.codex/config.toml (TOML) for codex. Because Claude Code's config is
project-scoped, it's install-on-request only — --all and pad mcp status cover
the per-user clients (including Codex) and skip it.
Tool catalog (v0.30) — ten resource × action tools plus pad_set_workspace (eleven total), no flat verb explosion. Undeclared input keys are rejected with a structured error rather than silently dropped. pad_item create/update accept field values as a fields object (the same shape reads return) as an equivalent to the dedicated params / field: ["key=value"], and its values keep their JSON types where the transport can carry them. Field values are typed against the collection schema server-side, so a declared number or json field is writable from the remote transport (which sends every value as a string). Keys the schema does not declare are stored and NAMED back in warnings.undeclared_fields. One key supplied through two doors is adjudicated once: differing values are refused, equal ones collapse, and two names for the same target — parent/plan, assign/assigned_user_id, role/agent_role_id — are refused even when the values match. pad_item.list accepts unparented: true (mutually exclusive with parent) to select items with no parent or implements relationship, and is summary-shaped by default on both transports (full: true opts into complete content bodies):
| Tool | Actions |
|---|---|
pad_item |
create, update, delete, get, list, move, restore, link, unlink, deps, star, unstar, starred, comment, list-comments, backlinks, bulk-update, note, decide, export, import, history, remind, ack-reminder |
pad_workspace |
list, members, invite, storage, audit-log, create, claim, deleted, restore |
pad_collection |
list, create, update, delete |
pad_project |
dashboard, next, ready, stale, standup, changelog, report, activity |
pad_role |
list, create, update, delete |
pad_search |
query |
pad_playbook |
list, get, run |
pad_library |
list, get, activate |
pad_attachment |
list, show |
pad_meta |
server-info, version, tool-surface, bootstrap |
pad_set_workspace |
session-default workspace pinning (response embeds the bootstrap blob) |
Plus resources at pad://workspaces, pad://workspace/{ws}/dashboard,
pad://workspace/{ws}/items, pad://workspace/{ws}/items/{ref},
pad://workspace/{ws}/collections,
pad://workspace/{ws}/attachments/{id} (bounded image bytes),
pad://workspace/{ws}/bootstrap,
and pad://_meta/version.
Stability contract — two version constants, both advertised in the
initialize handshake under capabilities.experimental.padCmdhelp and
capabilities.experimental.padToolSurface (and queryable at
pad://_meta/version):
cmdhelp_version: "0.1"— CLI help-tree contract (used at dispatch time)tool_surface_version: "0.30"— MCP tool catalog contract (v0.5 addedpad_library; v0.6pad_item.backlinks; v0.7pad_itemexport/import; v0.8pad_workspacedeleted/restore; v0.9 madepad_item.listsummary-shaped by default with a default+max result cap; v0.10 enforced the draft-playbook gate server-side onpad_playbook.runwith anallow_draftescape hatch; v0.11 added the read-onlypad_attachmenttool (list/show); v0.12 addedpad_project.activity(agent-accessible non-streaming activity feed); v0.13 addedpad_projectready/stale(agent-oriented backlog + attention queries); v0.14 addedpad_itemhistory+ optimistic concurrency (TASK-2022); v0.15 added thepad_item.listunparentedparameter (TASK-2096); v0.16 made an empty-stringassigned_user_id/agent_role_idCLEAR the assignment instead of being silently dropped, so an agent can finally unassign an item (TASK-2571); v0.17 carried that to the LOCAL STDIO transport by teaching the CLI to lift those keys onto their columns instead of into the fields blob (BUG-2583); v0.18 addedclear_assigned_user/clear_agent_rolebooleans — the canonical, schema-discoverable way to unassign, backed by new--clear-assigned-user/--clear-agent-roleflags onpad item update(IDEA-2584); v0.19 added aclear_parentboolean — the canonical, schema-discoverable way to detach an item from its parent, backed by a new--clear-parentflag onpad item update(BUG-2078); v0.20 gave every tool an explicit annotation block derived from the catalog’s read-only knowledge — fully-read-only tools advertisereadOnlyHint: true/destructiveHint: false, all-additive-write tools (pad_workspace,pad_library) dropdestructiveHint, overwrite/delete-capable tools stay conservatively destructive,openWorldHint: falseeverywhere — replacing mcp-go’s defaults that marked every tool destructive (BUG-2302), and madepad_item.listsummary-shaped on the remote HTTP transport too, with a declaredfullboolean as the opt-in for complete bodies on both transports (BUG-2305); v0.21 boundedpad_item.history, which was unbounded on every surface —limitnow covers it (default 50, max 300, the NEWEST N; nooffset, because reverse-patch storage makes only a newest-end window cheap), applied in the catalog action so it lands on both transports, and summary mode now asks the server to skip patch resolution rather than resolving bodies the dispatcher discards (BUG-2608); v0.22 stoppedpad_item.movedestroying an item’s system metadata — implementation notes, decision log, linked PR and convention data now survive a move, any field the destination schema has no home for is REPORTED in the move’s activity entry rather than vanishing, and afieldsetter naming one of those reserved keys is refused withmalformed_overrideinstead of writing it (BUG-2674); v0.23 closed the same door on the ordinary update — afieldsetter namingimplementation_notes,decision_logorconventionis now refused on every transport at once (validation_erroron HTTP, surfaced to MCP clients asvalidation_failed); the one gate covers the CLI, remote MCP and stdio MCP at once because all three lower afieldsetter into the samefields_patch;github_pris deliberately exempt ON UPDATE (move and copy still refuse it), sincepad github linkcannot run on remote MCP and refusing it would leave those agents with no door at all (that door is itself broken — BUG-2696); item CREATE stays open, deliberately, because its full-fieldspayload is shared with Pad’s own writers. v0.23 also added the retry-hostilestored_state_unreadableerror code so an agent told its target item’s stored data is unreadable stops instead of retrying a permanent failure (BUG-2627 / BUG-2675); v0.24 made thepad_itemfieldsobject a real write form on create/update — reads returnfieldsas a native object, and writing that shape back was a silent no-op (accepted, never mapped, dropped while the PATCH still bumpedupdated_at) — merging it into the same path asfield/the dedicated params with conflicting duplicate keys refused, and made input validation strict across all catalog tools: undeclared top-level keys now fail with a structured error instead of being silently dropped (#1066); v0.25 madepad_library.activateresolve its DESTINATION collection from the target’s declared artifact kind (SPEC-5 collection traits) rather than the literalconventions/playbooksslugs, so activating into a workspace that renamed either collection lands correctly instead of failing not-found with the collection sitting right there (BUG-2702); a lookup ERROR is now surfaced rather than silently falling back to the canonical slug, because falling back on an error means writing to a slug nothing was confirmed about (TASK-2657); v0.26 madepad_workspace.createREFUSE with a 403 when the calling OAuth connection's grant hasmay_create_workspaces=false— that checkbox previously gated only the post-creation auto-add, so a connection whose user declined it could still create workspaces — and on a connection with an explicit workspace allow-list, could not then see them (a wildcardall_current_workspacesconnection could, which is why the consent mismatch rather than the invisibility is the defect); the same gate coversPOST /workspaces/import, which mints a workspace through a second door. There is deliberately no escape-hatch parameter: the gate expresses the USER's consent decision, so only the user can lift it — by re-authorizing, or by enabling the flag on the existing connection at/console/connected-apps(IDEA-2756); v0.27 typed field values server-side so a declared number/json field is writable from the remote transport at all, carried thefieldsobject with its JSON types intact, named undeclared keys back inwarnings.undeclared_fields(accepted rather than refused — a census of 1012 items found 14 such keys across 168 live values, so refusing would have broken read-modify-write on items nobody had edited wrongly), and replaced the accreted per-site conflict guards with ONE check over a canonical view of every source; that check refuses several ambiguities v0.26 resolved silently, chiefly two names for one target in a single call (parent/plan,assign/assigned_user_id,role/agent_role_id), refused even when the values match because the names address one thing through incomparable vocabularies and the two doors resolved them differently (BUG-2850); v0.28 added two ADDITIVEpad_itemactions —remind, which arms a one-shot reminder at an RFC3339 instant (remind_at), andack-reminder, which acknowledges a fired one by id (reminder_id); a bareYYYY-MM-DDis refused rather than read as midnight, since a date names a 24-hour span and picking an hour inside it would be the server choosing a time nobody did (IDEA-2641); v0.29 made arelationfield value have to NAME A LIVE ITEM in the collection that field declares —internal/itemsonly ever checked the SHAPE of a relation ("must be a string"), because deciding whether a string names an item is a database question and that package is DB-free, so any string at all was accepted and stored and no client could render it honestly; every write door now refuses a value that names nothing, names an item in the WRONG collection, sits in a field whose schema declares no target collection, or is a SLUG (a deliberate divergence fromResolveItem: a slug is neither an ID nor stable, and free text like "red" resolving to whatever is sluggedredtoday is exactly the corruption this closes). A CARRIED value — one already on the item, asserted by nobody — is never refused, because refusing would make every legacy item un-updatable, un-movable and un-copyable: within a workspace it resolves and survives, across a workspace boundary it is dropped without a lookup and reported inwarnings.dropped_fields, sopad_item.action=copynow names a drop where v0.28 silently landed a dangling reference (PLAN-2857 / TASK-2878); ; v0.30 made one--field key=valueentry mean ONE thing at every door — six sites parsed it independently (item create,item list,item update,item move,item copy, and the remote door’s own ingest) in four spellings, sofield:[" effort=l"]stored an undeclared field literally named " effort" through the CLI and wroteeffortthrough /mcp, the same call storing two different keys depending only on the transport. All six now share one parse, with two deliberately asymmetric rules: a padded KEY is REFUSED everywhere rather than trimmed anywhere (trimming silently retargets the write to a field the caller did not type), and a VALUE is carried VERBATIM everywhere (trimming reinterprets a caller’s bytes, and on a text field the padding is content) — a padded value against a typed field is refused one layer down by validation, naming the field, which is the same answer at both doors since v0.27 types declared fields server-side. Both doors refuse something they used to accept, and they were accepting it differently — /mcp trimmed the padded key and wrote the declared field, the CLI stored a ghost field beside it; what is /mcp-only is the value half, which it used to trim and type and now passes through to the same validation the CLI has always applied. A caller writing canonical entries sees no difference at either door (BUG-2870); seeinternal/mcp/version.gofor the full changelog)
External agents pin against these so a future rename doesn't break them
silently. Errors come back as structured envelopes ({error: {code, message, hint, available_workspaces, ...}}) with a closed code
taxonomy — 17 codes as of v0.23, enumerated in
internal/mcp/errors.go. Branch on code, not on message text; a code
you don't recognize is possible, and stored_state_unreadable in
particular means STOP rather than retry.
Full guide at getpad.dev/mcp/local — install paths, action enums per tool, error taxonomy, troubleshooting.
On Pad Cloud? Skip the install: add https://mcp.getpad.dev as a remote
MCP server in Claude Desktop, Claude.ai, Cursor, or Windsurf and sign in with
OAuth — same tool surface, no local binary. Setup guide at
getpad.dev/mcp/remote.
CLI Reference
pad auth configure Configure how this client connects to Pad
pad auth setup Initialize the first admin account
pad auth login Sign in
pad auth whoami Show current user
pad server start Start the Pad API server
pad server stop Stop the Pad server
pad server info Show client, connection, and local server status
pad server open Open web UI in browser
pad workspace init [name] Initialize workspace in current directory
pad workspace link <workspace> Link current directory to an existing workspace
pad workspace list List all workspaces
pad workspace switch <workspace> Switch active workspace
pad workspace context Show structured workspace context
pad workspace context set --file X Update structured workspace context from JSON
# Workspace onboarding: run `/pad onboard` from an agent session inside the workspace
pad workspace members List workspace members
pad workspace invite <email> Invite a workspace member
pad workspace join <code> Accept an invitation
pad workspace export Export workspace data
pad workspace import <file> Import workspace data
pad project dashboard Project dashboard
pad project next Recommended next task
pad project ready Query actionable next items
pad project stale Query stalled or attention-worthy items
pad project standup [--days N] Daily standup report
pad project changelog [--days N] Release notes from completed items
pad project watch Real-time activity stream
pad project reconcile Reconcile item and PR state
pad item create <coll> "title" Create item (task, idea, plan, doc, ...)
pad item list [collection] List items (filters: --status, --priority, --all)
pad item show <ref> Show item detail
pad item open <ref> Open item in web UI
pad item update <ref> Update item fields
pad item delete <ref> Delete item
pad item move <ref> <collection> Move item between collections
pad item edit <ref> Open item in $EDITOR
pad item search "query" Full-text search across all items
pad item comment <ref> "text" Add comment to an item
pad item comments <ref> View item comments
pad item note <ref> "summary" Append an implementation note to an item
pad item decide <ref> "decision" Append a decision log entry to an item
pad item block <src> <target> Create dependency
pad item blocked-by <item> <blk> Mark item as blocked
pad item deps <ref> Show dependencies
pad item unblock <src> <target> Remove dependency
pad item related <ref> Show direct relationships for an item
pad item implemented-by <ref> Show incoming implementers for an item
pad item bulk-update --status X Batch update multiple items
pad collection list List collections with item counts
pad collection create <name> Create a custom collection
pad library list Browse convention and playbook library
pad library activate <title> Activate a convention or playbook
pad agent install [tool] Install /pad skill for AI coding tools
pad agent status Show supported tools and installation status
pad agent update Update installed tool integrations
pad github link [item-ref] Link current branch's PR to item
pad github status [item-ref] Show PR status for linked items
pad github unlink <item-ref> Remove PR link from item
pad webhook list List workspace webhooks
pad webhook create <url> Create webhook
pad session register Record this session (harness pid + agent name) locally
pad session list Registered sessions on this machine, with liveness
pad session prune Remove records of sessions that are dead
All commands accept --format json for machine-readable output and --workspace to target a specific workspace.
Shell completion
pad ships completion scripts for bash, zsh, fish, and PowerShell:
# Bash — current session only
source <(pad completion bash)
# Bash — persistent
pad completion bash > /etc/bash_completion.d/pad # Linux
pad completion bash > $(brew --prefix)/etc/bash_completion.d/pad # macOS (Homebrew)
# Zsh (make sure compinit runs in your ~/.zshrc)
pad completion zsh > "${fpath[1]}/_pad"
# Fish
pad completion fish > ~/.config/fish/completions/pad.fish
# PowerShell (append the output to your $PROFILE)
pad completion powershell | Out-String | Invoke-Expression
Beyond command and flag names, completion is context-aware: collection arguments (e.g. pad item list <TAB>) complete against your workspace's collections, --workspace completes configured workspace names, and --status / --priority complete their valid values.
Authentication
Pad runs without authentication by default for frictionless local use. For local installs, pad init creates the first admin account inline. The lower-level commands are useful when you're hosting a Pad server (Docker / remote) and need to set up auth on the server host directly:
pad auth setup # Initialize the first admin account (server host, non-local mode)
pad auth login # Sign in
pad auth whoami # Show current user
pad auth logout # Sign out
Once a user exists, all API requests and web UI access require authentication. Credentials are stored in ~/.pad/credentials.json. Multiple users can be invited to workspaces with role-based access control (owner, editor, viewer).
Authenticating with an environment token
Set PAD_TOKEN to a Pad API token (minted with pad token create, or under Settings → API tokens in the web UI) to authenticate without pad auth login:
PAD_TOKEN=pad_xxxxxxxx pad item list
PAD_TOKEN authenticates every command except one: minting a token needs a session, so pad token create is refused when the override carries a pad_ API token — see Managing API tokens from the CLI below. PAD_TOKEN takes precedence over credentials saved by pad auth login — the same convention as gh's GH_TOKEN. This is useful for CI, scripts, and machines where several AI agents share one CLI install but should act as different Pad users: give each agent its own token in its process environment, and the credential store is never touched. pad auth whoami reports the token's identity (with an Auth: PAD_TOKEN environment override line), and pad auth login/logout warn when the override is active — they manage the stored credentials, which the override bypasses. Deliberately, pad auth logout never invalidates the PAD_TOKEN session itself: it signs out the stored session only, and the env token's lifecycle belongs to wherever it was minted (revoke it with pad token revoke or under Settings → API tokens).
Managing API tokens from the CLI
pad token create --name ci-agent # Mint a token (secret shown once)
pad token create --name cursor --expires-in 30
pad token list # Metadata only — never secrets
pad token revoke <token-id> # Immediate; the id must be exact
Tokens are user-scoped and act as the user who minted them. create prints the secret exactly once — the server stores only a hash and cannot show it again — so pair each mint with wherever the token will live (CI secret store, an agent's PAD_TOKEN). revoke takes the exact id from pad token list; revocation is immediate, and anything still authenticating with that token fails on its next call.
create needs a login session; list and revoke do not. Minting a token from a session authenticated by a token is refused with HTTP 403 and the code session_required — "Creating or rotating API tokens requires an interactive session, not an API token". So pad token create fails whenever the request is authenticated by an API token — including a pad_ token in PAD_TOKEN, which takes precedence over a stored login — and works from a session. PAD_TOKEN also accepts a padsess_ session token, and that one IS a session, so it mints normally; a browser cookie and a saved CLI session likewise. On a headless machine, pad auth login -i prompts for email and password instead of opening a browser (plain pad auth login is browser-based). The reason for the gate is that the tokens a token mints outlive the revocation of the token that minted them: each has its own name and expiry, and nothing in pad token list records which token minted which — so revoking a leaked credential would not end the access established with it. list and revoke stay reachable by a token deliberately, because revocation is the response to a compromised credential and should not need a fresh login.
pad workspace members # List workspace members
pad workspace invite user@example.com
pad workspace join <code>
Architecture
┌──────────────────────────────────────────────┐
│ pad (single binary) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│ │ CLI │ │ REST │ │ Embedded │ │
│ │ (Cobra) │ │ API │ │ Web UI │ │
│ └────┬─────┘ └────┬─────┘ │ (SvelteKit)│ │
│ │ HTTP │ └────────────┘ │
│ └──────────────┤ │
│ ┌─────▼─────┐ │
│ │ SQLite │ │
│ │ + FTS5 │ │
│ └───────────┘ │
└───────────────────────────────────────────────┘
- Go backend — chi router, SQLite via modernc.org/sqlite (pure Go, no CGO), FTS5 full-text search, SSE for real-time updates
- SvelteKit frontend — Svelte 5, Tiptap editor, drag-and-drop, adapter-static, embedded via
go:embed - Single binary — serves the API and web UI, runs on macOS, Linux, and Windows
- Workspace-per-project — each project gets its own workspace linked by a
.pad.tomlfile
Self-hosted, all data lives in ~/.pad/pad.db. Your data. Your machine. No telemetry, no accounts required — cloud only if you opt in.
Community
- r/getpad — how-tos, roadmap discussion, and notes from the agents that run Pad's own workspaces
- GitHub Issues — bugs and feature requests
- X / Bluesky — release announcements
Contributing
See CONTRIBUTING.md for the development guide.
make build # Build web UI + Go binary
make test # Run Go tests
make dev-web # SvelteKit dev server with hot reload
make install # Build, install to ~/.local/bin, restart server
Security
See SECURITY.md for reporting vulnerabilities.
Pushes into agent sessions are consent-gated. pad push (and the web push composer) puts an item — and a message — in front of a running Claude Code session as direction from its own user. That is deliberate terminal instruction injection, so since v0.15.0 (PLAN-2613) receiving it is opt-in per session, not a side effect of installing the plugin:
- No consent, no stream. Nothing streams and nothing listens — watches and pushes alike — until the session consents (the plugin's always-on wrapper only registers presence and exits).
/pad:connectarms the session locally and starts the monitor, which announces the armed state when its stream connects;/pad:disconnectwithdraws;/pad:statusreports the state. A repo can opt its sessions in at start withpush.auto_arm = truein.pad.toml— an explicit file edit, never a machine-global default, and vetoable per user in~/.pad/config.toml. - Self-addressed only. The server forces every push's target to the caller's own sessions; nobody can push into a session that isn't theirs. Delivery is filtered to armed sessions, and the surfaces are honest about it: the web composer shows the split ("2 connected, 0 accepting pushes") and withholds a send it knows nobody would accept; a CLI broadcast still publishes and reports
delivered_sessions(in JSON output), and a targeted push to a session that is not accepting skips the publish rather than pretending. - No grandfathering. Updating the plugin replaces the v0.14 always-on monitor with the gated one for everyone. Sessions that used to receive pushes receive none until they connect; the web composer's counts make that visible rather than silent.
- The accepted caveat. An agent can run the arm command from inside its own session. That is visible in the transcript, within the operator's sight: the gate protects sessions from the outside and does not police the inside. A push can inject text; it cannot click a permission prompt.