- Scope:
globalorproject/<name>. - Project: name = basename of git repo root of cwd (main repo in a worktree). No
.pcmfile in project. - Section: user defined (e.g.
style,review). One folder per section. - Context: one md file. A section can have many contexts (e.g.
backend.md,ui.md). Many contexts can apply to one project. - Binaries:
pcm-server(API server, runs in background) andpcm(CLI client, calls API). - Home:
~/.pcm/holdsconfig.yaml,server.pid,server.log,index/(Bleve search index) andrepo/. Onlyrepo/is synced. - Repo: separate git repo. Default
~/.pcm/repo, user can select other path withpcm config set path <dir>. - First run: no init command. If repo folder is missing, pcm creates it and runs
git init -b main. Ifremoteis not set,pcm syncandpcm sync statusprint:info: remote not set, contexts are local only hint: pcm config set remote <git-url> && pcm sync - Layout:
<repo>/<scope>/<section>/<name>.md - Search: Bleve index in
~/.pcm/index/, cache only. md files are source of truth. Server updates it on context create and update. Rebuilt after any delete (context, section, project), after sync, onpcm index rebuild, and on server start if missing or schema changed (in background). - Sync: manual only. CLI
pcm syncor UI sync button. Server runs the git CLI (uses user's SSH agent,~/.ssh/config, credential helpers). Branchmain.git add -A, commitpcm sync: N files changedif changes.- No remote: stop. Else set
origin(add or set-url), fetch, rebase onorigin/main. - Conflict:
git rebase --abort, 409 with files. Fix by hand in repo, thenpcm sync. - Push if ahead (
-u origin main). Server readsremotefromconfig.yamlon each call: no restart needed. Timeouts: CLI health 2s, API calls 30s, sync 5m. Server finishes a sync even if the client disconnects.pcm sync statusbefore the first push:ahead= local commits, hintrun pcm sync to push.
- Claude Code: skill calls CLI. No MCP.
GET /health (root, not under /api/v1): health check.
| Method | Path | Purpose |
|---|---|---|
| GET | /projects |
List projects |
| POST | /projects |
Create project |
| GET | /projects/{project} |
Get project |
| DELETE | /projects/{project} |
Delete project |
| GET | /sections |
List sections |
| POST | /sections |
Create section |
| DELETE | /sections/{section} |
Delete section |
| GET | /contexts?scope=&project=§ion= |
List contexts with filters |
| GET | /contexts/{id} |
Read context (md + metadata) |
| POST | /contexts |
Create context |
| PUT | /contexts/{id} |
Update context |
| DELETE | /contexts/{id} |
Delete context |
| GET | /search?q=&scope=&project=&global=§ion=&limit= |
Full-text search (Bleve) in title, name, description, tags, content, section and project. Fuzzy, ranked, all scopes by default. project=X only X; project=X&global=true global + X. limit default 20, must be > 0. Query: words OR, +word must, -word must not, "phrase" exact. Hit: id, scope, project, section, name, title (name if none), description, snippet (HTML escaped, <mark>), score |
| POST | /index/rebuild |
Rebuild search index from md files |
| GET | /resolve?project=§ion= |
Merged global + project contexts with content. Project overrides global on same section/name. No project: global only |
| GET | /git/status |
branch, remote, changes (porcelain), ahead, behind (from last fetch) |
| POST | /git/sync |
Commit, pull --rebase, push. 409 {"error","files"} on conflict |
| GET | /git/log?n=10 |
Recent commits: hash, date, message |
| GET | /config |
Read config |
| PUT | /config |
Update config (remote URL, author) |
| GET | /* |
Embedded React app |
k8s style: pcm <verb> <resource> [name] [flags]. Output is a table. No short names.
| Command | Purpose |
|---|---|
pcm get context(s) [-s <section>] [-p <project>] |
Current contexts: project: line, then table SCOPE, NAME, SECTION, TITLE, DESCRIPTION, UPDATED. Global first, then project (-p or git repo). Project overrides global on same section/name. Not in git repo: global only |
pcm get context(s) -g [-s <section>] |
Global contexts only (no SCOPE column) |
pcm get context <name> -s <section> [-p <project> | -g] |
Print md file (frontmatter + content) |
pcm create context <name> -s <section> (-m <text> | -f <file|->) [--title] [--description] [--tag ...] [--force] [-p <project> | -g] |
Create context. --force replaces existing (PUT) |
pcm delete context <name> -s <section> [-p <project> | -g] |
Delete context |
pcm edit context <name> -s <section> |
Open in $EDITOR (later) |
pcm search <query> [-s <section>] [-p <project> | -g | --all] [--limit 20] |
Search contexts. No flag: global + git repo project; not in git repo: all. -p: global + project. -g: global only. --all: all. Table: SCOPE, NAME, SECTION, TITLE, SNIPPET, SCORE. Matches bold on a terminal |
pcm index rebuild |
Rebuild search index from md files |
pcm get contexts -o md [-s <section>] [-p <project> | -g] |
Merged global + project contexts as markdown (for skill). Not in git repo: global only |
pcm get project(s) [name] |
List projects or show one |
pcm create project <name> |
Create project |
pcm delete project <name> [--force] |
Delete project (--force if not empty) |
pcm get section(s) [-p <project> | -g] |
List sections in a scope |
pcm create section <name> [-p <project> | -g] |
Create section |
pcm delete section <name> [-p <project> | -g] [--force] |
Delete section (--force if not empty) |
pcm sync |
Commit, pull, push. Output: committed, pulled, pushed |
pcm sync status |
Branch, remote, changes, ahead, behind, changed files |
pcm sync log [-n 10] |
Recent commits (HASH, DATE, MESSAGE) |
pcm health |
Check server is reachable (text output, exit 1 if not) |
pcm --version, pcm-server --version |
Print <name> <version> (commit <sha>, built <date>). No server needed. Release builds set the values with ldflags (internal/version); local builds print dev |
pcm server start |
Start pcm-server in background (pid/log in ~/.pcm/) |
pcm server stop |
Stop background server |
pcm server status |
Show server health and pid |
pcm config get [key] |
Print all keys or one. Keys: path, remote, port, swagger |
pcm config set <key> <value> |
Write key to config.yaml. path / port / swagger: hint to restart server. swagger: true or false (default), serves API docs UI at /swagger/ |
Scope flags (like kubectl -n): -p <project> or -g (global). Both: error.
No flag: current project = main repo folder name: parent of git rev-parse --path-format=absolute --git-common-dir when it ends in .git (same for worktrees), else git rev-parse --show-toplevel. Normalized (My.Repo → my-repo). Needs git 2.31+.
- Not in git repo: error, hint
use -p <project> or -g. createauto-creates the current project.get/deletedo not.-p <project>never auto-creates (typo safety).
Source: internal/skill/SKILL.md, embedded in pcm with go:embed.
| Command | Purpose |
|---|---|
pcm skill install |
Write SKILL.md to ~/.claude/skills/pcm/ (overwrite) |
pcm skill uninstall |
Remove ~/.claude/skills/pcm/ |
pcm skill show |
Print SKILL.md |
Skill: start server if needed, load pcm get contexts -o md at start of coding task and before review, save with pcm create context when user asks to remember, dump session rules and decisions to a project context named after the PR title (fallback: branch, then a name the user approves) on request (user approves first; content written to a scratchpad file and saved with -f <file>; asks overwrite with --force or new name with -2 suffix), manage contexts on request. Before gh pr create: load contexts (and review section), check commit messages and branch name against the rules (reports only, never rewrites history), show title and body and wait for approval. allowed-tools: Bash(pcm:*), Bash(gh pr view:*), Bash(gh pr create:*), Bash(git branch:*), Bash(git log:*), Write.