Install and update PHARN in any git project.
PHARN gets features shipped right with Claude Code. The spec, plan, and checks stay in plain files in Git, so months later you can answer "what was done and why?".
npx @pharn-dev/pharn@latest initWhat is PHARN? · Why use it? · Quick start · How it works · What gets installed · After install · Day-to-day workflow · CLI commands · Agent skills · Safety model · Current scope · Documentation · Development · Security · License
PHARN is a repo-local methodology for making AI-assisted development easier to review, repeat, and maintain. It gives Claude Code a structured path from feature intent to implementation review:
spec -> plan -> grill -> test -> build -> regress -> verify -> ship
The npm package, @pharn-dev/pharn, is the installer. It does not scaffold your app. It detects what kind
of project you already have, installs the matching PHARN capabilities from
pharn-dev/pharn-oss, and records the install in
pharn.config.json and pharn.records.json.
AI agents can move fast, but a fast diff without durable context is hard to trust. PHARN is built around a simple idea: the reasoning behind a change should be committed beside the change.
- Preserve intent. Specs, plans, constraints, and review notes live in the repository, not only in an agent transcript.
- Make work inspectable. PHARN installs grillers and lenses: pipeline checks and review perspectives that help interrogate a plan or diff before it ships.
- Keep updates safe.
pharn updateuses per-file hashes to avoid overwriting local edits unless you explicitly choose--force. - Stay tool-shaped, not service-shaped. The CLI fetches open content, copies files into your project, and leaves the state in version-controlled markdown and JSON.
Run PHARN inside an existing git project. For a new app, make sure it is a git repository first
(create-next-app already runs git init and commits, unless git is missing or you pass --disable-git):
npx create-next-app@latest my-app && cd my-app
[ -d .git ] || { git init && git add -A && git commit -m "init"; }
npx @pharn-dev/pharn@latest initThen open Claude Code and start with /pharn-spec, or run the whole chain with
/pharn-loop implement password reset with a one-time token. Either way the run begins at the spec:
/pharn-plan halts unless an Approved, un-drifted SPEC.md exists (walkthrough).
Your project needs a test runner with per-test results. The test stage writes each acceptance
criterion's test before any code exists and requires it to fail, so it needs a test script (plus
test:e2e or e2e for end-to-end criteria) whose reporter writes per-test JSON, named under
testResults in pharn.config.json. Without one, /pharn-test stops and asks, and /pharn-loop ends
with blocked: no-test-runner. A fresh create-next-app has no test script, so set the runner up
first, as its own increment (a SPEC with spec_kind: test-infra); see upstream's
Per-test results.
pharn init is archetype-driven. There is no stack questionnaire and no module catalog.
| Step | What happens |
|---|---|
| Detect | Reads package.json dependency names and a bounded, symlink-safe file-tree scan to classify the project as ssr, backend, spa, lib, or a combination (rules). |
| Fetch | Downloads the newest verified release of pharn-dev/pharn-oss (a tag created only after its post-merge CI passed). With none resolvable it exits 1 and names --ref main, never falling back to the tip (details). |
| Resolve | Selects capabilities whose applies value is universal or intersects your archetypes. Skipped capabilities are named with the reason. |
| Install | Copies the selected capabilities plus the fixed PHARN product surfaces into .claude/ and pharn/. |
| Record | Writes pharn.config.json and pharn.records.json so future updates can tell PHARN-owned files from local edits. |
Everything PHARN keeps in your project lives under .claude/ (commands, hooks, agents) and pharn/
(capabilities, contracts, core, floor checkers, the trusted docs, a LICENSE copy and the features README),
plus pharn.config.json and pharn.records.json at the root: commit both. The full table is in
Getting started: What you get. An existing .claude/settings.json
is never overwritten. As you run the workflow, PHARN writes one directory per increment,
pharn/features/<name>/, which is the durable record; commit it. pharn init and pharn update add
pharn/.run/ and pharn/.backup/ to your .gitignore (how).
Two version numbers, on purpose. The npm package @pharn-dev/pharn carries the installer's version.
The content it installs carries its own, recorded as skillsVersion in pharn.config.json and taken from
upstream's SKILLS_VERSION. They move independently, and pharn status / pharn update are keyed to the
latter.
- Hooks enforce only once they are registered in
.claude/settings.json. If your project already had that file, PHARN kept it and printed aHOOKSnote listing each hook it does not wire, as paste-ready JSON. Until you copy them across, the guarantees that depend on aPreToolUsehook are inactive, andpharn status --strictfails. /pharn-loophas aStopguard (require-loop-record.cjs) that also does nothing until it is registered underStop.pharn init,pharn statusandpharn updatename a missing entry.pharn updatenever edits.claude/settings.json, so copy new hook entries across by hand. Writes issued through Bash bypass the write guards entirely.
What the write guards allow and deny, and the full set of bounds, are in upstream's
README and
LIMITS.md.
Once PHARN is installed, use the slash commands from Claude Code. The pipeline is eight typed stages, each
reading what the previous one produced (what each does).
/pharn-ship runs the first seven in one pass and keeps both human gates: approve the spec before code is
written, decide merge/fix/abandon after verification. /pharn-loop runs the same chain unattended and
commits a green result to a new local branch (never pushed or merged), leaving the merge decision to you. Outside the pipeline,
/pharn-review runs the review lenses over any code, and /pharn-memory-promote promotes one lesson into
pharn/memory-bank/. /pharn-spec uses your own SPEC template if you put one at pharn/spec-template.md
(see upstream's Your own SPEC template).
| Command | Description |
|---|---|
pharn init |
Detect archetypes and install matching capabilities. This is also the default when no command is given. --dry-run prints what it would install and writes nothing (add --json for one machine-readable object); --yes/-y installs without prompts, but only when no file would be overwritten. |
pharn add [capability] |
Add one capability manually, for example a11y or lens:n-plus-one. With no argument, opens an interactive picker. |
pharn remove [capability] |
Remove one installed capability. With no argument, opens an interactive picker. |
pharn update |
Re-fetch and apply the latest PHARN content using drift-safe per-file decisions. --force overwrites files you changed; --yes/-y skips the confirmation prompt; --dry-run prints what it would do and writes nothing (add --json for the plan as one machine-readable object, and --compact to leave the unchanged files out of it). |
pharn list |
Show installed archetypes and capabilities. Use --json for machine-readable output. |
pharn status |
Read-only version and drift report. Use --strict to make drift fail CI, --no-drift to skip byte comparison, or --json for one machine-readable report. |
pharn uninstall |
Remove PHARN: deletes only the files pharn recorded and you did not change, then pharn.records.json and pharn.config.json (backed up first). Never touches pharn/.backup/ or a .claude/settings.json it did not create. --yes/-y skips the confirmation prompt. |
pharn --help |
Show every command, option and environment variable. pharn <command> --help shows one command and only the options it takes. |
pharn --version |
Show the installed CLI version. |
init also takes --archetype <list> (for example --archetype ssr,backend) to install for those
archetypes instead of the detected ones; the choice is recorded, so update keeps it.
If you script the CLI: an option a command does not take, or an extra positional, exits 1
(Unsupported option for `status`: "--force"); off a TTY a plain init, update or uninstall exits 1
(update --yes is the CI line; init --yes never confirms an overwrite; --dry-run needs no terminal);
and one writer at a time holds pharn/.lock, while list and status never take it, so
pharn status --strict stays runnable in CI. A config changed while a prompt was open refuses the write.
The pharn-dev/skills repository ships a pharn-cli skill that
operates this CLI for you: ask "Is PHARN up to date in this project?" or "What would an update change?" and
it runs the read-only checks and a --dry-run first, applies updates without overwriting your edits, and
adds or removes grillers and lenses. It also carries phargus skills for
Phargus. In Claude Code, run /plugin marketplace add pharn-dev/skills
then /plugin install pharn@pharn-dev, or use npx skills add pharn-dev/skills --skill pharn-cli. The skills
are optional.
PHARN is intentionally conservative about writes:
initchecks for existing install targets and asks before overwriting them, and refuses the whole install (writing nothing) when a destination path crosses a symlinked directory.updateusespharn.records.jsonto skip files it cannot prove are untouched. In your project it deletes only the directory of a capability it drops frompharn.config.json(PHARN runs whatever capability directories are on disk), after backing up any file in it thatpharncannot prove it wrote; it never touches.claude/settings.json. A re-runinitdoes the same, after listing those directories in its prompt. Every delete, and what is never deleted: What PHARN deletes.update --forcebacks up overwritten files underpharn/.backup/<timestamp>/before writing.adddoes the same for any destination file that differs from upstream, and refuses the whole install (writing nothing) when a destination path crosses a symlinked directory.statusandlistare read-only.removedeletes only the selected capability directory and prunes its records, after backing up topharn/.backup/<timestamp>/any file in it thatpharncannot prove it wrote unchanged; it never touchesCONSTITUTION.md,pharn/memory-bank/, or your detected archetypes, and refuses when that directory's path crosses a symlink.uninstalldeletes only files recorded inpharn.records.jsonthat still match their recorded hash, insidepharn's install paths; it keeps every file you changed or added and lists the ones it kept, backs uppharn.config.jsonbefore deleting it, never writes.claude/settings.json(it prints the hooks you need to unwire instead), and refuses (deleting nothing) without a usable record store.
PHARN can also refuse to install at all: if upstream declares a minimum CLI version newer than yours,
init/add/update stop with a named error before writing anything. Remote content is treated as
untrusted input. Capability names, copyable file names, versions, commit SHAs, and paths are validated
against strict allowlists; path traversal and symlink escapes are rejected; copied file contents are not
executed by the CLI.
- It targets Claude Code today. Codex and Cursor support are planned, not shipped.
- It requires a git-initialized project and Node >= 24.2.0, for the CLI and for the installed floor
checkers (
pharn/floor/*.mjs), which refuse to run on an older Node.pharn initandpharn updaterefuse up front on an older Node, with nothing written. - Archetype detection is JS/TS-shaped and bounded. A Python, Go, Rust, Ruby or PHP repo without a root
package.jsonresolves toliband gets the universal capabilities, a correct outcome;pharn init --archetypecorrects any misdetection. The rules: Detect archetypes. - It does not scaffold your app, install framework packages, or replace tests, review or release judgment.
- Supported installs: the current minor and the previous one. Re-run
pharn initon an older install; it keeps the capabilities you added.--jsonreports stay additive withinschemaVersion: 1. See the support policy and the roadmap.
Start here: docs/. Getting started · Commands · pharn.config.json · pharn.records.json · Support policy · Troubleshooting · Roadmap
npm install
npm run dev -- init
npm run build
npm run check # format:check, lint, lint:md, typecheck, testOther scripts: npm run test:coverage (the coverage gate CI runs) and npm run build:install-local (build
and install the local CLI into local test apps). Set PHARN_DEBUG=1 for verbose fetch and install errors;
NO_COLOR / FORCE_COLOR control colour (see Colour). See
CONTRIBUTING.md for contributor notes and release discipline.
The CLI has a small trust boundary: it downloads PHARN content from GitHub, validates and extracts it, then copies selected files into your project. The security-sensitive path validation, tar extraction, symlink handling, and update decision tables are covered by tests. Please report vulnerabilities through SECURITY.md, not public issues. The detailed model is in THREAT-MODEL.md and LIMITS.md.