casefile

<div align="center">

# Casefile

**The task tracker your AI agents keep for each other.**

Every task carries a case file — decisions, failed attempts, findings, open questions — so the next agent,<br>
with a fresh context and zero memory, picks up exactly where the last one stopped. You watch it all on a live board.

[![CI](https://github.com/azimov777/casefile/actions/workflows/images.yml/badge.svg)](https://github.com/azimov777/casefile/actions/workflows/images.yml)
![MCP server](https://img.shields.io/badge/MCP-server-8A2BE2)
![Self-hosted](https://img.shields.io/badge/self--hosted-Docker-2496ED)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

</div>

**Install on macOS / Linux**

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

**Install on Windows (PowerShell)**

```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

<div align="center">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/demo-dark.gif">
  <img alt="An agent creates a task and works it over MCP — the board picks up the new card, follows it across statuses, and the task page shows the agent's own case entries, live and without a reload" src="docs/assets/demo-light.gif" width="900">
</picture>
</div>

## Why

Agents are smart, but they forget. A session ends or the context fills up, and the next one 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](#network-mode)).

<div align="center">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/question-dark.png">
  <img alt="A task waiting on a blocking question the agent asked the human" src="docs/assets/question-light.png" width="900">
</picture>
</div>

## Connect your agent

The installer prints a ready-made command with your token and its actual MCP address
filled in — by default:

```bash
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:

```json
{
  "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:

```bash
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.

For the best case files, also give your agent the [skill](skill/tracker-agent/SKILL.md) that teaches the discipline (Claude Code: `~/.claude/skills/tracker-agent/SKILL.md`).

## Tools

Every MCP tool a `task` or `main` token opens, grouped by area (`app/mcp/tools/`):

**Tasks**
- `get_task` — everything about a task in one call: card, links, computed flags, latest summary, open questions, unresolved remarks, case index and status transitions
- `search_tasks` — search tasks by a query-language string, by individual filters, or both combined
- `create_task` — create a task in `backlog`, where every new task starts
- `update_task` — update only the fields you pass; anything left out stays untouched
- `transition` — move a task to another status along the built-in transition table
- `close_task` — file entries, verdicts and the final summary, and move the task to `done` — all in one call and one transaction

**Case**
- `read_entries` — full bodies of case entries, with payload, in order
- `add_summary` — file a summary: a hand-off briefing for the case
- `add_entry` — file a plain entry: a decision, attempt, finding, artifact, remark or note
- `ask` — ask registered participants a question
- `answer` — answer a question filed on the same task
- `resolve` — resolve a remark on a task: how it turned out and where the follow-up work went
- `add_verdict` — file the outcome of one review check

**Links**
- `link` — link two tasks and file `link_added` in both their cases
- `unlink` — remove a link and file `link_removed` in both tasks' cases

**Queues & participants**
- `get_queue` — a queue with its description: the shared context for all its tasks
- `list_queues` — every queue in the installation: key and title
- `list_participants` — the participant registry — who a question can be addressed to
- `create_queue` — create a queue (requires the `main` token scope)
- `update_queue` — rename a queue or change its description (requires the `main` token scope)
- `register_participant` — register a person or a permanent agent (requires the `main` token scope)
- `update_participant` — change a participant's description (requires the `main` token scope)

**Journal**
- `wait_journal` — journal entries after a given sequence number, waiting for new ones if there aren't any yet

## Everyday

| | |
|---|---|
| Update right now | run the install line again |
| Turn auto-update off | `CASEFILE_AUTO_UPDATE=false` in `~/casefile/.env` |
| Stay on one release | `CASEFILE_VERSION=0.2.0` in `~/casefile/.env` |
| Stop / start | `docker compose stop` / `docker compose start` in `~/casefile` |
| Remove everything, data included | `docker compose down -v` in `~/casefile` |
| Move to another machine or your own server | [`docs/moving.md`](docs/moving.md) |
| Back up your data / restore into a clean install | [`docs/backup-restore.md`](docs/backup-restore.md) |

Ports and other settings live in `~/casefile/.env` — see [`.env.example`](.env.example).

### Updates

A new version of Casefile is a release: a git tag `vX.Y.Z` with its images on ghcr.io
under the version and under the `stable` channel. Every installation follows `stable`
by default. It checks when Docker starts and then once an hour, at a slightly random
minute, so a release reaches it within about an hour and ten minutes, with nothing to
restart. Commits to `main` without a tag never reach an installation. The update
recreates the Casefile containers and keeps your data in its volumes. An agent in the
middle of an MCP call when that happens gets a dropped connection and has to retry.

The first release on this channel is 0.2.0; until it is out, there is nothing to update
to. An installation from before it (on `latest`) moves to `stable` by itself the next
time Docker starts, and from then on checks every hour. If you set
`CASEFILE_VERSION=latest` in `.env` yourself, remove the line to follow releases.

`CASEFILE_UPDATE_INTERVAL` sets how often to check (hours, or `30m`; `0` means only
when Docker starts). If an update fails to start, `docker compose logs updater` names
the version to go back to.

## Network mode

Out of the box Casefile listens