Worktrail
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Worktrail show my open threads and what's next"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Worktrail
A record of what an AI coding agent did, kept so the next session does not have to guess from the code.
Worktrail is an MCP server and a small local window. While Claude Code or Codex works in your repository, it records the work as threads: what the thread is for, what was decided and what it was decided from, what is still open, and what comes next. The next session, another agent, or you picks up from that record instead of re-reading the diff.
Demo (read-only, a fictional team): https://casebook-api.syncflo.cloud/demo/en/ · Korean
Request access to the hosted server: https://casebook-api.syncflo.cloud/join (Google sign-in; a handful of seats, first come)
Feedback: GitHub Issues
What gets recorded
Every thread keeps four kinds of things apart, because they are overturned by different things:
Focus — what this thread is for and what would finish it.
Decisions and constraints — choices the work follows from now on, with the reason and who made them (you or the agent). They are superseded, never edited.
Evidence — what the machine or you actually said, byte-exact: a test result, an error, a diff. Never paraphrased.
Notes — what the agent observed and concluded at each step, and next: whose turn it is and what happens next.
The screen shows a thread as three lines a person can read without opening anything: how far it got, what is next, and why. The rules behind that are enforced by the server rather than by the agent's memory: a thread needs a topic, a next needs an owner, the first line of everything is a title (at most 120 columns, no record numbers in it), and evidence is cited by number instead of being pasted into prose.
Related MCP server: MCP Memory Keeper
Hosts
Claude Code — with session hooks, your open threads appear when a session starts.
Codex CLI — registered with
codex mcp add; say "show my open Worktrail threads" once when you start.claude.ai — as a connector, signed in with OAuth (hosted server only).
Works on macOS, Linux and WSL. On Windows, use the hosted server: paste the instructions the sign-up page gives you (windows.md) into your coding agent, and it does the install. Keeping records only on your machine needs WSL, because the installer and the launcher are sh scripts.
Install
Claude Code plugin
Claude Code users can install it as a plugin.
/plugin marketplace add jasonethicseo/worktrail
/plugin install worktrail@worktrailOn macOS and Linux it needs Python 3.11 or newer, or uv. (Windows: follow the existing instructions)
To get new versions automatically, turn on auto-update.
If you already installed it with the install line, installing the plugin cleans up the old registration and hooks automatically.
Install line
The easy way is the hosted server. Sign in at https://casebook-api.syncflo.cloud/join, read the data notice, and paste the one install line it gives you into a terminal. That line installs the client, registers the MCP server with whichever agents it finds, and installs the hooks. Afterwards casebook-ui opens the window and casebook-login signs you in from a terminal.
Two things worth knowing:
The MCP server is registered under the name
casebook. That is its original name, kept so that nothing already installed breaks. Say "casebook" to your agent.The installer asks where records live: on the hosted server, or only on your machine. During the test period the hosted server is recommended — fixes reach you without reinstalling, and the author can see what breaks. What is stored, who can read it, and how to delete it is written on the sign-up page.
From source (records stay on your machine)
git clone https://github.com/jasonethicseo/worktrail.git && cd worktrail
python3 -m venv .venv && .venv/bin/pip install -e ".[mcp]"
mkdir -p ~/.casebook && echo local > ~/.casebook/mode # records in a local sqlite file, no server
# Claude Code
claude mcp add casebook -s user -- $PWD/.venv/bin/python -m casebook.adapters.mcp_proxy
sh tools/hooks/install_claude_hooks.sh # optional: session-start and post-commit hooks
# Codex CLI
codex mcp add casebook -- $PWD/.venv/bin/python -m casebook.adapters.mcp_proxy
sh tools/hooks/install_codex_hooks.sh # prompt hook: keeps your words verbatim; Codex asks you to trust it once
.venv/bin/python -m casebook.adapters.ui_server # the windowLayout
casebook/core— the record: threads, turns, evidence, decisions, the first-line rules.casebook/adapters— the doors:mcp_server(stdio and HTTP),mcp_proxy(thin client),http_api,ui_server(the window),device_login,client_dist(what the install line delivers).web/worktrail— the screen.web/join— the sign-up page.tools/hooks— Claude Code and git hooks.tools/demo_*— the demo's fictional records.tests— run with.venv/bin/python -m pytest -q.
License
Functional Source License 1.1, Apache 2.0 Future License (FSL-1.1-ALv2, the license Sentry uses). You may use, copy, modify and redistribute it for any purpose except a competing product or service. Two years after each version is released, that version becomes Apache 2.0. GitHub lists it as "Other" because it is source-available rather than open source.
Available Tools
30 toolsadd_evidenceB
Store raw material VERBATIM as evidence: logs, error output, command results, config. Do not paraphrase or trim. Returns the evidence number.
Inputs: text (required), case_id (required), client. Returns: result
add_evidence_fileA
Store a file's contents as evidence, read directly by the server (no need to repeat the text). Use for log files, command output saved to a file, configs. A document you keep rewriting (Q&A notes, analysis, design .md) is not evidence: reference its path instead, and when the engineer adds to it, add_evidence only the new part, verbatim — never store the whole file again. Absolute or ~ path. Not available over the remote door (chat clients) — use add_evidence.
Inputs: path (required), case_id (required). Returns: result
add_utteranceA
Chat clients only (no prompt hook — if the engineer's prompt came with a line 'casebook source_ref: ', use that id instead). When the engineer's words ground a record (a decision or constraint with authority='user', a focus with authority='user', a note with observed_from='user'), paste their message here EXACTLY as they wrote it: first person, every character, no summary, no trimming, never your own words. Returns the id to pass in source_refs. Stored as pasted by you (origin: model_pasted), so a reader can tell it apart from a hook-captured prompt.
Inputs: text (required), client, capture. Returns: result
assign_topicA
Put threads under a topic for the engineer's Review (retrospective) screen — a topic is a line of work spanning threads and repositories (e.g. 'MCP for code agents', 'incident lab'). name finds or creates the topic; case_ids are added (idempotent). repos = repository identities whose pre-thread git commits belong to this topic. conclusion = one sentence to pin on the topic when the engineer wraps it up (a topic's phase is derived; only the conclusion is written by hand). Use it only when the engineer names the topic or a new thread clearly continues one. FIRST LINE = TITLE: at most 120 columns (CJK counts as 2), no ' — ' joiner, and no record numbers (#517, D15635, 확장 122호, turn 80, commit hashes) — a person reads that line on the screen; put the rest after a blank line as the body. The paragraph right under the title is read on the screen too, so no record numbers there either; they go in a later paragraph or evidence_ids (the server refuses otherwise).
Inputs: name (required), case_ids (required), repos, summary, +1 more. Returns: result
close_threadA
Close a thread (status resolved) and release every worktree bound to it. result = one sentence saying what came of it — it becomes the thread's closing line in Worktrail's Status screen and the retrospective. Also fills the result line of a thread the engineer already closed from the screen (needs_result in list_threads) — appended as a new ledger event, never an edit. Closed threads stay searchable; reopen from the screen or via set_status, then switch_thread to it. FIRST LINE = TITLE: at most 120 columns (CJK counts as 2), no ' — ' joiner, and no record numbers (#517, D15635, 확장 122호, turn 80, commit hashes) — a person reads that line on the screen; put the rest after a blank line as the body. The paragraph right under the title is read on the screen too, so no record numbers there either; they go in a later paragraph or evidence_ids (the server refuses otherwise).
Inputs: case_id (required), result.
constrainA
Record a constraint the work must respect (e.g. 'existing API contract must not break'). authority='user' or 'agent'. scope='thread' (default) or 'repo' (holds for every thread of this repository). Change later with supersedes=. source_refs = the prompt id(s) it comes from (the id from the prompt's "casebook source_ref: " line, or on a chat client the id add_utterance returns. Required with authority='user'.) FIRST LINE = TITLE: at most 120 columns (CJK counts as 2), no ' — ' joiner, and no record numbers (#517, D15635, 확장 122호, turn 80, commit hashes) — a person reads that line on the screen; put the rest after a blank line as the body. The paragraph right under the title is read on the screen too, so no record numbers there either; they go in a later paragraph or evidence_ids (the server refuses otherwise). reason follows the same first-line rule.
Inputs: case_id (required), statement (required), scope, reason, +4 more. Returns: result
decideA
Record a decision the work will follow from now on — a choice, not a truth (e.g. 'use a separate auth_credentials table'). authority='user' if the engineer stated it, 'agent' if you made it while implementing. To change it later, decide again with supersedes=. scope='thread' (default: archived with this thread) or 'repo' (holds for every thread of this repository — promotion is by declaring the scope, never automatic). Not for hypotheses about causes — those stay in note_turn. source_refs = the prompt id(s) the decision comes from (the id from the prompt's "casebook source_ref: " line, or on a chat client the id add_utterance returns. Required with authority='user'.) FIRST LINE = TITLE: at most 120 columns (CJK counts as 2), no ' — ' joiner, and no record numbers (#517, D15635, 확장 122호, turn 80, commit hashes) — a person reads that line on the screen; put the rest after a blank line as the body. The paragraph right under the title is read on the screen too, so no record numbers there either; they go in a later paragraph or evidence_ids (the server refuses otherwise). reason follows the same first-line rule — its first line is what the thread card shows as the reason. A decision changes what happens next: next (required) and owner (required) = what happens next after this and whose turn it is — "user", "watch" or an agent name; a next owned by the user is written TO the engineer.
Inputs: case_id (required), statement (required), next, owner, +8 more. Returns: result
declareA
Declare the thread's current focus (what it is for), open (what is still unresolved: questions, blockers, uncertainty) or next (the 1–3 concrete actions to take next). kind = focus|open|next. focus says what the thread is FOR and what would finish it — not how far along you are. In the body, explain first — what the thread does and what would finish it — and put where it came from (the engineer's words, quoted) last, as its grounds: the screen shows the body in order, so a quote first hides the focus. Re-declaring it with exactly the same words is a confirmation (it resets the turn cap and is not shown as a change); re-declare with different words only when the direction itself changed — then pass next and owner too (what happens next in the new direction, and whose turn); a confirmation takes neither. Append-only: the previous declaration of that kind is superseded, not edited. next REQUIRES owner — whose turn it is: "user" (the engineer must act), "watch" (nothing to do — observing only), or an agent name such as "codex" / "claude". It IS the thread's phase in Worktrail, and it is not carried over: a new next declaration without it is refused. A next owned by the user is written TO the engineer ('Decide X'), never about them ('The user decides X'). Declare open and next before pausing, switching, or when the engineer's direction changes; resume shows them as the starting point. source_refs = the prompt id(s) a declaration comes from (the id from the prompt's "casebook source_ref: " line, or on a chat client the id add_utterance returns. Required for a focus with authority='user'.) FIRST LINE = TITLE: at most 120 columns (CJK counts as 2), no ' — ' joiner, and no record numbers (#517, D15635, 확장 122호, turn 80, commit hashes) — a person reads that line on the screen; put the rest after a blank line as the body. The paragraph right under the title is read on the screen too, so no record numbers there either; they go in a later paragraph or evidence_ids (the server refuses otherwise).
Inputs: kind (required), case_id (required), statement (required), next, +4 more. Returns: result
defineA
Give a coined name its meaning — a term the work uses that a reader who was not there would not know (e.g. '1층 조리법', '3회차', 'blinding'). term = the name as written (≤40 chars); meaning = one line (≤120 columns), details after a blank line. scope 'thread' (default) or 'repo' (every thread of the repository). Not enforced: use it when the engineer asks what a name meant or asks you to tidy up, or when you coin a name inside a record. Superseded (supersedes=), never edited. resume and the screens show current terms; the Find screen shows first use.
Inputs: term (required), case_id (required), meaning (required), scope, +2 more. Returns: result
findA
Pull past context across every thread when you need it: decisions, constraints, ruled-outs, focus/open/next declarations, notes and close results whose text contains every word of query — one line each with its number (ref) and thread, in-force before superseded, newest first; evidence hits fill the remaining room. Use it when the engineer refers to something from before ('the one we rejected', 'why did we…') or you need a record's number. Notes are marked interpretation, not evidence. Then trail(case_id) or inspect(ref).
Inputs: query (required), limit, include_closed.
handoffA
Read the declared state, decisions, constraints and evidence references as a handoff, FOR THE ENGINEER. Requires engineer_asked=true, which you may pass only when they actually asked for a summary, a handover, or where the case stands. Never call it to refresh your own memory — use resume for that.
Inputs: case_id (required), engineer_asked. Returns: result
hookA
For the Claude Code hook script only (thin client) — not for agents. event = session-start | post-compact | post-commit | checkpoint; facts = git facts of the worktree read on the client (threads.local_facts). Returns the hook's JSON output.
Inputs: event (required), facts (required), why, reason.
import_priorB
For the casebook backfill script only (thin client) — not for agents. Imports pre-install session logs as repository history: verbatim engineer instructions only, no threads, topics, decisions or constraints are created from them.
Inputs: facts (required), sessions (required), reset.
inspectA
Return one record in full by its number (ref), as find, trail and resume print it: D decision · C constraint · R ruled-out · T term · F/O/N focus/open/next declaration (with what superseded it, if anything) · E evidence verbatim with provenance · : a note (what the agent observed and concluded, marked interpretation, with the evidence it cites). evidence_id= still works for evidence. Not summarized.
Inputs: ref, evidence_id.
list_casesA
List the engineer's recent cases (id, title, status, current focus) — to find the case to continue.
Inputs: limit.
list_threadsA
This worktree's current thread and the threads of its repository, one line each (open first, most recent activity first): title (the focus's first line), turns, updated_at, and for open threads the declared next's first line with its owner. Closed threads are only counted (closed.count, closed.needs_result) unless include_closed=true. needs_result means the engineer closed it from the screen without a result line; when they ask you to tidy up, call list_threads(include_closed=true), read each thread marked needs_result and fill it with close_thread(case_id, result). For one thread's full state use resume(case_id). Call it (or resume) first in a session, before any other work — always when the host has no session-start hook (e.g. Codex); pass worktree (absolute path) when you are not in the server's cwd. From a chat client (no repository) it also lists open work across all repositories.
Inputs: facts, worktree, include_closed.
list_topicsA
List the engineer's topics — id, name, summary, the threads under each, and the conclusion if pinned. Read-only. Use it to see what overlaps before the engineer decides what to merge, or to pick an existing topic name.
Inputs: no named parameters.
merge_topicA
Merge one topic into another, FOR THE ENGINEER: every thread under topic moves to into (its assignment time kept), repositories are united, into keeps its own summary and conclusion, and topic is deleted. Thread records are untouched. Both are existing topic names, exactly. Requires engineer_asked=true, which you may pass only when the engineer asked to merge or tidy topics — never on your own judgment; say which goes into which before calling.
Inputs: into (required), topic (required), engineer_asked. Returns: result
note_turnA
Record one diagnostic step: observed = what was seen, in your words or quoted, conclusion = what you concluded, ruled out, or propose next. Both are stored as the note — your account, not evidence. Machine output that grounds it goes in add_evidence verbatim first, then cite it in evidence_ids. kind (required) = change(바꿈: code/screen/config changed) · verified(확인: test/prod/repro confirmed) · finding(발견: measured or found out, a fact) · thought(생각: proposal/hypothesis/judgment — can be overturned); if two apply, split into two notes. next (required) = after this turn, what happens next, and owner (required) = whose turn it is: "user" (the engineer must act), "watch" (nothing to do, only watching), or an agent name such as "codex" / "claude". Say next EVERY turn, even when nothing changed — if it is the same line as before, nothing new is written, so this costs you a sentence and keeps the thread honest. A stale next is the failure this product exists to prevent: the next session reads it and goes off to do work that is already done. Updates the case brief. Call at the end of each step, not every message. Refused once 15 turns have piled up since the thread's focus was last declared: re-declare the focus if it is still the same work, or open_thread for the new subject. evidence_ids (optional) = the evidence numbers this conclusion rests on — cite them here, not in the text; the screen renders them as links. observed_from = "machine" (tool output, tests, diffs, files) or "user" (the engineer's words) — required; when "user", source_refs is required too (the id from the prompt's "casebook source_ref: " line, or on a chat client the id add_utterance returns) A next owned by the user is written TO the engineer ('Decide X'), never about them ('The user decides X'). FIRST LINE = TITLE: at most 120 columns (CJK counts as 2), no ' — ' joiner, and no record numbers (#517, D15635, 확장 122호, turn 80, commit hashes) — a person reads that line on the screen; put the rest after a blank line as the body. The paragraph right under the title is read on the screen too, so no record numbers there either; they go in a later paragraph or evidence_ids (the server refuses otherwise).
Inputs: kind (required), next (required), owner (required), case_id (required), +7 more. Returns: result
open_caseA
Start a new investigation case. Title = one line, the first symptom as the engineer stated it. Returns case_id; reuse it for the rest of this problem.
Inputs: title (required).
open_threadA
Start a thread — one question or change in one repository, followed to the end (deciding and building are one thread; re-declare focus to continue) — and bind it to this worktree. Open a new one only when the question changes. focus = one sentence, what this thread is for (durable declaration, not a summary). In the body, explain first — what the thread does and what would finish it — and put where it came from (the engineer's words, quoted) last, as its grounds: the screen shows the body in order, so a quote first hides the focus. topic (required) = the line of work this thread belongs to — it must be one of the engineer's existing topics; a name that is not one of them is refused once, with the list, so you choose instead of inventing. Only when none of them fits, call again with new_topic=true. "Uncategorized" (미분류) is refused — every thread belongs to a topic. Returns case_id; use it for evidence, note_turn, decide. FIRST LINE = TITLE: at most 120 columns (CJK counts as 2), no ' — ' joiner, and no record numbers (#517, D15635, 확장 122호, turn 80, commit hashes) — a person reads that line on the screen; put the rest after a blank line as the body. The paragraph right under the title is read on the screen too, so no record numbers there either; they go in a later paragraph or evidence_ids (the server refuses otherwise).
Inputs: focus (required), topic (required), facts, title, +3 more.
overviewA
Browse your open work across ALL repositories before choosing a directory, including in Codex where there is no SessionStart hook. Returns repositories with open threads: focus, next, updated_at (last turn, record or commit activity), and bound_worktrees. Repositories and threads are ordered by recent activity; closed/archived threads and repositories without open work are omitted. No worktree argument or model call. Use resume(case_id) for constraints and decisions before continuing a thread.
Inputs: no named parameters. Returns: result
rate_handoffA
Record the ENGINEER's judgment of one handoff (a fresh session that picked up a thread) — never your own score. Ask them, then pass what they said: constraints_retained / decisions_retained (did the new session honour them without being told again), duplicate_investigation (re-did finished work), wrong_next_step, re_explained (how many times they had to re-explain past context), retrieval_used / retrieval_changed_action (was a past thread searched, and did it change what happened). Leave unknown fields out.
Inputs: note, case_id, re_explained, retrieval_used, +5 more. Returns: result
record_utterancesA
For the Worktrail prompt uploader only (thin client) — not for agents. Stores the engineer's prompts verbatim, keyed by the prompt id the hook gave as source_ref; re-sent ids are ignored.
Inputs: items (required).
resumeA
Pick a thread up in a new session. When the host has no session-start hook (e.g. Codex), call it (or list_threads) first, before any other work. Durable state as it stands now, seven fields: focus · anchor (live git of this worktree: branch, HEAD, dirty) · constraints · decisions (with reason and authority) · open (unresolved) · next (actions) · evidence_refs — plus repo_state (repo-scope constraints/decisions shared by every thread of the repository, titles and numbers only — inspect(ref) for the full text; if one conflicts with the thread's own, both are shown, nothing is resolved for you). mode='fresh' omits decisions and ruled-outs. Never includes how it got here: pull that with trail(case_id) or find(query) when you need it.
Inputs: case_id (required), mode, facts, worktree.
rule_outA
Record that a hypothesis was ruled out — ONLY with the evidence that killed it and the scope where that holds (repro path, commit, environment). Outside the scope it is a hypothesis again. Ruling-outs stop future investigation, so the bar is higher than for a finding. Ruling out changes what happens next: next (required) and owner (required) = what happens next after this and whose turn it is — "user", "watch" or an agent name; a next owned by the user is written TO the engineer.
Inputs: scope (required), case_id (required), hypothesis (required), evidence_ids (required), +2 more. Returns: result
search_evidenceB
Search this engineer's recorded evidence across all their cases — the raw material, never past conclusions. When there is room left, results also include material from BEFORE casebook was installed (kind="pre_install"): the engineer's own words imported from old session logs, with the source session. Treat those as raw material only — they are not decisions or constraints, and they may describe approaches that were later abandoned. A hit is retrieval, not a conclusion.
Inputs: query (required), limit, include_archived.
search_priorA
Search what the engineer actually typed in sessions from BEFORE casebook was installed (repository history, imported by backfill). Returns their words verbatim with the source session — never a conclusion, and never anything an agent said. Nothing here is a decision or a constraint: it is raw material, and it may describe approaches that were later abandoned. Use it when the engineer asks what they were doing back then, or when you need the original wording of an old request; use search_evidence for recorded work.
Inputs: query (required), limit.
switch_threadA
Bind this worktree to an existing open thread (case_id), or pause: case_id omitted unbinds the worktree. Threads are per repository; the binding is per worktree, so two agents in two worktrees never overwrite each other. From a chat client the binding may point at a thread of any repository.
Inputs: facts, case_id, worktree.
trailA
Walk one thread back in time, one line per event: opened, focus/open/next declarations (with owner), decisions, constraints, ruled-outs, notes, evidence, commits, closed. The most recent limit lines; pass before=<the earliest line's at> for older ones. Use it when you need how a thread got where it is — resume gives only where it is now. Notes are marked interpretation, not evidence. inspect(ref) for any line in full.
Inputs: case_id (required), limit, before.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Descriptions are exhaustive and explicitly contrast several pairs (resume vs trail vs find vs inspect, add_evidence vs search_prior), which helps. But the set still has genuinely confusable siblings: open_case vs open_thread, list_cases vs list_threads vs overview, and search_evidence vs search_prior vs find all answer 'where do I look for past material?' without a crisp rule an agent can apply quickly. The heavy overlap plus three 'for scripts only, not for agents' tools (hook, record_utterances, import_prior) sitting in the same namespace makes misselection likely.
Everything is snake_case, and most names are verb_noun (add_evidence, list_threads, open_thread, close_thread, merge_topic, search_prior). The deviations are the handful of bare verbs (inspect, find, trail, resume, decide, define, constrain, handoff, overview), which are readable but break the pattern the rest of the set establishes.
30 tools is heavy for a thread/decision ledger, and the surface is inflated by internal-only entry points that agents must learn to skip. Several functional clusters (three searches, three listings, three evidence-ingest paths) could be collapsed into fewer tools with a mode parameter.
The lifecycle is well covered: open/switch/close threads, focus/open/next declarations, decisions, constraints, ruled-outs, terms, evidence with provenance, topics, search, and handoff. Gaps are minor — topics have no dedicated create or delete (assign/find-or-create only) and no edit path exists for evidence, though that append-only design is stated as intentional.
Maintenance
Related MCP Connectors
Persistent engineering memory designed to follow developers across coding agents.
Shared, scoped, reviewable team memory for AI coding agents.
Evidence-backed project memory and checkpoints for AI coding agents.
A home for your agents: an owned book of record any AI agent can write to, with provenance and undo.
Related MCP Servers
- AlicenseCqualityDmaintenanceCaptures key development moments, enables multi-agent traceability, provides intelligent context curation, and facilitates seamless agent-to-agent handoffs.2917MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding assistants to persist and restore development context across sessions, including decisions, progress, checkpoints, file caches, and searchable channel-based memory. Supports shared context across parallel sessions and helps recover after context compaction.243 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding assistants to persist, organize, search, checkpoint, and restore development context across sessions, resets, and parallel workflows.243 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding assistants to maintain persistent context across sessions by saving, searching, organizing, checkpointing, and restoring conversations, decisions, file content, and progress.243 npmMIT