Use cases
Three small Markdown records kept beside the work: the current state, the decisions that constrain what comes next, and the learnings that were verified. Coding, writing, research, planning — any project you run with agents. One project needs nothing but the folder it already has. Several projects can share one private Hub above them.
Project Context installs into the repository or project folder you already have. Coding, writing, research, planning — every project keeps the same three core summaries, with five writer-backed operational kinds when the work earns them.
Nothing about the record layers is specific to code. Coding, writing, research, planning — every project has a current state, decisions, and verified learnings; active work can also earn questions, tasks, designs, and incident records.
Project Context works with software, document, research, writing and mixed projects. The install asks which one this is and adapts the pipeline to it.
One folder beside the project's own materials, and a block in the file your agent already reads. That is the whole footprint.
Source files, chapters, sources, notes, plans, slides — whatever this particular project is made of. Project Context does not move or rewrite any of it.
Install creates whichever of the two is missing. That block is how the protocol reaches an agent at all.
Claude Code today, Codex tomorrow, a different machine next month. The record travels with the project rather than living in one vendor's memory store.
That is the whole system for one project. No Hub, no server, no database, no vector store, no account — and no command that reaches the network.
Four projects, four shapes of work, one record model. None of them needs anything beyond the folder it already lives in.
A session ends halfway through splitting the auth module. Days later the next agent — often a different agent entirely — opens the current-state record and finds what was decided, what already landed, and what is still open. It does not re-derive the plan from a diff, and it does not start a fourth parallel approach.
Long-form work is mostly continuity: what the reader already knows by chapter nine, which voice was agreed for the second act, the terminology call that has to hold across four hundred pages. Editorial decisions live as decisions with their reasoning, rather than as somebody's memory of a conversation in a chat window nobody can find.
Screening criteria were settled in March. The dataset was swapped in May for a reason nobody wrote down. Three different agents have since summarised the same twenty papers. The decision record holds why the inclusion criteria are what they are; the learnings record holds which extraction pass produced unusable output — so the next pass starts where the last one stopped.
Scope, constraints and the commitments made in week two are exactly the things that walk out of the door with whoever leaves. Held as records in the project folder, they survive a handover: the person who joins in month five, and the agent drafting the next update, can both see what was promised and on what basis.
Records go stale quietly, and a stale record is worse than none. A read-only doctor is what keeps the difference visible.
Markdown and Git are the whole storage contract. A project with no owner pushing to it simply has no global/ and no blueprint/, and everything on this tab still works offline. Project Hub is the other half of the pair and it is entirely optional — the next tab is for when you want it.
The managed instruction block, a harness pointer or a working hook must still deliver the protocol into a session. no-delivery-path is an error, because perfect files that nothing ever loads otherwise report healthy.
A decision pins its justification to path/to/file@commit. The doctor reports evidence-drift when that file has changed since — meaning the justification may no longer hold, and the decision is worth a second look before anyone builds on it. It is read-only, always: a doctor that edited your judgement would defeat the point of having one.
The evidence anchor. A decision pins its justification to a path at a commit, so a later session can check whether the reason still holds.
Version control is the best case, not a prerequisite. Without it, the tooling falls back to file-modification times to detect that work has landed since the context was last updated.
Without git you lose the commit-anchored evidence trail and the drift detection that depends on it. The records still work. The verification is weaker.
Each project keeps its own project-context/, exactly as on the first tab. What they share — the guardrails, the workflows, and the goal each project serves — belongs in one place rather than copied into four. The projects under one Hub need not be the same kind: a coding repository, a research folder, a manuscript and a planning folder sit side by side, because the records are the same either way.
Both halves are the same records under the same rules — one parser, one schema, one doctor, because a Hub is itself a Project Context install. Nothing moves between them except by a command the owner runs.
Both arrows start with the owner, from the Hub, and only in the direction their access already allows. Nothing in a project repository ever reaches out to a Hub: no call home, no registration, no credential.
You are working in one project, on the first tab's arrangement. An owner runs a Hub above it. Here is everything that is different for you.
global/ and blueprint/ show up inside your project-context/. They are the pushed set: authored elsewhere, copied in, and read-only here. The stamp lives in the marker and never in the file — a pushed file stays clean Markdown, while .project-context.json records its sha256, the source commit and the push time.
A push does not write to your default branch. It commits to a long-lived hub-sync branch and opens a pull request, so what an owner sends arrives as a change you review like any other. Repeated syncs stack commits on that one branch and update the same request rather than scattering branches. Nothing force-pushes, and nothing merges — merging stays with you.
If you disagree with something pushed to you, raise a question in your own project-context/, or run project-context capture --kind proposal. It reaches the owner the next time they pull, and it arrives with the project context that explains it. That is the only path back up — nothing in your repository ever contacts the Hub by itself.
Editing a pushed file does not win the argument, and it does not get overwritten either. The Hub recorded that file's hash, so the next push sees the change and refuses. One edited file is a conflict that stops the owner's entire push to your repository, naming your file and saying the place to change it is the Hub. So the edit just stops the sync — and the owner still never learns what you objected to.
A Hub is one private repository you make from the public scaffold and administer yourself. It is plain Markdown in Git: no database, no service to log into, no runtime dependency.
Identity, guardrails, workflows, goals and resources. You write them once, in global/, and push them into the projects that need them — rather than copying the same guardrail into four repositories and watching three of them drift.
projects/<id>/ holds that project's mark — remote, branch, visibility, who builds it — your summary of it, and the blueprint you author for it: EPIC.md, the goal the project serves, and ARCHITECTURE.md, the shape it has to keep.
pull copies each repository's plan, tasks, decisions, learnings, open questions, designs, and incidents into projects/<id>/pulled/, stamped with repository, branch, commit and time. You read them here, together, without cloning anything. It is also your inbox: a question or a proposal a builder raised arrives on this path, and nothing moves until you pull.
The Hub's IDENTITY.md never reaches a project repository, at any setting — a project may have collaborators outside your organisation, so identity stays with you. GOALS.md, RESOURCES.md, people/ and agents/ are opt-in per project rather than default. And owners_window/, where you write about what is coming, is never pushed anywhere at all.
It works the same whether that folder holds source files, a manuscript or a client engagement.
uvx --from git+https://github.com/monomind-ai-lab/project-context project-context init --target . --install-skills --apply
Clarity comes with context.