pad CLAUDE.md

Pad — Development Guide

What This Is

Pad is a project management tool for developers and AI agents. Single Go binary with embedded SvelteKit web UI, SQLite storage, and multi-agent skill support (Claude Code, Cursor, Windsurf, Codex, OpenCode, Copilot, Amazon Q, Junie).

Related repo: The marketing website (getpad.dev) lives at ../pad-web — a separate SvelteKit site deployed to Vercel.

Architecture

• Backend: Go (cmd/pad/main.go) → REST API (internal/server/) → SQLite (internal/store/)
• Frontend: SvelteKit 2 + Svelte 5 (web/src/) → static build embedded in Go binary
• Data model: Workspaces → Collections (typed with JSON schemas) → Items (structured fields + rich content)
• CLI: Cobra commands in cmd/pad/main.go, HTTP client in internal/cli/
• Agent skill: Single natural-language /pad skill in skills/pad/SKILL.md

Build & Install

make build      # Build web UI + Go binary (./pad)
make install    # Build, kill server, install to ~/.local/bin/pad, restart
make build-go   # Build Go only (skip web — faster when only backend changes)
make test       # Run Go tests
make web        # Build web UI only
make dev-web    # Run SvelteKit dev server (hot reload on :5173)

After making changes, always run make install to rebuild the binary, install it, and restart the server. The web UI at http://localhost:7777 will reflect the changes.

Quick iteration loop

• Backend only: make install (skips web rebuild if no frontend changes — edit Makefile to use build-go instead of build in the install target)
• Frontend only: make web && make install or use make dev-web for hot reload during development
• Full rebuild: make install

Working in a git worktree

Agent sessions take a git worktree per task rather than sharing the main checkout (a shared checkout means a shared stash stack, branch state, and dirty files across sessions). Three rules keep web tooling working there:

• Symlinking web/node_modules to the main checkout's copy is fine (and fast). Vitest, vite build, and npm run check all work through the symlink.
• A fresh worktree has no web/.svelte-kit (gitignored, generated). Run npx svelte-kit sync in web/ before any vitest/vite command — or npm run check, which syncs first. Without it, vitest fails with Failed to load tsconfig '.svelte-kit/tsconfig.json': Tsconfig not found regardless of how node_modules was set up. (This missing generated dir was historically misdiagnosed as a symlink problem — npm ci "fixed" it only because its prepare script runs svelte-kit sync.)
• Never run npm ci in a worktree whose web/node_modules is a symlink — including via make. npm ci lives in the web target, so every target whose dependency chain reaches it is off-limits too: currently web, build, install, serve, web-check, and check (via web-check). Everything else — build-go, dev, restart, test, test-pg, lint, vuln, web-test, dev-web, clean — never reaches npm ci. npm ci deletes through the symlink into the shared tree, breaking every other worktree and session at once with a confusing vitest: not found. If you want a real, isolated node_modules instead of a symlink, npm ci in an un-symlinked web/ is ~5s on a warm cache and regenerates .svelte-kit as a side effect.