MCPcopy Create free account
hub / github.com/PerpetualSoftware/pad

github.com/PerpetualSoftware/pad

Chat with this repo
repository ↗ · DeepWiki ↗ · release v0.21.1 ↗ · + Follow · compare 15 versions
32,085 symbols 219,710 edges 4,127 files 16,578 documented · 52% ● updated 46d agov0.18.0-rc.3 · 2026-10-03★ 1864 open issues

Browse by type

⨍ Functions 28,840◇ Types & classes 3,245
What it actually does AI analysis from the code graph — generated when you open this
loading…
README


Pad

Project Management for the agent era.

<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>
<a href="https://github.com/PerpetualSoftware/pad/releases"><img src="https://img.shields.io/github/v/release/PerpetualSoftware/pad" alt="Release"></a>
<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>
<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>
<a href="https://github.com/PerpetualSoftware/pad/raw/v0.21.1/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License"></a>
<a href="https://github.com/sponsors/xarmian"><img src="https://img.shields.io/github/sponsors/xarmian?label=sponsors&logo=github" alt="GitHub Sponsors"></a>






<a href="https://getpad.dev">Website</a>
&nbsp;·&nbsp;
<a href="https://getpad.dev/docs">Docs</a>
&nbsp;·&nbsp;
<a href="https://getpad.dev/blog">Blog</a>
&nbsp;·&nbsp;
<a href="https://getpad.dev/changelog">Changelog</a>
&nbsp;·&nbsp;
<a href="https://www.reddit.com/r/getpad/">Reddit</a>
&nbsp;·&nbsp;
<a href="https://x.com/getpaddev">X</a>
&nbsp;·&nbsp;
<a href="https://bsky.app/profile/getpaddev.bsky.social">Bluesky</a>

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.

<img src="https://github.com/PerpetualSoftware/pad/raw/v0.21.1/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" />

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. A self-hosted workspace moves there by export and import; see the move-to-Cloud guide.

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 interface at localhost:7777, in dark and light themes, with:

  • Board, list, and table views — drag-and-drop between status columns
  • Keyboard navigation — j/k to move, Enter to open, Esc to go back, Cmd+K to search
  • Rich text editor — Tiptap-based with markdown and auto-save, and real-time co-editing
  • Wiki-links — type [[Title]] to link between items
  • Real-time updates — an agent creates a task in the terminal, it appears in the browser instantly
  • History — every change is versioned, with who made it: a person, or a named agent
  • Dashboard — active work, plan progress, what needs attention, and what to do next

    Pad tasks board: Open, In-Progress, Done and Cancelled columns of task cards, each showing priority and the plan it belongs to

For AI Agents

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:

/plugin marketplace add PerpetualSoftware/pad
/plugin install pad@pad

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.

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.

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

<img src="https://github.com/PerpetualSoftware/pad/raw/v0.21.1/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" />

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:

pad session register --agent rook   # 0. this session's registered name
# 1. agent_name = "reviewer" in .pad.toml (per workspace, committed)
export PAD_AGENT=reviewer           # 2. per process
# 3. otherwise the detected runtime, e.g. "claude-code"

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.

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.

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.

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

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.

For multi-instance deployments, Pad supports Postgres + Redis via docker-compose.yml — see docs/deployment.md for the full setup. The compose file runs the released image; set PAD_VERSION in .env to pin it.

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

Binary Download

Pre-built binaries for macOS, Linux, and Windows are available on the [releases page](https://github.com/Perp

Extension points exported contracts — how you extend this code

browse all types & interfaces →

Core symbols most depended-on inside this repo

browse all functions →

Shape

Function 23,145
Method 5,695
Struct 2,117
Interface 677
Class 326
TypeAlias 100
FuncType 25

Languages

Go76%
TypeScript24%
Python1%

Modules by API surface

web/src/lib/types/index.ts294 symbols
internal/cli/client.go275 symbols
internal/store/items.go169 symbols
internal/server/server.go114 symbols
internal/logging/redaction_followups_test.go107 symbols
cmd/pad/cmd_item.go92 symbols
plugin/hooks/register.js80 symbols
internal/store/items_test.go76 symbols
internal/store/dialect.go75 symbols
web/src/test/identityFenceAst.ts74 symbols
web/src/lib/components/common/Lightbox.svelte.test.ts73 symbols
web/src/lib/api/client.ts73 symbols

Dependencies from manifests, versioned

github.com/JohannesKaufmann/domv0.3.1 · 1×
github.com/araddon/dateparsev0.0.0-2021042916200 · 1×
github.com/asaskevich/govalidatorv0.0.0-2023030114320 · 1×
github.com/bahlo/generic-list-gov0.2.0 · 1×
github.com/beorn7/perksv1.0.1 · 1×
github.com/boombuler/barcodev1.0.1-0.20190219062 · 1×

Datastores touched

padDatabase · 1 repos
dbDatabase · 1 repos
dbnameDatabase · 1 repos
newdbDatabase · 1 repos

For agents

$ claude mcp add pad \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

Ask about this repo answers extend the page