COAL
Pre-alphabeing built

Dig up what you built with AI.

COAL keeps a record of your work outside any one tool: what you meant to do, what got made, and what comes next. It is open source, it lives in a folder on your machine, and any AI tool that supports MCP (the Model Context Protocol) can read it.

Enter the mine Read the spec

We are building it in the open. A proof of concept runs the demo from a recorded Claude Code session, from capture to the resume line. There is nothing to install yet. The first release captures from Claude Code only, and anything else you add by hand.

Level 1−20 m

It's in one of those chats. Somewhere.

You use Claude, ChatGPT, Cursor and Claude Code in the same week. Each one makes things: an HTML page, a script, a plan, a decision. Each one forgets what you were doing when the session ends. The only index is which conversation it was in.

Level 2−90 m

Three things, kept outside any one tool.

For each thing you are working on, COAL keeps one record, called an Intent Manifest.

intent

The intent, in your words

The first thing you asked for becomes the summary. You search for it later the way you said it, not the way a model paraphrased it.

artifacts[]

The artifacts

Pages, scripts and docs, copied in and addressed by their SHA-256 hash, so the record survives a moved file or a deleted chat. Each one notes which tool and model made it.

state

The state

When you last touched it, the next step, and the questions still open. This is what lets the next session start where the last one stopped.

Level 3−180 m

It writes itself while you work.

Claude Code runs hooks at fixed points in a session. COAL listens to them. You do not fill in anything.

Claude Code is the only tool in the first release. Cursor, Codex CLI and Gemini CLI have hooks too, so each can get a small adapter that feeds the same capture contract.

Pages made in claude.ai or ChatGPT are not captured. In the first release you add them by hand with coal add. Importing session logs and chat exports is the first Phase 2 item.

  1. SessionStart

    COAL finds the record for this folder and puts the next step on screen.

  2. PostToolUse

    Claude writes budget.html. COAL registers it as an artifact. On the first write it creates the record, using your first message as the summary, and drops a small .coal marker in the project.

  3. Stop

    After each turn, COAL updates the last activity time and nothing else, so the hook stays quick.

  4. SessionEnd

    A job is queued and the hook returns at once. If Claude did not record the next step during the session, a background worker writes a short summary from the transcript.

Level 4−300 m

Find that thing you built, from any tool.

Any tool connected to the COAL MCP server can search the record and open what it finds. Ask Cursor for the budget tracker you built in Claude Code and you get the same record. coal find does the same from the terminal.

terminalMockup
$ coal find "budget"
ID        SUMMARY            STATUS  LAST   ARTIFACTS
019a3f2c  Household budget…  active  1 Nov  1
any MCP clientMockup
Find the budget thing I built
called coal_find({ query: "budget" })
Household budget tracker as a single HTML page
activeyour words1 artifact · budget.html
Last activity 1 Nov · Claude Code
Next: Add CSV export and a category edit dialog
Here it is. You last worked on it in Claude Code on 1 November and left off at CSV export. Want me to open it?
Level 5−450 m

Pick up where you left off.

Open a session in a folder that has a record and the next step is on screen before you type.

~/projects/budgetMockup
~/projects/budget $ coal resume

◆ COAL: Household budget tracker as a single HTML page. Next: Add CSV export and a category edit dialog. 1 open question.

● You left off at CSV export. The page renders categories and a transaction form, with no persistence yet. One open question: keep data in localStorage, or let you pick a JSON file?

  Continue with CSV export?

coal resume

Finds the record for this folder and starts Claude Code with the resume as the first turn. You type nothing and it opens with where you left off.

Plain claude

The COAL line with the next step shows before you type. Whatever you say first, the reply opens by offering to continue from it.

Level 6−650 m

The format is the product.

Each record is one JSON file in ~/.coal/manifests/. You can read it with cat. Any tool can write one. The Intent Manifest schema is open, and the v0.1 draft is published at coalmine.io/schema/intent-manifest/0.1.json.

~/.coal/manifests/019a3f2c….json (excerpt)
{
  "$schema": "https://coalmine.io/schema/intent-manifest/0.1.json",
  "version": "0.1",
  "id": "019a3f2c-8e4b-7d31-9a5c-2f6b1c8d4e70",
  "intent": {
    "summary": "Household budget tracker as a single HTML page",
    "source": "user"
  },
  "status": "active",
  "artifacts": [{
    "hash": "sha256:9f86d0…0a08",
    "title": "budget.html",
    "type": "html",
    "producer": { "tool": "claude-code" }
  }],
  "state": {
    "lastActivityAt": "2026-11-01T02:41:33Z",
    "nextStep": "Add CSV export and a category edit dialog",
    "openQuestions": ["localStorage or a JSON file?"]
  },
  "provenance": { "tool": "claude-code", "model": "claude-opus-5-5" },
  "contexts": [{ "kind": "path", "key": "/Users/you/projects/budget" }]
}
  • intent.sourceWho wrote the summary: you or a model. Search ranks your own words first.
  • artifacts[].hashSHA-256 of the copy in ~/.coal/artifacts/. The original path is kept too, but it can go stale.
  • state.nextStepThe line every resume starts from.
  • contexts[]Where this work lives. When a project has no .coal marker, SessionStart uses it to find the record.
  • provenanceWhich tool and model wrote the record. It never stores tokens or secrets.
Level 7−800 m

Nothing about it locks you in.

Every manifest is a JSON file and every artifact is a plain copy of the original, all under ~/.coal/. None of it needs COAL to open.

  1. Local first. Everything lives in ~/.coal/. No account. The only server is the daemon on your own machine.
  2. Files are the truth. Plain JSON is the record. The search index is SQLite and can be deleted and rebuilt from the files.
  3. Your words first. The summary is what you typed. A model can suggest a better one, but it goes in a separate field unless you say yes.
  4. No telemetry. No network calls you did not set up yourself. The daemon listens on 127.0.0.1 only.
  5. Never deletes. Remove means move to the trash folder. When git is installed, every change to a record is kept in its history.
  6. Open, all of it. Apache 2.0: the schema, the library, the CLI and every adapter. No paid tier.
Level 8−950 m

Four phases. Each starts only after a retro on the last.

Phase 1 is the MVP, about six weeks, and it ends with a week of real use. If COAL does not get used unprompted at least five times that week, the project stops there and the spec stays open.

Phase 1

Record

Capture from Claude Code, find from any MCP tool, resume in the next session.

In progress
Phase 2

Reach

Import from session logs and chat exports, adapters for Cursor and Codex, semantic search with a local model.

Next
Phase 3

Attention

Surface the right record at the right time, by rules you can read and edit.

Later
Phase 4

Portability

Spec v1.0 with a second implementer, encrypted sync between your devices.

Later
The seam−1000 m
The COAL logo: a lump of coal cracked open with a diamond inside

We are building it. Come join us.

A proof of concept on the poc/go branch, written in Go, runs the demo from a recorded Claude Code session: capture through the real hooks, find from the CLI and over MCP, the resume line at session start, and the web UI. It has not been run against a live session, it has no coal resume yet, and it does not build from a fresh clone. Read the spec, look through the code, and open an issue for anything that is wrong or unclear.

There are 9 diamonds in the walls on the way down.

Read the spec See the proof of concept How to help