Casefile

Casefile

One case file per task — shared by every session, agent and person that touches it.

Casefile keeps a case file for every task: the decisions, failed attempts, findings and open questions that agents write down as they work.

When a session ends, the next one — the same agent, an agent from another vendor, or you — reads the latest summary and the open questions and carries on.

It is a self-hosted MCP server and a web board, MIT-licensed; it assigns and schedules nothing.

For anyone whose agents work on tasks longer than one session. Free to use. Made for Claude Code; Codex, Cursor and any other MCP client connect the same way.

Install on macOS / Linux

curl -fsSL https://raw.githubusercontent.com/azimov777/casefile/main/install.sh | sh

Install on Windows (PowerShell)

irm https://raw.githubusercontent.com/azimov777/casefile/main/install.ps1 | iex

All you need is Docker. The board opens at http://localhost:8080, and the installer connects Claude Code and Codex by itself — a plugin and an OAuth sign-in, no token to copy. Casefile updates itself to each new release: it checks once an hour and whenever Docker starts. A small updater service does it and holds the Docker socket for that; you can turn it off.

Or let your agent do it. Paste this into Claude Code, Codex or Cursor:

Install Casefile for me by following https://raw.githubusercontent.com/azimov777/casefile/main/docs/agent-install.md

Why

A session ends or the context fills up, and the next agent starts from scratch: re-reading the code, re-trying what already failed, re-asking what you already answered.

Casefile gives every task a case file — an append-only log the agent writes as it works.

• Hand-offs that survive a fresh context. The next agent reads the latest summary, the open questions and an index of the case, then carries on. No re-discovery.
• Built for agents, over MCP. Agents create and split tasks, record decisions and dead ends, ask you questions, and close with a verdict on every check.
• You stay in the loop. A live board and task pages show what every agent is doing. Answer questions, leave remarks and hand each agent its own access — right from the browser.
• Guardrails, not bureaucracy. No closing without a summary and a passed verdict per check; no starting a blocked task. Nothing else — no sprints, no estimates, no automation.
• Yours, on your machine. Runs locally in Docker and listens on localhost only. Nothing leaves your computer — unless you turn on sign-in and put it on your own server for your team (Network mode).

How it's different

• Not a notes file. A CLAUDE.md or handoff.md gets overwritten: the attempt that failed two days ago disappears, and two sessions edit the same file. A case file is append-only — a correction is a new entry that points at the old one. Keep CLAUDE.md for per-repo rules; Casefile is per task.
• Not a memory server. Memory MCPs recall facts by similarity. Casefile recalls nothing clever: it is a work log per task, read in a fixed order — card, latest summary, open questions, index, then only the entries you need.
• Not an issue tracker with MCP bolted on. An issue is a description and a thread anyone can edit. Case entries are typed and never edited, and the tracker refuses writes that would break the record.
• Not an orchestrator. It never starts agents, runs timers or moves tasks by itself. Handing out work and noticing a dead session stay with you and your agent harness.

Connect your agent

The installer connects Claude Code and Codex by itself. It installs the Casefile plugin — the skill and a connection to this installation's MCP address — and signs them in with OAuth: no token is copied and none lands in any file. If the installer had no terminal for the sign-in, it prints the commands; run them once:

claude mcp login plugin:casefile:casefile

codex mcp login casefile

The installer asks before it changes anything of another program. The plugin step edits files that are not Casefile's: Claude Code's ~/.claude/settings.json (one line, "autoUpdate": true, inside extraKnownMarketplaces.casefile), Codex's ~/.codex/config.toml, the manual MCP entries casefile and tracker that point at this installation, and ~/.agents/skills. It prints that list and asks [y/N] on your terminal (also under curl … | sh); N skips the whole plugin step, leaves those files alone and installs the service as usual. Before the first change to a file it saves a copy next to it — settings.json.casefile-bak, config.toml.casefile-bak, kept and never overwritten — and it writes only the line it needs, leaving the rest of the file as it was. The copy holds whatever the file held, a token of a manual entry the installer removes included: delete it when you no longer need it. These variables go in front of sh:

• CASEFILE_SKILL=0 skips the plugin step; CASEFILE_SKILL=1 answers the question in advance. Without a terminal (an agent, CI) nothing is asked and the step runs, as it does with 1.
• CASEFILE_PLUGIN_AUTOUPDATE=0 installs the Claude Code plugin without autoUpdate; update it yourself with claude plugin update casefile@casefile.

The same commands sign an agent in again after you disconnect it on the board's Access screen (in a Claude Code session, /mcp → casefile → Re-authenticate). On your own machine the sign-in needs no password: Claude Code acts as claude, Codex as codex.

The skill comes with the plugin. Connecting gives the agent the tools; the Casefile skill teaches it how to use them. The installer puts it into Claude Code, Codex, Hermes and other agents it finds on the machine, and prints one line per harness. An installation made before v0.8.0 has no skill and no plugin, and the hourly self-update does not add them: it updates only the service. Run the install line again, or install just the plugin and the skill without touching the service (add CASEFILE_URL= for a server that is not on this machine):

curl -fsSL https://raw.githubusercontent.com/azimov777/casefile/main/install.sh | CASEFILE_SKILL_ONLY=1 sh

How to check whether an agent has the skill, and the commands for each harness, are in step 4 of the agent guide.

Claude Desktop gets an extension for its chat. The chat of the Claude desktop app (macOS, Windows) does not load the Claude Code plugin; it gets Casefile from casefile.mcpb, attached to every release. The installer downloads and opens it when it finds Claude Desktop; by hand, double-click the file. It signs in with OAuth, needs no Node.js and works while the installation runs (details).

Hermes signs in with OAuth (auth: oauth in ~/.hermes/config.yaml; the installer prints the block; not yet checked against a real Hermes). Clients without OAuth use the agent key. Scripts and any client that cannot sign in with MCP OAuth connect over streamable HTTP at the MCP address with the agent key in a header. The installer prints the key in their blocks; read it again with docker compose run --rm --no-deps -T agent-token cat .secrets/agent-token in ~/casefile. Such a client that takes an mcpServers JSON uses this — with the key and, if your installer printed a different address, that address instead:

{

"mcpServers": { "casefile": { "type": "http", "url": "http://localhost:8100/mcp", "headers": { "Authorization": "Bearer " } } } }

Over stdio, as an alternative. Streamable HTTP above is the main way in. A client that can only launch a command and talk to it over stdin/stdout gets the same server that way: it starts a short-lived container of your installation, attached to the installation's database — same tools, same key, same case. There is no OAuth over stdio: the agent key goes in the client's environment, not on the command line:

claude mcp add --scope user casefile-stdio --env TRACKER_MCP_TOKEN=<token> -- \

docker compose -f ~/casefile/docker-compose.prod.yml run --rm --no-deps -T \ -e TRACKER_MCP_TOKEN mcp python -m app.mcp --stdio

The installation has to be up: the stdio process brings no database of its own. Each client session is a process of its own, so HTTP stays the lighter choice wherever the client supports it. An installation image older than the stdio mode answers unrecognized arguments: --stdio — update it first.

A second agent, without the terminal. Connect an agent on the board shows this installation's MCP address and ready-made snippets. Access lists every way in, in three sections: agent connections (OAuth sign-ins), agent keys and sign-in sessions — yours, or every one of the installation if you are an administrator: who it speaks for, who issued it and when it was last used. A connection is disconnected there and a key revoked. For a client without OAuth you register an agent, issue its own key there and copy the snippet with the key already in it — shown once. Give each agent its own sign-in or key and its case entries are signed with its name. On a shared installation every person does this for their own agents, without the administrator, and sees only the connections and keys they issued or that speak for them.

Tell it what to do

Connecting the agent is only the wiring. Once it is done, tell the agent these, word for word.

Have work to hand over? Say:

File tasks in Casefile for my work: a project for it if there is none yet, and tasks with all their sections and checks, each small enough for one agent to finish in one go, each naming its environment in context — where the work lives and how to check it is done. Don't start the work itself; if I haven't described it yet, ask me.

Then, in a new agent session, say:

Carry out the tasks for this work from the Casefile tracker. Hand them to agents, one task per agent, to save your own context, and give them cheaper models where those cope.

The two phrases go to different agent sessions: the second agent starts with a clean context and knows only what is in the task cases. The board carries the same phrases, with copy buttons, on its /start page.

Tools

Every MCP tool the server offers, grouped by area (app/mcp/tools/):

Tasks

• get_task — returns everything about one task in a single call: card, parent and children, links, computed features, latest summary, open questions, unresolved remarks, its discussions, case index and transition tar