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.
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
13 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 . --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 . --apply
prefer pipx · install once, keep init / inspect / review / doctor on your path
scroll →
pipx install git+https://github.com/monomind-ai-lab/project-context && project-context init --target . --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.
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. This is the whole block, verbatim:
<!-- project-context:start -->
Project Context
Before substantial repository work, read `project-context/SKILL.md` and `project-context/NOW.md`, then search `project-context/DECISIONS.md` and `project-context/LEARNINGS.md` for relevant constraints and evidence. Update project context at meaningful milestones and handoffs. Confirm important claims against the repository's primary artifacts and evidence. Treat generated indexes and wikis as auxiliary views, not authority.
<!-- project-context:end -->
everything outside these two markers is never touched
| 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 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
- installed scaffold version
- 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 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 two Project Context entries from .claude/settings.json — they are the ones whose commands call context_triggers.py. Hooks exist only if you explicitly opted in.
next
You have three new files. 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.