Skip to content
Back to search

pjman

MarketplaceWorks with Claude CodeGitHub

The pjman adapter for Claude Code, loaded in place from this repository

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vinhvanvu--pjman/badge.svg)](/listings/vinhvanvu--pjman)

HTML

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

Install

Install instructions from the README

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

pjman needs git. The plugin needs [Claude Code](https://claude.com/claude-code).

With npm, on Node 24 or newer:

npm install -g @vinhvanvu/pjman

With Homebrew, which brings its own Node:

brew trust --formula vinhvanvu/pjman/pjman
brew install vinhvanvu/pjman/pjman

If the install stops, see [docs/install.md](docs/install.md).

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 · 14 lines
  1. {
  2. "name": "pjman",
  3. "owner": {
  4. "name": "Vinh Van Vu"
  5. },
  6. "description": "The pjman adapter for Claude Code, loaded in place from this repository",
  7. "plugins": [
  8. {
  9. "name": "pjman",
  10. "source": "./adapters/claude-code",
  11. "description": "Session records, context injection and observed edges for a pjman store"
  12. }
  13. ]
  14. }
README.md · README · 246 lines
  1. # pjman
  2. pjman is a command-line tool and a Claude Code plugin. It keeps a record of your product work in a store: Markdown files in a git repository on your machine.
  3. The agent reads the store at the start of each session and writes to it through the `pjman` command, so a new session starts from what earlier sessions recorded. A local dashboard shows the same files. pjman needs no account.
  4. The records link to each other, so the store is a graph. A change knows the part of the map it changes, the decisions made on it, and the tickets and sessions behind it. A capability knows the files of code that implement it. A person knows the accounts they hold, their stakes on the map and their parts in the work. The links also cross the tree drawn below: one file can implement several capabilities, and one session or ticket can belong to several changes. The store holds these records:
  5. ```text
  6. product pantry what you are building
  7. └─ feature shopping-list what it does for a person
  8. ├─ person ada tied to it as owner, a stake the nodes beneath inherit
  9. └─ capability share-a-list one behaviour of that feature
  10. ├─ source src/share/pdf.ts a file that implements it: a source of kind code
  11. └─ change list-as-pdf one unit of work: origin, intent, done when, plan
  12. ├─ decision page-size a choice: options, one recommended, accepted by you
  13. ├─ source ABC-1234 a ticket, PR or doc the work points at
  14. └─ session 2026-11-21 one agent run that worked on it
  15. ```
  16. Most state is derived from the records. A change becomes `planning` once its plan has a step and `active` once a step starts, and a capability is live once the change that adds it is done.
  17. The examples on this page follow one made-up product: `pantry`, a shopping list app.
  18. ## Install
  19. pjman needs git. The plugin needs [Claude Code](https://claude.com/claude-code).
  20. With npm, on Node 24 or newer:
  21. ```bash
  22. npm install -g @vinhvanvu/pjman
  23. ```
  24. With Homebrew, which brings its own Node:
  25. ```bash
  26. brew trust --formula vinhvanvu/pjman/pjman
  27. brew install vinhvanvu/pjman/pjman
  28. ```
  29. If the install stops, see [docs/install.md](docs/install.md).
  30. ## Set up a repository
  31. ```bash
  32. cd pantry
  33. pjman init
  34. ```
  35. Init creates your store, registers the repository as a project, installs the Claude Code plugin when `claude` is on your PATH, and starts the dashboard. Your repository is not changed. The store is a git repository of its own, and every write to it is a commit:
  36. ```text
  37. ~/.pjman/store/
  38. └─ products/pantry/
  39. ├─ product.md
  40. ├─ features/shopping-list/feature.md
  41. └─ changes/list-as-pdf/
  42. ├─ change.md
  43. └─ decisions/2026-11-21-page-size.md
  44. ```
  45. Init asks one question:
  46. ```text
  47. Should the first session propose a product map from this repository? [Y/n]
  48. ```
  49. A product map is a tree of what your product does: its features, and the distinct behaviours under each. Every piece of work names its place on it.
  50. ### If you say yes
  51. Run `claude` in the repository and ask for your first piece of work. The agent files it, then asks you three questions: who the product is for, what it does for them, and what is next for it. From your answers, your docs and your code, it proposes the whole map as one decision:
  52. ```text
  53. pantry
  54. ├─ shopping-list Keep a list of what to buy
  55. │ ├─ add-items Add an item by typing it or scanning its barcode
  56. │ └─ share-a-list Send a list to someone else
  57. ├─ recipes Turn a recipe into the items it needs
  58. └─ stores Sort a list by the aisles of your store
  59. ```
  60. Nothing is created until you accept it. A repository with no docs or code yet gets no proposal: its map grows as changes are filed.
  61. ### If you say no
  62. No map is proposed, and your requests are filed the same way. To turn the offer back on, run `pjman set project:pantry map=propose`.
  63. ## Ask for work
  64. Say what you want done:
  65. ```text
  66. you let me save my shopping list as a PDF
  67. agent filed change:list-as-pdf · changes feature:share-a-list · one change · later · no date
  68. ```
  69. For each request, the agent does three things:
  70. - **It checks for a duplicate.** If an open change already covers the request, it attaches yours to that change and files nothing new.
  71. - **It finds the place on the map.** The change names the most specific feature it adds, changes or removes.
  72. - **It files a change.** A change is one unit of work: where it came from in your words, what it is for, what done means, and a plan as steps.
  73. This is the change in the store, trimmed to its main fields:
  74. ```markdown
  75. ---
  76. name: List as PDF
  77. gist: A shopping list can be saved as a PDF
  78. status: planning
  79. features:
  80. - feature:pantry/share-a-list
  81. plan:
  82. - text: Render a list to a PDF page
  83. state: open
  84. - text: Add Save as PDF to the share menu
  85. state: open
  86. ---
  87. ## Origin
  88. > "let me save my shopping list as a PDF"
  89. ## Intent
  90. A person in a shop with no signal still has their list.
  91. ## Done when
  92. Save as PDF on any list downloads a file that shows every item on it.
  93. ```
  94. A ticket or a URL named in your request is linked to the change as a source. Each file the agent writes for the change is linked too.
  95. ## Pick the work up in any session
  96. Start a session on the change's branch, or name the change in your prompt. The session opens with the change's whole record: where it came from, what done means, every decision made, and the plan with the step the last session stopped on.
  97. When the agent needs what came before on that part of the product, it runs `pjman history`. That lists the earlier changes, their decisions and their sources, for a node of the map and each parent above it.
  98. When the agent reaches a choice that closes off options, it opens a decision with the options laid out and one recommended. It then works on what does not depend on the answer. Only a person can accept: the command refuses an acceptance from an agent.
  99. ```text
  100. Page size (decision:list-as-pdf/page-size)
  101. Question: Which page size does the PDF use?
  102. Options:
  103. - a4: Always A4
  104. - letter: Always US Letter
  105. - by-locale (accepted): US Letter in the US and Canada, A4 everywhere else
  106. Why by-locale: A list printed at home should fit the paper in the printer.
  107. Accepted by-locale by person:ada on 2026-11-21: by locale, and let me change it later
  108. ```
  109. A session that wrote code for the change stops where the record says it can: at a decision that waits on you, at a recorded blocker, at a status you set, or with every step done and the work committed for review. If the agent tries to stop anywhere else, the plugin sends it back once.
  110. ## Start from the code
  111. The record a session opens with lists the files of the capabilities the change names, so the agent reads those before it searches:
  112. ```text
  113. ## Code
  114. feature:share-a-list:
  115. - src/share/menu.ts (pinned)
  116. - src/share/pdf.ts (found)
  117. - src/share/ShareSheet.tsx (3×)
  118. - src/share/ShareSheet.test.tsx (2×)
  119. ```
  120. Each file is a source of kind `code`, linked to the capability it implements. Links are made in three ways:
  121. - **By you.** `pjman code link share-a-list src/share/menu.ts` pins a file. A pinned link stays until you take it off.
  122. - **By the agent.** When a search turns up a file that implements the capability, the agent links it, so the next session skips that search. When a listed path is gone, it moves the link to where the file went.
  123. - **By the merge.** When a change in review lands, its diff updates each capability the change names. `pjman merge` does this when it merges. A pull request merged on GitHub is found by `pjman sync git`, which runs after any agent turn that pulls, while the branch is still in your checkout. A renamed file's links follow it, and each touched file counts once more. A link no person made drops after five merged changes to its capability pass without touching it.
  124. The count after a file is how many merged changes to the capability touched it. `pjman validate` names any linked path that no longer exists. In a repository with history, `pjman code seed` gives each capability its first links from past commits that each name a single change and touch at most 15 files.
  125. ## People
  126. A person is a record that holds their role, the accounts they use (`github-user:ada`, `linear-user:ada`, `email:ada@example.com`) and their ties. A tie is a typed edge from the person: its type is the relationship. A tie to a node of the map is a stake, and every node beneath inherits it until a nearer node names its own. A tie to anything else is a part.
  127. ```text
  128. person:ada Ada · designer
  129. ├─ owner feature:shopping-list a stake on the map
  130. └─ author url:…/share-spec a part on a doc
  131. linear-user:ada her account, not a tie
  132. └─ assignee ABC-1234 a synced ticket names the account, which leads to her
  133. ```
  134. The agent keeps people from the conversation:
  135. - **A name.** When you mention someone, the agent looks for their record by an account, the handle, an alias or the full name, and creates one only when no one matches. A first name alone lists the people it could be, so two people are never merged on a name.
  136. - **A tie.** When you say who owns or wrote something ("Ada owns the shopping list"), the agent records the tie as said. A passing mention ties no one. `pjman tie person:ada owner feature:shopping-list` sets it yourself, and replaces what was said.
  137. - **An account.** A ticket synced from GitHub or Linear names its assignee and author. Each reaches its person through the account, and an account no one holds shows as itself.
  138. Two reads use them:
  139. ```bash
  140. pjman people change:list-as-pdf # who to tag on its pull request: stakes on what it changes, its ties, its tickets' people
  141. pjman people person:ada # her dossier: stakes, open changes she is on, tickets, decisions, last seen
  142. ```
  143. The dossier is read from the store each time it is asked for. It holds keys and titles, never the text of a message or a doc.
  144. ## Read the store
  145. Every record is a file you can open. Four commands read the store for you:
  146. ```bash
  147. pjman context # what is in flight
  148. pjman context change:list-as-pdf # one change in full
  149. pjman tree # the product map, with the state of each node
  150. pjman code shopping-list # the files beneath a part of the map, rolled up from its capabilities
  151. ```
  152. `pjman open` opens the dashboard, a local page that draws the same store: what needs you now, the product map, the milestones and the roadmap. You can accept a decision there too.
  153. ## Finish a change
  154. `pjman review change:list-as-pdf` prints what a reviewer judges the branch by: the change's intent, what done means, the decisions accepted on it, and its commits. `pjman merge change:list-as-pdf` lands the branch and sets the change done. It refuses while any finding of the review is still open: each is fixed on the branch, dismissed with the reason, or deferred by a person first.
  155. ### With Entire (opt-in)
  156. [Entire](https://entire.com) captures each agent session as a checkpoint on its commits, and runs review and merge through Trails. A project opts in with `pjman set project:pantry ext.entire.enabled=true`. `pjman doctor` names what the opt-in still needs.
  157. Opted in, three things change:
  158. - **Review.** `pjman review` files what it finds onto the change's Trail, and the Trail holds the merge until each finding is resolved.
  159. - **Merge.** `pjman merge` goes through the Trail's gates. pjman never forces a merge past a gate and never approves one.
  160. - **Why.** `pjman why <file>:<line>` reads a line back past its commit to the session that wrote it, its change and the decisions behind it.
  161. Without the opt-in, none of Entire's commands run, and review, merge and `pjman why` work locally.
  162. ## Docs
  163. - [Reference](docs/reference.md): the store, every command, the dashboard and its API, trackers.
  164. - [SCHEMA.md](SCHEMA.md): the record contract.
  165. - [Install](docs/install.md): Homebrew, upgrading, and what to do when an install is off.
  166. - [The Claude Code adapter](adapters/claude-code/README.md): the hooks and the skills.
  167. - [Hosts](adapters/hosts.md): the terminals a session can run in, and what each gives.
  168. ## License
  169. Apache License 2.0. See `LICENSE` and `NOTICE`.

Ratings and comments

Sign in to rate this skill.

Sign in

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