claude-pa
Personal assistant for Obsidian-style vault management as a Claude Code plugin. Daily-note creation + carry-over, multi-pane terminal orchestration, cross-pane state IPC, live dashboard, end-of-day commit wrap, same-day session resume.
Status
v0.2.1 — Tim's own daily driver. Production-grade for his vault layout; friends should expect rough edges on first install and report them.
Requirements
-
Claude Code v2.1.141+ (plugin marketplace + namespaced skills + hooks/hooks.json).
-
macOS or Linux. Windows / PowerShell deferred to v0.3+.
-
bash 4+. macOS ships /bin/bash 3.2 — run brew install bash and ensure /opt/homebrew/bin is ahead of /usr/bin on PATH. The wizard and launcher are 3.2-compatible, but pa doctor flags this as a failure because the dispatcher relies on a few bash-4 idioms.
-
python 3.10+ (/usr/bin/python3 on modern macOS, apt install python3 on Linux).
-
Terminal backend — one of:
| Backend | Native? | Notes |
|---|
| WezTerm | yes | Full multi-pane orchestration + dashboard split. Tim's daily driver. |
| Kitty | yes | kitten @ remote control; needs allow_remote_control yes in config. |
| iTerm2 | yes | macOS only. Manual QA per CONTRIBUTING.md (auth prompt on first run). |
| tmux 3.0+ | fallback | Universal — covers Terminal.app, Ghostty, gnome-terminal, etc. |
Install
/plugin marketplace add timbartels/claude-pa
/plugin install claude-pa@claude-pa
pa init
pa init walks you through configuration: terminal backend (auto-detected), preset selection, vault + projects paths, then prints the ~/.claude/settings.json allow-rules snippet for manual paste. Re-run any time to tweak.
Updating
/plugin marketplace update claude-pa # refresh the catalog (git-pulls the marketplace clone)
/plugin # plugin manager → claude-pa → Update
Claude Code installs plugins in two stages, so a single command isn't enough:
- Marketplace clone (
~/.claude/plugins/marketplaces/claude-pa/) — a git checkout that advertises available versions. /plugin marketplace update pulls it.
- Cache install (
~/.claude/plugins/cache/claude-pa/claude-pa/<version>/) — the copy that actually runs. /plugin → Update installs the new version here and repoints the active pin in installed_plugins.json.
If pa still reports an old version after updating, the cache install didn't bump — re-open /plugin and confirm claude-pa shows the new version, then reload the session so the hooks and launcher pick it up.
Quick start
pa init # interactive wizard
pa doctor # confirm green
pa # bare launch — opens orchestrator session in your current terminal
Inside the session, the personal-assistant skill auto-runs the morning routine. Spawn project panes during the day with /claude-pa:spawn <repo>; end the day with /claude-pa:wrap.
Slash commands
Auto-discovered by Claude Code from commands/:
/claude-pa:morning — daily-note carry-over + PR enrichment + agenda question/claude-pa:wrap — EOD commit summary + feature-note reconciliation + pane shutdown/claude-pa:spawn <repo> [<prompt>] — open or activate a project pane/claude-pa:peek [<repo>] — cross-pane state read/claude-pa:status [<filter>] — feature notes by status
MCP server
The plugin registers an MCP stdio server (pa.mcp_server) exposing five tools — peek_pane, list_panes, aggregate_todos, current_state, dispatch_to_pane. Schema-validated; lets Claude drive PA without shell-parsing pa.sh output.
Presets
presets/obsidian-ce/ ships in v0.2.1 — full Obsidian + Compound Engineering workflow flavor. Pick it at pa init, or "start fresh" to answer every question. New presets are welcome via PR — see presets/README.md.
Privacy + data handling
- All state local-only. No network telemetry, no analytics, no opt-in metrics in v0.2.1.
- Vault contents never sent remotely. Any future remote feature would require an explicit opt-in + documented data flow.
- State files under
$XDG_DATA_HOME/claude-pa/state/ may contain prompt text + daily-note excerpts. Stored with mode 0600; the data dir is 0700.
pa uninstall wipes config + (optionally) data. The vault itself is never touched.
Known limitations (v0.2.1)
