Skip to content
Back to search

pad

Official Pad marketplace — the pad plugin: conversational project management, a side panel and live item notifications for Claude Code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/perpetualsoftware--pad/badge.svg)](/listings/perpetualsoftware--pad)

HTML

<a href="/listings/perpetualsoftware--pad"><img src="/api/listings/perpetualsoftware--pad/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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."

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines
  1. {
  2. "name": "pad",
  3. "owner": {
  4. "name": "Perpetual Software LLC",
  5. "url": "https://getpad.dev"
  6. },
  7. "plugins": [
  8. {
  9. "name": "pad",
  10. "source": {
  11. "source": "git-subdir",
  12. "url": "https://github.com/PerpetualSoftware/pad.git",
  13. "path": "plugin",
  14. "ref": "v0.21.0"
  15. },
  16. "description": "Talk to your project. Pad is local-first project management for developers and AI agents — this plugin gives Claude Code a conversational Pad skill, typed shortcuts (/pad:status, /pad:capture, /pad:onboard), a /pad-pane side panel, and live item-change notifications."
  17. }
  18. ],
  19. "description": "Official Pad marketplace — the pad plugin: conversational project management, a side panel and live item notifications for Claude Code."
  20. }
README.md · README · 705 lines
  1. <p align="center">
  2. <img src="docs/brand/mark/pad-mark.svg" width="72" height="72" alt="">
  3. <h1 align="center">Pad</h1>
  4. <p align="center"><strong>Project Management for the agent era.</strong></p>
  5. <p align="center">
  6. <a href="https://github.com/PerpetualSoftware/pad/actions/workflows/ci.yml"><img src="https://github.com/PerpetualSoftware/pad/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  7. <a href="https://github.com/PerpetualSoftware/pad/releases"><img src="https://img.shields.io/github/v/release/PerpetualSoftware/pad" alt="Release"></a>
  8. <a href="https://goreportcard.com/report/github.com/PerpetualSoftware/pad"><img src="https://goreportcard.com/badge/github.com/PerpetualSoftware/pad" alt="Go Report Card"></a>
  9. <a href="https://github.com/PerpetualSoftware/pad/pkgs/container/pad"><img src="https://img.shields.io/badge/ghcr.io-perpetualsoftware%2Fpad-blue?logo=docker&logoColor=white" alt="Container image on GHCR"></a>
  10. <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License"></a>
  11. <a href="https://github.com/sponsors/xarmian"><img src="https://img.shields.io/github/sponsors/xarmian?label=sponsors&logo=github" alt="GitHub Sponsors"></a>
  12. </p>
  13. <p align="center">
  14. <a href="https://getpad.dev">Website</a>
  15. &nbsp;·&nbsp;
  16. <a href="https://getpad.dev/docs">Docs</a>
  17. &nbsp;·&nbsp;
  18. <a href="https://getpad.dev/blog">Blog</a>
  19. &nbsp;·&nbsp;
  20. <a href="https://getpad.dev/changelog">Changelog</a>
  21. &nbsp;·&nbsp;
  22. <a href="https://www.reddit.com/r/getpad/">Reddit</a>
  23. &nbsp;·&nbsp;
  24. <a href="https://x.com/getpaddev">X</a>
  25. &nbsp;·&nbsp;
  26. <a href="https://bsky.app/profile/getpaddev.bsky.social">Bluesky</a>
  27. </p>
  28. </p>
  29. ---
  30. > One binary. Local-first. No sign-up. 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](https://app.getpad.dev).
  31. <p align="center">
  32. <picture>
  33. <source media="(prefers-color-scheme: light)" srcset="docs/screenshots/dashboard-light.png" />
  34. <img src="docs/screenshots/dashboard.png" width="900" alt="Pad dashboard for a project called Atlas: active work cards, an active plan at 4 of 7 tasks done, collection summaries, and what needs attention next" />
  35. </picture>
  36. </p>
  37. ## Quick Start
  38. ```bash
  39. brew install PerpetualSoftware/tap/pad
  40. cd your-project
  41. pad init # configure, auth, workspace, AI skill — all in one
  42. pad server open # opens the web UI at localhost:7777
  43. ```
  44. `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).
  45. Then, in a fresh agent session in your project, say:
  46. ```
  47. /pad onboard
  48. ```
  49. 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."
  50. ## Why Pad?
  51. 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](https://app.getpad.dev) hosts the same product with sync, workspace invites, and role-based access. A self-hosted workspace moves there by export and import; see the [move-to-Cloud guide](https://app.getpad.dev/console/move-to-cloud).
  52. | | Pad | Linear / Jira | Notion |
  53. |---|---|---|---|
  54. | **Setup** | `pad init` | Create account, invite team, configure | Create account, pick template |
  55. | **AI agents** | Native `/pad` skill for 7+ tools | Third-party integrations | Third-party integrations |
  56. | **Data** | Local SQLite you own — or opt-in Pad Cloud | Their cloud | Their cloud |
  57. | **Offline** | Full functionality | Read-only cache at best | Limited |
  58. | **CLI** | First-class | Afterthought | None |
  59. | **Price** | Free, open source | Per-seat pricing | Per-seat pricing |
  60. ## Features
  61. ### For Developers
  62. **CLI that doesn't get in your way.** Create tasks, search items, check status — without leaving the terminal.
  63. ```bash
  64. pad item create task "Fix OAuth redirect" --priority high
  65. pad item create idea "Real-time collaboration" --category infrastructure
  66. pad item list tasks --status in-progress
  67. pad item search "authentication"
  68. pad project dashboard # Project dashboard
  69. pad project next # What should I work on?
  70. pad server info # How this client is connected to Pad
  71. ```
  72. **Web UI that stays out of your way.** A clean interface at `localhost:7777`, in dark and light themes, with:
  73. - **Board, list, and table views** — drag-and-drop between status columns
  74. - **Keyboard navigation** — `j`/`k` to move, `Enter` to open, `Esc` to go back, `Cmd+K` to search
  75. - **Rich text editor** — Tiptap-based with markdown and auto-save, and real-time co-editing
  76. - **Wiki-links** — type `[[Title]]` to link between items
  77. - **Real-time updates** — an agent creates a task in the terminal, it appears in the browser instantly
  78. - **History** — every change is versioned, with who made it: a person, or a named agent
  79. - **Dashboard** — active work, plan progress, what needs attention, and what to do next
  80. <p align="center">
  81. <picture>
  82. <source media="(prefers-color-scheme: light)" srcset="docs/screenshots/board-light.png" />
  83. <img src="docs/screenshots/board.png" width="900" alt="Pad tasks board: Open, In-Progress, Done and Cancelled columns of task cards, each showing priority and the plan it belongs to" />
  84. </picture>
  85. </p>
  86. ### For AI Agents
  87. **Using Claude Code? Install the Pad plugin.** It bundles the `/pad` skill, typed shortcuts (`/pad:status`, `/pad:capture`, `/pad:onboard`), live item notifications and a side panel (`/pad-pane`), and it updates itself:
  88. ```
  89. /plugin marketplace add PerpetualSoftware/pad
  90. /plugin install pad@pad
  91. ```
  92. In the Claude Desktop app's Code tab: **+ → Plugins**, add the marketplace `PerpetualSoftware/pad`, then install **pad**. Open the panel with `/pad-pane`. If nothing is set up yet, it walks you through connecting to Pad Cloud, installing Pad on this machine, or linking your own server. The panel needs Claude Code 2.1.287 or later; the skills work on any version.
  93. **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. Cursor, Codex, Windsurf, and OpenCode receive a compact dispatcher, reuse bootstrapped context within a conversation, and load detailed guidance by topic with `pad agent guide`, keeping routine turns small.
  94. ```bash
  95. pad agent install # Auto-detects your tools and installs the skill
  96. ```
  97. Works with **Claude Code**, **Cursor**, **Windsurf**, **Codex**, **OpenCode**, **GitHub Copilot**, **Amazon Q**, and **JetBrains Junie**.
  98. Then just talk to your project:
  99. ```
  100. > /pad what should I work on next?
  101. > /pad I finished the OAuth fix
  102. > /pad create a task to add rate limiting
  103. > /pad let's brainstorm about the API redesign
  104. ```
  105. **Conventions and playbooks** teach agents how your project works:
  106. - **Conventions** — trigger-based rules like "run tests before marking a task done" or "use conventional commits"
  107. - **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_slug` so users can invoke them directly: `/pad ship PLAN-42`, `/pad release 0.5.0`. Fresh `startup` workspaces ship a generic `ship` playbook out of the box.
  108. ```bash
  109. pad item create convention "Run tests before completing tasks" \
  110. --field trigger=on-task-complete \
  111. --field scope=all \
  112. --field priority=must
  113. ```
  114. 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.
  115. <p align="center">
  116. <picture>
  117. <source media="(prefers-color-scheme: light)" srcset="docs/screenshots/item-light.png" />
  118. <img src="docs/screenshots/item.png" width="900" alt="A task open beside the task list: its status, priority, effort and assignee, the plan it belongs to, and a body written by an agent, with a 2 of 4 checklist progress bar on its list row" />
  119. </picture>
  120. </p>
  121. **Name your agents.** An agent that identifies itself gets its name on its writes: in the activity feed, the dashboard, item timelines and the admin audit log. Pad takes the first of these it finds:
  122. ```bash
  123. pad session register --agent rook # 0. this session's registered name
  124. # 1. agent_name = "reviewer" in .pad.toml (per workspace, committed)
  125. export PAD_AGENT=reviewer # 2. per process
  126. # 3. otherwise the detected runtime, e.g. "claude-code"
  127. ```
  128. With none of these, the write is recorded as the person whose credentials it used. The name is self-declared, so it labels a trail rather than proving who acted; provenance surfaces show both, e.g. `reviewer (via Dana)`. `pad session list` shows which registered sessions on this machine are alive, and as which agent.
  129. **Onboard agents to a new codebase:**
  130. 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.
  131. ### Collections & Custom Fields
  132. Pad organizes work into **collections** — typed containers with structured fields.
  133. **Built-in collections:**
  134. | Collection | Purpose |
  135. |---|---|
  136. | **Tasks** | Work items with status, priority, assignee, effort, due date |
  137. | **Ideas** | Feature ideas with impact and category |
  138. | **Plans** | Project milestones with progress tracking |
  139. | **Docs** | Documentation, decisions, reference material |
  140. | **Conventions** | Project rules that guide agent behavior |
  141. | **Playbooks** | Multi-step workflows for agents to follow |
  142. **Create your own** with typed fields — select, text, date, number, url, relation, checkbox:
  143. ```bash
  144. pad collection create "Bug Reports" \
  145. --fields "severity:select:low,medium,high,critical; browser:text; reproducible:checkbox"
  146. ```
  147. Items get reference numbers automatically (`TASK-5`, `BUG-12`) and can be moved between collections with field migration.
  148. ## Installation
  149. ### Homebrew (macOS and Linux)
  150. ```bash
  151. brew install PerpetualSoftware/tap/pad
  152. ```
  153. ### Build from Source
  154. ```bash
  155. git clone https://github.com/PerpetualSoftware/pad
  156. cd pad
  157. make build
  158. cp pad ~/.local/bin/ # or /usr/local/bin/
  159. ```
  160. 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](#nix) section below.
  161. 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.
  162. ### Docker
  163. ```bash
  164. docker run -p 127.0.0.1:7777:7777 -v pad-data:/data ghcr.io/perpetualsoftware/pad
  165. ```
  166. This publishes Pad to `localhost:7777` on the host machine, which is the recommended default for local use.
  167. **Pin a version for anything you keep.** The untagged name is `latest`, which moves to each new stable release (never a release candidate) the next time the image is pulled. Name the release instead, as a bare version with no leading `v`, for example `ghcr.io/perpetualsoftware/pad:0.17.2`, and change the tag when you choose to upgrade. Every published image is multi-arch and cosign-signed.
  168. **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:
  169. ```bash
  170. docker logs <container> 2>&1 | grep -A6 'Pad first-run setup'
  171. # → http://<your-host>:7777/setup#token=<one-time-token>
  172. ```
  173. 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).
  174. **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:
  175. ```bash
  176. docker run -p 7777:7777 -v pad-data:/data ghcr.io/perpetualsoftware/pad
  177. ```
  178. Set `PUID` / `PGID` to match your host's file ownership: the entrypoint runs Pad as that user. The defaults, 99/100, are Unraid's `nobody:users`.
  179. For multi-instance deployments, Pad supports Postgres + Redis via `docker-compose.yml` — see [docs/deployment.md](docs/deployment.md) for the full setup. The compose file runs the released image; set `PAD_VERSION` in `.env` to pin it.
  180. ### Nix
  181. Run without installing:
  182. ```bash
  183. nix run github:PerpetualSoftware/pad
  184. ```
  185. Or install into your profile:
  186. ```bash
  187. nix profile install github:PerpetualSoftware/pad
  188. ```
  189. A flake devShell (Go, Node, and friends, pinned to the same versions CI uses) is also available for contributors:
  190. ```bash
  191. nix develop
  192. ```
  193. > A `nixpkgs` package (`nix-shell -p pad` / `environment.systemPackages`) is planned but not yet merged upstream. Until then, use the `github:PerpetualSoftware/pad` flake reference above.
  194. ### Binary Download
  195. Pre-built binaries for macOS, Linux, and Windows are available on the [releases page](https://github.com/PerpetualSoftware/pad/releases).
  196. ### Pad Cloud (hosted)
  197. Don't want to run anything? [Pad Cloud](https://app.getpad.dev/register) is the managed option — same product, same CLI, same `/pad` skill, free during beta. Sign up on the web, then connect a project directory:
  198. ```bash
  199. pad init --url https://app.getpad.dev --workspace my-workspace
  200. ```
  201. Self-hosting stays first-class: the binary is unchanged and no features are Cloud-only.
  202. ### Upgrading Pad
  203. 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).
  204. **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):
  205. ```
  206. database schema is newer than this pad binary: ... This almost always means the
  207. binary was DOWNGRADED (e.g. brew/docker rollback) ... Upgrade pad back to a build
  208. that includes those migrations, or re-run with `pad start --force`.
  209. ```
  210. 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.
  211. **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](docs/backup.md)). PostgreSQL instances are skipped here; use `pg_dump` or a provider snapshot before upgrading.
  212. Recommended upgrade flow:
  213. ```bash
  214. # 1. Back up first (SQLite shown; see docs/backup.md for Postgres)
  215. pad db backup -o pad-backup-$(date +%Y%m%d).db
  216. # 2. Stop the server, install the new binary, restart
  217. # (migrations + the pre-migration snapshot run automatically on start)
  218. brew upgrade pad # or: a new image tag (see Docker above), binary download, make install
  219. # 3. Confirm it's healthy
  220. pad --version
  221. curl -s localhost:7777/api/v1/health
  222. ```
  223. ## Getting Started
  224. ### 1. Set up Pad
  225. ```bash
  226. cd ~/projects/myapp
  227. pad init "My App"
  228. ```
  229. `pad init` is the smart entry point that handles everything in one command:
  230. - Configures this client's connection (local server, remote, or Docker)
  231. - Auto-starts the local server
  232. - Creates the first admin account on a fresh local install (Docker / remote hosts run `pad auth setup` on the server instead)
  233. - Logs you in if needed
  234. - Creates or links a workspace for the current directory (writes `.pad.toml`)
  235. - Installs the `/pad` skill for any AI tools detected in the project
  236. Run from your project root. Safe to re-run anytime — it skips finished steps and prints a status summary if nothing's needed.
  237. **Choose a template** with `--template`, or omit it for an interactive picker grouped by category (Software / People / …):
  238. ```bash
  239. pad workspace init --list-templates # See the full catalog grouped by category
  240. pad init "My App" --template scrum # Scrum-style with sprints
  241. pad init "My App" --template product # Product management focused
  242. pad init "My Hiring" --template hiring # Company-side: requisitions, candidates, interview loops, feedback
  243. pad init "Job Search" --template interviewing # Candidate-side: applications, interviews, companies, contacts
  244. pad init "My App" --template blank # Custom: system collections only — let /pad onboard build the rest
  245. ```
  246. 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`.
  247. ### 2. Start working
  248. ```bash
  249. # From the CLI
  250. pad item create task "Set up CI pipeline" --priority high
  251. pad item create idea "Add WebSocket support" --category infrastructure
  252. pad project dashboard
  253. # From the web UI
  254. pad server open # Opens localhost:7777 in your browser
  255. # From your AI agent
  256. # Just use /pad in Claude Code, Cursor, etc.
  257. ```
  258. ### 3. Teach your agents the rules
  259. In an agent session inside the workspace:
  260. ```
  261. /pad onboard
  262. ```
  263. The agent walks an interview, detects your tooling, and adapts the workspace's collections, conventions, roles, and playbooks. To browse the library directly:
  264. ```bash
  265. pad library list --type conventions # Pre-built conventions you can adopt
  266. pad library list --type playbooks # Pre-built multi-step workflows
  267. ```
  268. ### 4. Optional — connect a desktop AI app via MCP
  269. Pad ships an MCP (Model Context Protocol) server so Claude Desktop, Cursor,
  270. Windsurf, Claude Code, or Codex can manage items, plans, ideas, and dependencies
  271. as native tools, read workspace state by URL, and load multi-step workflows as
  272. prompts.
  273. ```bash
  274. pad mcp install claude-desktop # or: cursor, windsurf, claude-code, codex, --all
  275. # Restart the client; pad shows up as the "pad" MCP server.
  276. ```
  277. Cursor and Codex installations can opt into compact tool results:
  278. ```bash
  279. pad mcp install cursor --compact-results
  280. pad mcp install codex --compact-results
  281. ```
  282. Pad keeps the result channel each client currently exposes to its model: JSON
  283. text for Cursor and `structuredContent` for Codex. It removes the duplicate
  284. channel only from successful structured results; errors and one-channel results
  285. remain unchanged. Leave the flag off for other clients or compatibility testing.
  286. `pad mcp install` writes each client's native config: JSON `mcpServers` for
  287. Claude Desktop / Cursor / Windsurf, a **project-local `.mcp.json`** in the current
  288. directory for `claude-code`, and an `[mcp_servers.pad]` table in
  289. `~/.codex/config.toml` (TOML) for `codex`. Because Claude Code's config is
  290. project-scoped, it's install-on-request only — `--all` and `pad mcp status` cover
  291. the per-user clients (including Codex) and skip it.
  292. **Tool catalog (v0.120)** — eleven resource × action tools plus `pad_set_workspace`, and `pad_board` on remote HTTP with Apps enabled. Undeclared input keys are rejected with a structured error rather than silently dropped, and field values are typed against the collection schema on the server:
  293. | Tool | Actions |
  294. |---|---|
  295. | `pad_item` | `create`, `update`, `delete`, `get`, `list`, `move`, `restore`, `link`, `unlink`, `deps`, `context`, `star`, `unstar`, `starred`, `comment`, `list-comments`, `edit-comment`, `delete-comment`, `backlinks`, `bulk-update`, `note`, `decide`, `export`, `import`, `history`, `remind`, `ack-reminder`, `reminders`, `unremind`, `schedule`, `schedule-forecast`, `schedule-edit`, `schedule-resolve`, `schedule-reopen`, `schedule-renegotiate`, `schedule-link`, `schedule-unlink`, `schedule-move`, `schedule-gate`, `schedule-dismiss`, `schedule-delete`, `agenda`, `link-pr`, `unlink-pr`, `claim`, `release`, `patch` |
  296. | `pad_workspace` | `list`, `members`, `invite`, `storage`, `audit-log`, `create`, `claim`, `deleted`, `restore` |
  297. | `pad_collection` | `list`, `create`, `update`, `delete`, `list-archived`, `restore` |
  298. | `pad_project` | `dashboard`, `next`, `ready`, `stale`, `standup`, `changelog`, `report`, `activity`, `catch-up` |
  299. | `pad_role` | `list`, `create`, `update`, `delete` |
  300. | `pad_search` | `query` |
  301. | `pad_playbook` | `list`, `get`, `run`, `match` |
  302. | `pad_library` | `list`, `get`, `activate` |
  303. | `pad_attachment` | `list`, `show` |
  304. | `pad_board` | `show`, `changes` (remote HTTP with Apps only; read-only collection board) |
  305. | `pad_chat` | `list`, `inbox`, `show`, `send`, `delete`, `read` (global agent chat; excluded from ChatGPT) |
  306. | `pad_meta` | `server-info`, `version`, `tool-surface`, `bootstrap` |
  307. | `pad_set_workspace` | session-default workspace pinning (response embeds the bootstrap blob) |
  308. Plus resources at `pad://workspaces`, `pad://workspace/{ws}/dashboard`,
  309. `pad://workspace/{ws}/items`, `pad://workspace/{ws}/items/{ref}`,
  310. `pad://workspace/{ws}/collections`,
  311. `pad://workspace/{ws}/attachments/{id}` (bounded image bytes),
  312. `pad://workspace/{ws}/bootstrap`,
  313. and `pad://_meta/version`.
  314. **Stability contract.** The catalog is versioned
  315. (`tool_surface_version: "0.120"`) and advertised in the initialize handshake and at
  316. `pad://_meta/version`, so external agents can pin against it; the per-version
  317. changelog lives in [`internal/mcp/version.go`](internal/mcp/version.go). Errors
  318. come back as structured envelopes (`{error: {code, message, hint, ...}}`) from a
  319. closed code list in `internal/mcp/errors.go`. Branch on `code`, not message
  320. text, and treat `stored_state_unreadable` as STOP rather than retry.
  321. Full guide at [getpad.dev/mcp/local](https://getpad.dev/mcp/local) — install
  322. paths, action enums per tool, error taxonomy, troubleshooting.
  323. **On Pad Cloud?** Skip the install: add `https://mcp.getpad.dev` as a remote
  324. MCP server in Claude Desktop, Claude.ai, Cursor, or Windsurf and sign in with
  325. OAuth — same tool surface, no local binary. Setup guide at
  326. [getpad.dev/mcp/remote](https://getpad.dev/mcp/remote). ChatGPT connects
  327. through its own OAuth-only endpoint; see
  328. [getpad.dev/docs/mcp/chatgpt](https://getpad.dev/docs/mcp/chatgpt).
  329. **Self-hosting?** The same remote MCP endpoint is built in and off by default:
  330. an admin turns it on, with OAuth when its issuer URL is https and personal
  331. API tokens either way. See "MCP for agents (self-hosted)" in
  332. [docs/deployment.md](docs/deployment.md).
  333. ## CLI Reference
  334. ```
  335. pad auth configure Configure how this client connects to Pad
  336. pad auth setup Initialize the first admin account
  337. pad auth login Sign in
  338. pad auth whoami Show current user
  339. pad server start Start the Pad API server
  340. pad server stop Stop the Pad server
  341. pad server info Show client, connection, and local server status
  342. pad server open Open web UI in browser
  343. pad workspace init [name] Initialize workspace in current directory
  344. pad workspace link <workspace> Link current directory to an existing workspace
  345. pad workspace list List all workspaces
  346. pad workspace switch <workspace> Switch active workspace
  347. pad workspace context Show structured workspace context
  348. pad workspace context set --file X Update structured workspace context from JSON
  349. # Workspace onboarding: run `/pad onboard` from an agent session inside the workspace
  350. pad workspace members List workspace members
  351. pad workspace invite <email> Invite a workspace member
  352. pad workspace join <code> Accept an invitation
  353. pad workspace export Export workspace data
  354. pad workspace import <file> Import workspace data
  355. pad project dashboard Project dashboard
  356. pad project next Recommended next task
  357. pad project ready Query actionable next items
  358. pad project stale Query stalled or attention-worthy items
  359. pad project standup [--days N] Daily standup report
  360. pad project changelog [--days N] Release notes from completed items
  361. pad project catch-up Your catch-up digest (read-only; marking is web-only)
  362. pad project watch Real-time activity stream
  363. pad project reconcile Reconcile item and PR state
  364. pad item create <coll> "title" Create item (task, idea, plan, doc, ...)
  365. pad item list [collection] List items (filters: --status, --priority, --all)
  366. pad item show <ref> Show item detail
  367. pad item open <ref> Open item in web UI
  368. pad item update <ref> Update item fields
  369. pad item delete <ref> Delete item
  370. pad item move <ref> <collection> Move item between collections
  371. pad item edit <ref> [--force] Open item in $EDITOR (guarded save; see --help)
  372. pad item search "query" Full-text search across all items
  373. pad item comment <ref> "text" Add comment to an item (--stdin reads the text from stdin)
  374. pad item comments <ref> View item comments
  375. pad item note <ref> "summary" Append an implementation note to an item
  376. pad item decide <ref> "decision" Append a decision log entry to an item
  377. pad item block <src> <target> Create dependency
  378. pad item blocked-by <item> <blk> Mark item as blocked
  379. pad item deps <ref> Show dependencies
  380. pad item context <ref> [--intent X] One brief for working an item (conventions, parents, deps)
  381. pad item unblock <src> <target> Remove dependency
  382. pad item related <ref> Show direct relationships for an item
  383. pad item implemented-by <ref> Show incoming implementers for an item
  384. pad item claim <ref> Atomically claim an item for execution (--holder, --ttl; 409 names the live holder)
  385. pad item release <ref> Release your execution lease (idempotent)
  386. pad item bulk-update --status X Batch update multiple items
  387. pad collection list List collections with item counts
  388. pad collection create <name> Create a custom collection
  389. pad library list Browse convention and playbook library
  390. pad library activate <title> Activate a convention or playbook
  391. pad agent install [tool] Install /pad skill for AI coding tools
  392. pad agent guide [topic] Print one section of the canonical agent guide
  393. pad agent status Show supported tools and installation status
  394. pad agent update Update installed tool integrations
  395. pad github link [item-ref] Link current branch's PR to item
  396. pad github status [item-ref] Show PR status for linked items
  397. pad github unlink <item-ref> Remove PR link from item
  398. pad webhook list List workspace webhooks
  399. pad webhook create <url> Create webhook
  400. pad session register Record this session (harness pid + agent name) locally
  401. pad session list Registered sessions on this machine, with liveness
  402. pad session prune Remove records of sessions that are dead
  403. ```
  404. All commands accept `--format json` for machine-readable output and `--workspace` to target a specific workspace.
  405. ### Shell completion
  406. `pad` ships completion scripts for bash, zsh, fish, and PowerShell:
  407. ```bash
  408. # Bash — current session only
  409. source <(pad completion bash)
  410. # Bash — persistent
  411. pad completion bash > /etc/bash_completion.d/pad # Linux
  412. pad completion bash > $(brew --prefix)/etc/bash_completion.d/pad # macOS (Homebrew)
  413. # Zsh (make sure compinit runs in your ~/.zshrc)
  414. pad completion zsh > "${fpath[1]}/_pad"
  415. # Fish
  416. pad completion fish > ~/.config/fish/completions/pad.fish
  417. # PowerShell (append the output to your $PROFILE)
  418. pad completion powershell | Out-String | Invoke-Expression
  419. ```
  420. 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.
  421. ### Authentication
  422. 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:
  423. ```bash
  424. pad auth setup # Initialize the first admin account (server host, non-local mode)
  425. pad auth login # Sign in
  426. pad auth whoami # Show current user
  427. pad auth logout # Sign out
  428. ```
  429. 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`).
  430. #### Authenticating with an environment token
  431. 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`:
  432. ```bash
  433. PAD_TOKEN=pad_xxxxxxxx pad item list
  434. ```
  435. `PAD_TOKEN` takes precedence over credentials saved by `pad auth login`, like `gh`'s `GH_TOKEN`. It suits CI, scripts, and machines where several agents share one CLI install but should act as different Pad users: give each its own token in its environment. `pad auth whoami` reports the token's identity. `pad auth logout` signs out the stored session only; revoke an env token with `pad token revoke` or under **Settings → API tokens**.
  436. `PAD_TOKEN` is only sent to the server you chose: `--url`, `PAD_URL`, your config, or the default. A repository's `.pad.toml` can name a different server, and anyone can commit one, so the CLI does not send `PAD_TOKEN` to a server that only `.pad.toml` names. Requests there use the credential saved for that server, and the CLI prints one line saying so. To use the token with that server, set `PAD_URL` to it or pass `--url`.
  437. #### Managing API tokens from the CLI
  438. ```bash
  439. pad token create --name ci-agent # Mint a token (secret shown once)
  440. pad token create --name cursor --expires-in 30
  441. pad token list # Metadata only — never secrets
  442. pad token rotate <token-id> # New secret; the old one dies with the same write
  443. pad token revoke <token-id> # Immediate; the id must be exact
  444. ```
  445. 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. `rotate` keeps a token's metadata (name, scopes) and replaces its secret in place: the old secret stops working immediately — there is no grace window — so update whatever holds it before its next call, and use `--expires-in <days>` to set a new expiry (otherwise the original is preserved).
  446. **`create` and `rotate` need a login session; `list` and `revoke` do not.** A request authenticated by an API token (including a `pad_` token in `PAD_TOKEN`) is refused with `403 session_required`, because tokens a token mints would outlive its revocation. A browser session, a saved CLI login, or a `padsess_` token in `PAD_TOKEN` mints normally; on a headless machine, `pad auth login -i` prompts for email and password. `list` and `revoke` stay reachable by a token, since revoking is the response to a leaked one.
  447. ```bash
  448. pad workspace members # List workspace members
  449. pad workspace invite user@example.com
  450. pad workspace join <code>
  451. ```
  452. ### Decision provider (optional)
  453. Pad can ask a small classification model typed questions about your items, such as "does this need a human decision?", and use the answers in the dashboard and playbook routing. It is **off by default**, and off is not a degraded mode: with no provider configured, no decision job is queued and nothing is sent anywhere. The dashboard shows only its graph-derived attention entries, the decisions list is empty, and `playbook match` answers `404 decision_provider_unavailable`.
  454. **What uses it**
  455. - The dashboard's `attention` list gains `needs_human` entries. Its `blocked` entries always come from the dependency graph. An answer counts when it was computed from the item's *current* state, or while a re-ask of a changed item is still pending.
  456. - `pad playbook match -- "<text>"` (`pad_playbook action=match` over MCP) picks the active playbook that free text asks for. It answers `404 decision_provider_unavailable` with no provider, so callers fall back to slug or trigger routing.
  457. - `GET /workspaces/{ws}/items/{slug}/decisions` lists an item's latest answers.
  458. Answers are computed **asynchronously**. Creating, updating, restoring or moving an item, and creating, editing or deleting a comment on it, queues a job, and a server tick makes the provider call, so no write ever waits on the network. A re-ask within an hour of the item's last evaluation for a question set waits until that hour is up, so a burst of edits and comments costs at most one call an hour per set, not one per write. Only open items in non-system collections are asked about: a job owed for a closed item is dropped at the tick without a call.
  459. **Configure** (later sources win, per field): the config file, then the instance-admin setting (**Settings → Admin → Instance**), then the environment.
  460. | Environment | `~/.pad/config.toml` | Meaning |
  461. |---|---|---|
  462. | `PAD_DECISION_PROVIDER` | `decision_provider` | `typesafe` to enable; `none` (or unset) to disable |
  463. | `PAD_TYPESAFE_API_KEY` | `typesafe_api_key` | the provider key: never logged, and write-only on the admin page |
  464. | `PAD_DECISION_MODEL` | `decision_model` | model pin; defaults to `jev-1.13.0` (a fixed version, so stored answers stay comparable) |
  465. Because the environment overrides the admin setting, `PAD_DECISION_PROVIDER=none` is how an operator turns off a provider an admin enabled. On Pad Cloud, the environment is the only source. `pad server info` shows what the CLI host's config file and environment resolve to. It cannot see the admin setting, so it is not the server's full effective configuration.
  466. **What leaves the box.** Enabling it sends item content to `https://api.typesafe.ai/v1/systemone` (typesafe.ai's Jev). For an item question, that is the title, collection slug, field values, the body clipped to 16,000 characters, and the last 10 comments. For `playbook match`, it is the text you asked about plus the active playbooks' refs, titles, summaries and triggers. Nothing is sent until a provider is enabled. Disabling it takes effect without a restart: no new call starts, though a request already in flight may finish.
  467. ## Architecture
  468. ```
  469. ┌──────────────────────────────────────────────┐
  470. │ pad (single binary) │
  471. │ │
  472. │ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
  473. │ │ CLI │ │ REST │ │ Embedded │ │
  474. │ │ (Cobra) │ │ API │ │ Web UI │ │
  475. │ └────┬─────┘ └────┬─────┘ │ (SvelteKit)│ │
  476. │ │ HTTP │ └────────────┘ │
  477. │ └──────────────┤ │
  478. │ ┌─────▼─────┐ │
  479. │ │ SQLite │ │
  480. │ │ + FTS5 │ │
  481. │ └───────────┘ │
  482. └───────────────────────────────────────────────┘
  483. ```
  484. - **Go backend** — chi router, SQLite via [modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite) (pure Go, no CGO), FTS5 full-text search, SSE for real-time updates
  485. - **SvelteKit frontend** — Svelte 5, Tiptap editor, drag-and-drop, adapter-static, embedded via `go:embed`
  486. - **Single binary** — serves the API and web UI, runs on macOS, Linux, and Windows
  487. - **Workspace-per-project** — each project gets its own workspace linked by a `.pad.toml` file
  488. Self-hosted, all data lives in `~/.pad/pad.db`. Your data. Your machine. No telemetry, no sign-up — cloud only if you opt in.
  489. ## Community
  490. - **[r/getpad](https://www.reddit.com/r/getpad/)** — how-tos, roadmap discussion, and notes from the agents that run Pad's own workspaces
  491. - **[GitHub Issues](https://github.com/PerpetualSoftware/pad/issues)** — bugs and feature requests
  492. - **[X](https://x.com/getpaddev)** / **[Bluesky](https://bsky.app/profile/getpaddev.bsky.social)** — release announcements
  493. ## Contributing
  494. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development guide.
  495. ```bash
  496. make build # Build web UI + Go binary
  497. make test # Run Go tests
  498. make dev-web # SvelteKit dev server with hot reload
  499. make install # Build, install to ~/.local/bin, restart server
  500. ```
  501. ## Security
  502. See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
  503. **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:
  504. - **No consent, no stream.** Nothing streams and nothing listens — watches and pushes alike — until the session consents. At session start the plugin's mod records the session's presence and asks whether it has consented; a session that has not starts nothing and shows nothing (TASK-3513). `/pad:connect` arms the session locally and starts the monitor, which announces the armed state when its stream connects; `/pad:disconnect` withdraws; `/pad:status` reports the state. A repo can opt its sessions in at start with `push.auto_arm = true` in `.pad.toml` — an explicit file edit, never a machine-global default, and vetoable per user in `~/.pad/config.toml`.
  505. - **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.
  506. - **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.
  507. - **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.
  508. The plugin's Claude Code hooks report activity through `pad session activity`:
  509. the hook returns immediately and sends the report in a detached background
  510. process, so a prompt never waits on the network. `UserPromptSubmit` sets busy
  511. and `Stop` clears it. Client timestamps keep a late busy report from overwriting
  512. a newer idle report within a 10-second reorder window; larger gaps apply as
  513. clock steps. Claude Code fires no `Stop` when the user interrupts a turn
  514. with Esc, so an interrupted session reads busy until its record expires 30
  515. minutes after the prompt report reaches the server. Nothing refreshes the record
  516. mid-turn: a single turn longer than 30 minutes reads `online` or
  517. `connected_not_accepting` for the rest of the turn, according to its armed state.
  518. For `pad session activity`, argument errors, flag errors, configuration failures,
  519. network failures and spawn failures are silent and exit 0. `--help` prints help
  520. to stdout; the shipped hooks never pass it. An OS-level kill cannot be converted
  521. to exit 0. If session identity cannot be resolved within 500ms, that report is
  522. sent without a worker id and the server drops it with `400 invalid_worker_id`.
  523. The next prompt or stop retries resolution and corrects activity once identity
  524. resolves. The hooks discard output because `UserPromptSubmit` stdout reaches
  525. the model. Activity reporting does not change push consent.
  526. A hook running with a read-only API token cannot report activity and silently does nothing.
  527. ## License
  528. [Apache License 2.0](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.