Byte-for-byte preservation
Existing context files are preserved byte-for-byte.
Docs Install
Read the plan before anything is written.
This tool edits AGENTS.md and CLAUDE.md, and any careful reader stops right there. So the promises come first, the preview command comes second, and the write comes only after you have read its plan.
01 before the command
What it will never do to your repo
Six promises, enforced by the installer itself and covered by the test suite — not aspirations.
One managed block, nothing else
Existing AGENTS.md / CLAUDE.md content is preserved outside one clearly marked managed block — including file mode and CRLF line endings.
Review, never migrate
Unknown or overlapping memory — old status files, ADRs, lessons folders — is reviewed and classified, never migrated behind your back. project-context consolidate is that read-only sweep. It was called review until 0.8.0; review now names the standing report of what is waiting on a person.
Halt before harm
Malformed blocks, unsafe symlinks and non-UTF-8 instructions stop apply mode before any write.
Add-ons are opt-in, each
Optional tools need a separate, informed opt-in each. Nothing is a default checklist.
A small, inspectable footprint
19 files. One skill. Zero runtime dependencies — stdlib Python 3.10+. The installer itself is never copied into your repo.
02 the command
Dry-run first, apply second
The CLI is deterministic: the plan --dry-run prints is exactly what --apply will do, and running it twice changes nothing the second time.
1 · preview the exact file plan — nothing is written
scroll →
uvx --from git+https://github.com/monomind-ai-lab/project-context project-context init --target . --install-skills --dry-run
2 · apply the plan you just read
scroll →
uvx --from git+https://github.com/monomind-ai-lab/project-context project-context init --target . --install-skills --apply
prefer pipx · install once and the whole CLI stays on your path — init, update, record, capture, inspect, context, onboard, review, consolidate, doctor
scroll →
pipx install git+https://github.com/monomind-ai-lab/project-context && project-context init --target . --install-skills --dry-run
One question before anything else. The initializer asks whether the repository is brand-new or existing — because an existing project may already hold status files, ADRs or lessons that deserve review, and a brand-new one has nothing to review. It then adapts to software, document, research, writing, mixed or general work, proposes the profile and the exact file changes, and waits for approval.
Nothing in this repository ever reaches out to a Hub. There is no call home, no registration, no credential. Project Context is a complete, offline product on its own. Where an owner does run a Project Hub, the direction is one way by construction: what they send arrives as a pull request you review like any other, and you never gain — or need — access to theirs. What a Project Hub is →
03 per harness
How your agent finds it
Installation creates two complementary trigger paths, so no single harness is required: harnesses that support the Agent Skills convention discover the installed skill directly, and a managed block in the root agent instructions routes everything else. The block now opens by declaring itself managed and naming project-context update as the thing that rewrites it, so nobody edits it in good faith. This is the whole block, verbatim:
<!-- project-context:start -->
Project Context
Managed region. `project-context update` rewrites everything between these markers and nothing outside them — the rest of the file is yours. Leave both markers in place; a broken pair stops the update rather than being repaired.
Before substantial work, run `project-context context --task "<one line>"`, or read `project-context/NOW.md` and `project-context/PLAN.md` if the CLI is not available. Search `DECISIONS.md`, `LEARNINGS.md`, and `QUESTIONS.md` for constraints touching the files you are about to change.
At milestones and before ending, read `project-context/SKILL.md` and evaluate every trigger. Use `project-context record` to create decisions, questions, tasks, designs, and incidents; update existing records, `NOW.md`, and registries. Use `project-context capture` only when classification can wait; acknowledge when nothing fired.
When planning, read `project-context/blueprint/` first. `global/` and `blueprint/` are owner-authored and read-only; raise changes as questions.
<!-- project-context:end -->
everything outside these two markers is never touched — where install had to create the file, even the short header above the block sits outside them, yours to rewrite
| Environment | How the protocol reaches it |
|---|---|
| Claude Code | Discovers the installed skill through the pointer at .claude/skills/project-context/SKILL.md; the managed block in CLAUDE.md covers it too. |
| Cursor · Windsurf · Copilot Chat · Aider | Agent mode with repository access. The managed block in AGENTS.md and CLAUDE.md routes them into the record before substantial work. |
| Claude Desktop · ChatGPT | Filesystem, workspace or project access to the folder. The managed block applies, and the paste-in prompt below works with no tooling at all. |
| Any other agent | If it can read and write files in the project folder, it is supported — the managed block is the delivery path, and no launcher is required. |
04 zero tooling
No Python, no CLI — one prompt
Paste this into any AI agent that can read and edit the target folder. The agent asks the onboarding question, shows you the plan, and waits for approval — the same guarantees, delivered by the agent instead of the CLI.
Install Project Context in the current repository or project folder using https://github.com/monomind-ai-lab/project-context. Read and follow `skills/project-context-init/SKILL.md`, starting with its required onboarding question. Show me the proposed plan and wait for my approval before making changes.
05 verify
Prove it took
A read-only doctor checks the install end to end. It reports; it never rewrites. With pipx it is simply project-context doctor --target .
health check · read-only
scroll →
uvx --from git+https://github.com/monomind-ai-lab/project-context project-context doctor --target .
- required core files
- the installed version against the current release
- NOW.md freshness
- duplicate decision and learning IDs
- broken relative links
- reachability — something still delivers the protocol
The last check is the one that matters. A healthy result names the routes that carry the protocol into a session — the managed block, the harness pointer, any hooks. no-delivery-path is an error, because perfect files that nothing ever loads would otherwise report healthy.
06 stay current
Installed months ago? That is what update is for
init is create-only, so it upgrades nothing: a file already present is preserved, which is right for a record and wrong for an out-of-date copy of a script. update is the other half — and like everything else here, it is local only. Nothing in it reaches a network.
1 · the exact plan — nothing is written
scroll →
uvx --from git+https://github.com/monomind-ai-lab/project-context project-context update --target . --dry-run
2 · apply the plan you just read
scroll →
uvx --from git+https://github.com/monomind-ai-lab/project-context project-context update --target . --apply
- refreshes what the tool owns — the skill, its scripts, the managed blocks, the generated indexes
- creates a scaffold file your install predates; never touches a record that already exists
- verifies anything a Hub pushed against its stamp and reports — it never rewrites it
- runs the doctor at the end · running it twice changes nothing the second time
The doctor is what tells you an update is waiting. template-update-available is a warning, and its detail names both numbers and the command — installed X, available Y, run project-context update. There is one version number per product, read from its own VERSION file.
07 uninstall
Leaving is four deletions
There is no uninstall command because nothing needs one: everything the installer creates is a plain file in your repo. Removal is deleting them.
Delete the records
Remove the project-context/ directory. Consider keeping a copy first — it holds your project's decisions and learnings, not the tool's.
Delete the skill and its pointer
Remove .agents/skills/project-context/ and the pointer at .claude/skills/project-context/.
Remove the managed block
In AGENTS.md / CLAUDE.md, delete everything between <!-- project-context:start --> and <!-- project-context:end -->, markers included. The rest of the file was never touched.
If you opted into hooks
Remove the three Project Context hook entries from .claude/settings.json — two on SessionStart and one on Stop. They are the ones whose commands call context_packet.py or context_triggers.py; every other hook in the file is yours and was never ours. Hooks exist only if you explicitly opted in.
next
You have three core summaries. Now meet them.
The moment after install is where adoption is usually lost. The records page walks each file — what it answers, what does not belong in it, and what a good entry looks like next to a bad one.