ProjectKeeper

ProjectKeeper

AI writes code faster every week. Do you still know whether what it built is what you wanted?

ProjectKeeper puts what you asked for, the decisions you changed and the work the AI actually finished on one map, shows you where they part, and lets the next agent pick up where the last one stopped — even on a project left half-done. Your own agent takes the project over by reading it as it is and filling in one table; from then on a resident agent keeps the map current every day.

• Anchored to what you said. Your words are kept verbatim, with the session they were said in. Where a document has drifted from them, where something you wanted was dropped along the way, or where work grew that you never asked for, ProjectKeeper tells you.
• A half-done project, ready to hand over. Point it at the folder: documents, git history, code and agent sessions become one picture, and one command gives the next agent the context for the work it picks up.

English · 简体中文

One real project on one screen: what the owner asked for, the goals and product areas, two earlier plans, and the current plan's work. Every object opens to its sources.

Why

Let AI build a piece of software for long enough and you end up here: the conversations pile up, the plan keeps changing, and the agents have been swapped several times. Every agent says its task is done, yet nobody can say in full what was asked for at first, what changed later, and what was finally built. The answers exist — in documents, commit messages and session logs nobody will read again.

ProjectKeeper works like a project's archivist. It does not write code for the agents; it lines up every request, every change and the work actually finished. Where they do not match, it tells you; when the agent changes, it hands the whole story to the next one.

It is not too late to bring it in halfway: it goes through the sessions, documents and commits already there, and tells you what each version of the requirements was, what it was changed to, and which version is the one built. All of it happens on your machine.

What you get

• The whole project on one map. What you said you wanted, the goals, the product areas, the plans, and each piece of work in its place.
• What really happened to each piece of work. Its steps — dispatched, delivered, reviewed, fixed, merged — each with the commit, report or verdict it rests on, and marked Inferred where the Keeper inferred it.
• Where a decision came from. Your own words, quoted verbatim with the session they were said in, and the documents and commits that carried the decision on.
• What became of old plans. Every item of an earlier plan with what happened to it: carried on, moved, deferred or dropped.
• What needs you. Notes that ask for your decision and give options, and send-backs — a review that failed and nobody picked up — ready to copy to an agent.
• The right context for the next agent. One command gives an agent the pack for a work item: what it serves, how it got here, your project's rules, where the code is.

And it stays current: after the takeover, a round runs on the schedule you set, or when you press Follow up.

After one pass

The first pass reads the documents, the git history, the code structure and your agent sessions, and fills three views.

Graph: your words and the product on top, goals and areas across, earlier plans rolled up, the current plan's work in its cells.

List: one area opened. What was planned is on the left; what actually happened is on the right — in progress, merged in which commit, delivered with no check recorded.

Code: which code belongs to which product area, which pieces of work built it, how many tests it has, and whether the current plan still uses it.

Measured: this pass took about 50 minutes and about 11 CNY (about $1.5) on DeepSeek. The project is ProjectKeeper's own working repository: about 1,000 files of documents and code (some 470 Markdown documents and 400 source files, about 217,000 lines), about 750 commits and 22 agent sessions.

After a deepening

A deepening digs the history by question and checks its own work. On the same project it took another 71 minutes.

A piece of work with its steps under it — checked, dispatched, delivered, merged — and beside it the code it changed and the commits and review verdicts it came through.

Where a decision came from: an area's requirements, designs and decisions in one list, and for the one you click, when it was made and the commits that carried it.

What became of an old plan: every item of an earlier generation, struck through, with the current item that carried it on.

A note that needs you: the question, the Keeper's view, why it matters, three options with what follows from each, and the facts with their sources.

What each round used and which model carried which steps. The dollar figure is an estimate at list prices; the bill for this run was lower (see What a run costs).

From the map to one piece of work, to what happened to it, to the code it changed.

See it without a key

npm run demo

This builds an invented project — Papertrail, a one-person read-later list — already organized, and serves it at http://127.0.0.1:4880/. No key, no model, no network; the Keeper's answers in the demo are canned. Everything it writes goes into one folder in your temporary directory.

Four looks

The workbench comes in four themes; switch with Theme in the top bar. Here is the demo project in each.

Walnut Workshop — the default	Peacock & Brass
Warm Clay	Task Console

Factory in the same list is the plain built-in look, without a theme.

Quick start

You need Node.js 24 or later, and git, on Windows or macOS. On a Mac, git comes with the Xcode command line tools (xcode-select --install), and Homebrew's node is a newer Node than the 24 this is tested on: what a Mac needs.

git clone https://github.com/feiyanglyy-stack/ProjectKeeper.git && cd ProjectKeeper
npm ci
npm start

Or from npm, without a clone: npm install -g projectkeeper, then projectkeeper serve; where this page says npx pk, use projectkeeper.

Then take your project over, in one of two ways.

With your own agent (recommended). Claude Code, Codex or any agent you use reads the project and fills in the table:

npx pk takeover --project <your project folder> --prepare

This sets up three folders, each with its instructions, in ProjectKeeper's own folder, never in your project:

• one for the agent that reads your words in your past sessions;
• one for the agent that reads a copy of the project;
• one for the main agent that merges the two.

Run the three steps with your agent, then pk import, as printed, takes the table in. With Codex, --run codex in place of --prepare runs the three steps by themselves and takes the table in when it checks clean. Open http://127.0.0.1:4870/ to see it. How the agents fill the table: the template.

With the Keeper and your key. Open http://127.0.0.1:4870/, then four clicks:

1. Add project — a name and the folder of your project, typed or picked with Browse…. Nothing runs yet.
2. Add a key — on the Keeper page that opens, under Model provider: choose the provider, paste the key, Save.
3. Choose a depth — Full, Focused or First picture only.
4. Start.

The first picture comes first; the deepening follows if you chose one. Details: Getting started.

Either way, add a key for the daily upkeep: the Keeper uses it to carry the picture on as the project changes.

Models and keys

You bring your own key. The model library underneath (pi) lists some forty providers; the ones actually run so far are DeepSeek (deepseek-v4-pro, deepseek-flash) and Zhipu GLM (glm-5.3, glm-5.3-flash). A key you save stays on your machine, in ProjectKeeper's own folder, and is never shown again. Each step of a round can run on its own model, and backup keys take over when one runs out of quota: Models and keys.

Subscriptions: a Claude Pro or Max subscription cannot run the Keeper, because Anthropic allows that login only in Claude Code and on claude.ai; use an API key from the Claude Console. ChatGPT (Codex), Kimi Coding and GitHub Copilot subscriptions connect through pi's login, and none of them has been tested yet: Subscriptions.

What a run costs

A takeover by your own agent runs on that agent's subscription. On ProjectKeeper's own working repository, Codex took the three steps in about 27 minutes:

• the reader of the owner's words and the reader of the project ran side by side, in about 18 minutes;
• then the main agent took 8 minutes.

The table it filled has 75 things the owner wanted, 33 decisions plus 7 boundaries, 36 pieces of work and 18 places where the owner and the project part ways.

A daily follow-up runs on your key, and runs no model on a day with nothing new.

A takeover by the Keeper (the first pass and a full deepening) of the same project, measured four times:

Models	Time	Cost
DeepSeek: flash for everything, pro for the final check	126 min	29 CNY billed (about $4)
DeepSeek: pro as main agent and for the deepening's sub-agents, flash for the rest	122 min	57 CNY billed (about $8)
Zhipu GLM-5.3 as main agent, GLM-5.3-flash for the rest	198 min	$19 at list price
Zhipu GLM-5.3 for everything	200 min	$67 at list price

These are four runs on one project: a loose comparison, not a benchmark. The program changed between the runs (the GLM runs are the older ones), and the main agent of the all-flash run had read the previous run's list of faults in the project it was organizing.

• The first pass alone on DeepSeek: about 50 minutes and about 11 CNY with pro as main agent, or about 10 CNY all on flash.
• GLM on a Coding Plan subscription costs far less than the list price. In the maintainer's own terms: a GLM-5.3 first pass is about half of a junior team seat's 5-hour quota, a deepening about one 5-hour quota, a daily follow-up barely moves the quota, and an all-flash run about a third of one 5-hour quota.
• The Usage page is an estimate. It applies a list-price table to the recorded tokens; on the DeepSeek run with pro it showed $14.48 where the account was charged 57 CNY.

What each run got right and what it missed: Cost and quality.

What it does not do, and privacy

• It does not change your project's files. It writes to its own home folder (~/.projectkeeper). Inside your project it writes one folder of its own, and only after you authorize it.
• It listens on 127.0.0.1 only. No account, and no telemetry of its own.
• What leaves your machine is what goes to the model provider you chose: prompts that contain text from your project — documents, code, commit messages, and what you said in your agent sessions.
• It does not write code, run your tests or manage tickets. It reads, and tells you what it found, with the source of each statement.

More in Privacy.

For your agents: pk

Agents read the same picture through a command while the workbench is running. Two real outputs from the demo project, shortened where … stands:

$ pk context --work T-18
# Context for Incoming agent · Work: T-18 Search index incremental rebuild 增量重建 · Kind: Implement
…
## Owner's words
What the owner said that this work traces up to, word for word:
- `ow_save_fast` · the owner, 2026-09-09 [1]:
  “Saving has to be faster than deciding where it goes”
…
## Open problems
- The receipt claims a one-minute background refresh; the code does not have it.
- Is the one-minute refresh claim measured anywhere?
…

$ pk get sb_search_refresh
# Send-back · sb_search_refresh
Where: Search index incremental rebuild 增量重建 (thread_search_index)
What: Batch 2 says the index refreshes every minute; the review could not confirm it from the code, and batch 2 was signed off anyway.
Send back to: Work · Reopen T-18: make the index refresh in the background, or correct the receipt.
Status: Suggested · Open
…

For clients that take their tools over MCP (Claude Desktop, Cursor and others), pk mcp serves the same commands as a local MCP server: As an MCP server.

All of it, and how to run these against the demo: The pk command.

How it works

flowchart LR
  subgraph P["Your project, read as it is"]
    D["Documents and plans"]
    G["Git history"]
    C["Code"]
    S["Agent sessions"]
  end
  subgraph T["Takeover, by your own agent"]
    O["Your words, from the sessions"]
    R["The project, from a copy"]
    M["Main agent: merges, notes where they part"]
    O --> M
    R --> M
  end
  subgraph K["ProjectKeeper, on your machine"]
    L["Ledger: a program records what exists and when"]
    C2["pk check, pk import: the table against the project"]
    U["Daily upkeep: the Keeper carries the table on"]
  end
  P --> L
  P --> T
  M --> C2
  C2 --> U
  K --> W["The workbench in your browser"]
  K --> A["pk, for your agents"]

A program records what exists and when, without a model: every commit, document version, number and session. Your own agent then reads the project in its own way and fills in one table. The program checks the table against the project — every id, every source, every quote word for word — and draws it. From then on the Keeper carries the same table on as the project changes, through the same check. What a program can count or check, the program does; the models' attention goes to judgement.

The Keeper can also take a project over itself, in rounds, with your key. More: How the Keeper works.

How it compares

Tools that draw a graph of code structure, such as Understand-Anything, show how the code hangs together; ProjectKeeper's map is of intent and work — what was wanted, planned and done — with the code attached to the product areas it serves. Session-memory tools such as claude-mem capture what agents do from the day you install them; ProjectKeeper takes over what already exists, history included. Spec and task tools such as OpenSpec or Backlog.md work when you and your agents write in their format; ProjectKeeper asks you to write nothing new. It reads what the project already has and keeps it for a person to browse and for agents to query.

Status and limits

• v1.0. It makes mistakes, and it differs from run to run; every statement links to its source so you can check it. The measured runs, and what each missed, are in Cost and quality.
• Windows and macOS. ProjectKeeper was built on Windows and is used there every day. It runs on macOS too: its test suite passes there on GitHub's runners, but it has not yet had daily use on a Mac, so expect rough edges — a report of what it did on yours is welcome. Linux is not supported yet.
• Names on a Mac. Two names that differ only in case, or only in the Unicode form of an accented, Korean or Japanese character, are one name to ProjectKeeper, as they are to a Mac's usual volume. On a volume formatted case-sensitive, two files named that way would be taken for one.
• A project at a very long path. Files deep inside a project are read at any length. The project's own path is limited on Windows, and neither git's long-path setting nor Windows' own lifts the limit: at more than 246 characters git cannot open the repository (the files are read without their history, and Project scope says so), and at more than 251 the Keeper cannot work in the directory. Move such a project to a shorter path.
• It reads sessions from Claude Code and Codex. Other agents' sessions are not read yet.
• The interface is English; the content is in your project's language. The screenshots are from a Chinese-language project.
• The name. ProjectKeeper was developed under the working name ContextKeeper, and the screenshots show it organizing its own project, which carries that name.

Documentation

Getting started · Concepts · Models and keys · How the Keeper works · Cost and quality · The pk command · Privacy · FAQ · Architecture

Contributing

Issues and pull requests are welcome: CONTRIBUTING.md. Changes are listed in CHANGELOG.md.

Licence

MIT — see LICENSE. The themes under ui/themes/ are not covered by it: ui/themes/LICENSE.md. Third-party material: THIRD_PARTY_NOTICES.md.

Built with Claude Code.