For anyone whose agents work on tasks longer than one session. A self-hosted MCP server and a web board, free and MIT-licensed. 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 prints the one command that connects your agent. Casefile updates itself to each new release: it checks once an hour and whenever Docker starts.

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 prints a ready-made command with your token and its actual MCP address filled in — by default:

claude mcp add --transport http --scope user casefile http://localhost:8100/mcp \
  --header "Authorization: Bearer <token>"

Any other MCP client works the same way: streamable HTTP at the MCP address the installer printed (http://localhost:8100/mcp by default) with that header. Clients that take an mcpServers JSON (Cursor, VS Code and others) use this — fill in your token and, if your installer printed a different address, that address instead:

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

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 token, same case. The token 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. The board carries the same snippets. Connect an agent shows this installation's MCP address and ready-made snippets for Claude Code, Codex and any client that takes an mcpServers JSON — no secret on the screen, a placeholder where the token goes. Access lists your tokens — every token of the installation, if you are an administrator: who it speaks for, what it opens, who issued it and when it was last used. From there you register an agent, issue its own token, copy the snippet with the secret already in it — shown once — and revoke it when that agent is done. Give each agent a token of its own and its case entries are signed with its name instead of one shared agent. On a shared installation every person does this for their own agents, without the administrator, and sees and revokes only the tokens they issued or that speak for them.

Tools

Every MCP tool a task or main token opens, 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, case index and transition targets
• search_tasks — searches tasks by a query-language string, by separate conditions, or by both
• create_task — creates a task in backlog, optionally as a child of a parent task
• update_task — changes the given fields of a task; fields left out stay as they are
• transition — moves a task to another status along the fixed transition table
• close_task — closes a task: files entries, verdicts and the final summary and moves it to done, in one transaction
• move_task — moves a task, or each task of a list with an outcome per key, to another project with a reason; its previous key keeps leading to it (main token only)

Case

• read_entries — returns entry bodies of one task's case, with payload, in number order
• add_summary — files a summary: the handover note of a case, in four parts
• add_entry — files an entry without payload: a decision, attempt, finding, artifact, remark or note
• ask — files a question to registry participants
• answer — answers a question of the same task
• resolve — resolves a remark on a task: its outcome and where the work went
• add_verdict — files the outcome of one review check
• read_project_entries — returns entry bodies of one project's case, with payload, in number order
• add_project_entry — files a decision, finding, artifact or note in a project's case

Links

• link — links two tasks and files link_added in both cases
• unlink — removes a link and files link_removed in both cases