xarmian
f268b66344
* feat(web): mount split-pane detail view + row-click open (TASK-2112, TASK-2111)
PLAN-2105 wave 2 — the increment where the Asana-style right-docked detail
pane first becomes visible. Builds on the merged TASK-2106 (<ItemDetail>
embedded extraction) and TASK-2110 (?item= URL plumbing).
TASK-2112 — split layout + mount the pane:
- .collection-page becomes a flex row when ?item= is set: list column
(flex:1, always mounted, wrapped in .list-column) + a right-docked
.item-pane that breaks out of the max-width constraint (mirroring how
board-active drops max-width) and fills .main-content so it scrolls
independently. Board view's wrapper preserves its fixed-height fill.
- Mount <ItemDetail ref={openItemRef} embedded ...> inside {#if openItemRef}
with NO {#key} wrapper — A->B is a PROP UPDATE that reuses the mounted
instance (re-drives loadData/collabKey via ref), open/close is the only
mount/unmount.
- Cross-collection ?item= safety: ItemDetail derives its effective
collection (schema + URLs) from the loaded item.collection_slug when
embedded, refetching the correct collection on mismatch and surfacing a
load failure rather than rendering the route collection's schema.
- Paned row highlighted in list, board AND table (focusedItemId now threaded
into TableView; an effect snaps the cursor to the open pane's item).
- Title precedence: the embedded ItemDetail owns the tab title while
mounted; the collection page gates its own title writer on !openItemRef.
- The 2 EditCollectionModal route-away gotos are parameterized through
onNavigateAway/onGone so an embedded pane doesn't hard-navigate the page.
- loadData is fenced by a monotonic loadGeneration (bumped on unmount) so
overlapping A->B loads can't clobber newer state.
TASK-2111 — opt-in row-click interception:
- Added an onclick to the plain ItemCard + TableView title anchors, href
intact: plain left-click -> preventDefault + onItemOpen; modifier/middle
click falls through to the full-page URL (popout); sub-control clicks are
untouched (they already stopPropagation).
- onItemOpen threads from +page.svelte through ListView/BoardView to
ItemCard and directly to TableView (openItemPane); absent elsewhere
(starred/tags/roles) it defaults to full-page anchor nav.
- Keyboard Enter opens the pane; handlePageKeydown now also bails on
contenteditable / .item-pane so keys typed in the pane editor aren't
captured by list navigation.
- openItemPane pushes history on first open, replaces on re-target so
paging A->B->C doesn't stack entries Back must unwind.
npm run check clean; Codex review CLEAN.
Claude-Session: https://claude.ai/code/session_01EZ6yr6pAUFb1uffan912ra
* fix(web): switch-safety hardening for the no-{#key} detail pane (TASK-2112, TASK-2111)
The split-pane switches items via a PROP UPDATE (no {#key} remount), so the
mounted ItemDetail instance is reused across item A→B. Async continuations
written for the full-page route (where the component effectively lived one
item at a time) can now resolve after the pane has re-targeted, letting stale
work land on the wrong item. This closes that whole class (pulls TASK-2117/
2118 substance forward — reachable now that the pane exists).
The four coordinator-named defects:
1. Raw-markdown pending edits were dropped on switch. loadData's reset now
flushNow({keepalive:true}) the dirty raw saver against the OLD item BEFORE
clearPending() — wrapped in untrack() so reading `item` there doesn't make
it a dependency of the route effect (which would duplicate-load).
2. Late post-await item writes (saveTitle / assignment / role / restore /
updateField / stampSourceUrl / relationship add+remove / refreshFromSource /
copy-ref / legacy content save) unconditionally reassigned `item`. All now
capture (targetItem, loadGeneration) before the await and drop the write +
feedback via a shared switchedAway() helper (id + generation → also closes
the A→B→A id-reuse gap). handleCreateLink/handleDeleteLink now refresh via
the CAPTURED slug, not the live itemSlug.
3. Stale collab provider stayed active after its editor was destroyed. collabKey
is now gated on a new itemMatchesRef derived, so it goes null the instant
`ref` changes (tearing the old provider down before the new fetch resolves);
onApplierRequest rejects a destroyed editor / superseded provider / mismatched
item; the force_refresh GET chain bails on collabProvider!==provider.
4. Destructive/ephemeral UI leaked across the switch. loadData now resets
confirmDelete + all open menus/dialogs/drawers + in-flight op flags
(deleting/moving/restoring/refreshing) + add-link state + copied +
backlinksCount, so an armed delete on A can't delete B.
Also: SSE onItemEvent + sync onSync bail on !itemMatchesRef and generation-fence
every post-await guard (incl. the catch handleGone) so a stale archive/delete
can't close the newly-opening pane; the rich→Markdown toggle is generation-fenced
(try AND catch) so B can't mount in rawMode seeded with A's content; delete/move
feedback is fenced; the raw saver (debounced save + flushRawIfPending) carries a
generation check alongside the id check.
Deliberately left id-scoped (by design, not bugs): the tagSavers Map keyed by
item.id (coalesces a navigate-away-and-back into the running per-item saver) and
the collab-snapshot flusher's activeCollabContext capture (intentionally PATCHes
the OLD item's URL on a mid-flight switch — its documented never-cross-write
guarantee).
npm run check clean; Codex review CLEAN.
Claude-Session: https://claude.ai/code/session_01EZ6yr6pAUFb1uffan912ra
* fix(web): switch-safety sweep into descendant panels (TASK-2112, TASK-2111)
Second batch of the no-{#key} pane switch-safety hardening. The reused
ItemDetail instance keeps its per-item DESCENDANT panels mounted across an
A→B item switch too, so their in-flight async loads can resolve after the
switch and (a) overwrite the new item's display data or (b) invoke a parent
callback with the OLD item's data. Systematic sweep: every per-item async
continuation in ItemDetail AND every descendant panel it renders now captures
its request identity before the await and drops the post-await state-write /
parent-callback / navigation when the identity no longer matches.
ItemDetail.svelte (the three remaining spots):
- handleVersionRestore — the descendant version card's restore await resolves
in the parent's sync callback; now drops the write unless the restored
item is the one currently shown (A's restore can't render under ?item=B).
- isForegroundCurrent (collab-snapshot flusher) — the UI-feedback gate now
also checks a generation captured at flush-start, so setDirty(false)/
showSaved()/saveStatus/error-toast can't fire for a superseded generation
after A→B→A (the flush's PATCH targeting stays ctx-scoped, unchanged).
- navIfStillCurrent (move) — now uses stillOnSource() (folds in the load
generation) so a superseded move can't navigate after A→B→A.
Descendant panels — fenced by capturing the item-identifying prop(s)
(itemSlug/itemId/wsSlug) before each await and dropping the write/callback on
mismatch:
- ChildItems.loadChildren — no longer overwrites B's children or fires
onChildrenChange (→ parent childItemIds/progress/terminal overrides) with A.
- BacklinksPanel.loadFirstPage + loadMore — no longer overwrite B's backlinks
or push A's count into the parent's mention badge.
- ItemTimeline: loadTimeline, loadMore, probeAttachment, the SSE-debounced
refresh, submitComment, and handleReply/Edit/Delete/Reaction/RemoveReaction
— each drops its entries/error write + follow-up reload on mismatch.
- TimelineVersionCard: confirmRestore (does NOT invoke onRestore if switched
by resolve-time) + ensureResolved (guards its lazy content/error writes).
- CommentEditor.doSubmit — captures wsSlug+itemId before awaiting onSubmit and
only clearContent() when still the same item + editor alive, so switching to
B while A's comment submits can't erase B's freshly-typed draft.
Left id-scoped by design (documented exceptions, verified safe): tagSavers Map
keyed by item.id; the collab-snapshot flusher's activeCollabContext capture;
loadTagSuggestions (workspace-scoped, fenced on ws); FieldEditor (drops its
pending typed value on value-prop change / unmount). TimelineCommentCard,
TimelineActivityCard, and DiffView carry no unfenced per-item continuation.
npm run check clean; independent adversarial Codex pass over the diff CLEAN.
Claude-Session: https://claude.ai/code/session_01EZ6yr6pAUFb1uffan912ra
* refactor(web): structural containment via {#key itemSlug} for the split pane (TASK-2112, TASK-2111)
Owner decision: stop chasing per-await switch-safety fences one at a time —
the class doesn't converge that way. Contain it structurally instead. Wrap the
NON-EDITOR body subtree of ItemDetail in {#key itemSlug} so it remounts on
every item switch, which structurally cancels stale async continuations in the
descendant panels. Keep the perf-critical editor/collab machinery persistent.
{#key itemSlug} boundary (keyed on itemSlug — the ref/URL identity — NOT
item.id, so the panels reset and show loading/empty the instant the ref
changes, before B's data resolves):
- INSIDE the key (remount per switch): the QuickActionsMenu, the .fields-panel
(FieldEditor debounces + assignment selects), the relationships / add-link
form / ChildItems / BacklinksPanel / ItemTimeline (comments + composer +
version cards) block, ShareDialog, and EditCollectionModal.
- OUTSIDE the key (persistent, the whole no-{#key} perf premise): the
.content-panel — RawMarkdownEditor, both collab <Editor> instances (each
keeps its OWN existing {#key `${item.id}...`} for the per-item Y.Doc swap),
EditorBubbleMenu, EditorLinkPopover. The collab provider $effect, collabKey,
and the SSE/sync onMount/onDestroy subscriptions are script-level and
untouched — so an A→B switch still spins up no second WebSocket and keeps the
one persistent item SSE subscription.
Bounded residue that {#key} does NOT cover — code that writes into the
PERSISTENT editor after an await — is explicitly fenced:
- EditorBubbleMenu.handleCreate: captures the originating editor before the
create await; on an item switch mid-create it skips the wiki-link insert +
onItemCreated + toast (the item was still created — SSE reconciles the
index) and resets the persistent menu's form directly (hide() no-ops while
`creating` is true).
- ItemDetail Rich-mode button: captures item+generation before
`await flushRawIfPending()` and bails before writing rawMode/rawSeedMarkdown
(flushRawIfPending's re-entrancy waiter can resolve true post-switch).
- ItemDetail Markdown-toggle loop: a generation+id check IMMEDIATELY after each
`await collabFlusher.flush(...)`, before inspecting the result / showing a
recovery toast / continuing the loop.
The batch-1/2/3 root-logic + descendant fences are KEPT as defense-in-depth
(removing them risks regression); the {#key} is an ADDITIONAL structural layer.
npm run check clean; Codex review CLEAN (boundary placement verified: editor/
content-panel carries no added itemSlug key; all keys balanced + on itemSlug;
all three residue fences correct).
Claude-Session: https://claude.ai/code/session_01EZ6yr6pAUFb1uffan912ra
* fix(web): parent-side fences for destroyed-child callbacks into the persistent pane (TASK-2112, TASK-2111)
The {#key itemSlug} structural containment resets each panel's OWN state on
switch, but it can't cover the residue: a destroyed A-instance child's in-flight
promise still resolves and fires its callback UP into the persistent parent
(ItemDetail), and the child's own identity check passes (its prop is frozen at
A). So A's result would land on B through 4 parent-callback handlers. The fence
must be parent-side.
At each {#key itemSlug} block, `{@const keyedSlug = itemSlug}` freezes the
render-time ref for that instance's closures; each callback guards
`if (keyedSlug !== itemSlug) return;` — where `itemSlug` in the closure reads
the LIVE component value, so a callback fired from a superseded (A) render is
dropped once the pane has moved to B (the current render's callbacks always
pass). The 4 fully-enumerated handlers:
1. QuickActionsMenu oncollectionupdated — guard before `collection = updated`
(a cross-collection switch would otherwise land A's collection on B).
2. ChildItems onChildrenChange (→ handleChildrenChange: progress / childItemIds
/ terminal-status overrides) — guard before delegating.
3. BacklinksPanel onCountChange — guard before `backlinksCount = n`.
4. EditCollectionModal onupdated — guard as the FIRST statement so a superseded
modal's completed save/archive can't reload / navigate / close B's pane.
The children keep their own request-identity self-fences (defense-in-depth);
this adds the parent-boundary layer they structurally cannot provide. Other
child→parent callbacks are already covered: onRestore→handleVersionRestore
(item.id identity check) and FieldEditor/TagInput/assignment → updateField /
updateAssignedUser / updateAgentRole / updateTags (root-fenced); onmanage is a
click handler (a destroyed menu can't be clicked), not an async continuation.
npm run check clean; Codex review CLEAN.
Claude-Session: https://claude.ai/code/session_01EZ6yr6pAUFb1uffan912ra
Pad
Project Management for the agent era.
Website · Docs · Blog · Changelog · 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. All agent actions are attributed in the activity feed, so you always know what the AI changed.
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+.
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.
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.15) — ten resource × action tools plus pad_set_workspace (eleven total), no flat verb explosion. pad_item.list accepts unparented: true (mutually exclusive with parent) to select items with no parent or implements relationship:
| 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 |
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.15"— 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); 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 eight-code
taxonomy.
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
All commands accept --format json for machine-readable output and --workspace to target a specific workspace.
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).
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.
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.