Worktrail
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| CASEBOOK_DB | Yes | Path to the local SQLite database file for storing Worktrail records. | |
| CASEBOOK_MCP_EMAIL | Yes | Email address of the user, used by the MCP server. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Worktrail keeps a durable, byte-exact record of engineering work so the next session or agent can pick it up without guessing.
No session-start hook (e.g. Codex)? Call resume (or list_threads) first, before any other work.
Unit of work: a thread — one question or change in one repository, followed to the end. Deciding and building are ONE thread (re-declare focus); open a new one only when the question changes. open_thread / switch_thread / close_thread; declare(focus|open|next) keeps it current.
When to record — before you end each reply, record only what it settled; skip a reply that settled nothing (not every reply).
A turn is when the machine told you something that changed what you would do next — a test result, an error, a diff. Record the raw output as evidence and your conclusion. If nothing new was observed, there is no turn.
Keep raw evidence sparse: what grounded a decision or is hard to reproduce; if git or a file holds it, reference it. A document you keep rewriting (Q&A notes, analysis, design .md) is not evidence: reference its path; when the engineer adds to it, add_evidence only the new part, verbatim.
Your conclusions are interpretation, not evidence.
add_evidence / add_evidence_file take raw material VERBATIM — never paraphrase or trim. note_turn(kind=change|verified|finding|thought): what you observed and concluded. handoff only when the engineer asks where things stand. First line of every statement = its title: ≤120 columns (CJK=2), no ' — ', no record numbers (#517, hash) in it or the paragraph under it. A next for the user is written to them.
Durable state — the boundary is "what could overturn it": a hypothesis stays in note_turn, never in decide. A decision or constraint (only the engineer can change it) goes to decide/constrain with authority, superseded, not edited. rule_out needs the evidence that killed the hypothesis AND the scope where that holds.
resume = the state now. The past: find(query) → trail(case_id) → inspect(ref); a hit is retrieval, not conclusion.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| 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. |
| 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. |
| 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. |
| 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). |
| 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. |
| 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). |
| 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). |
| 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). |
| 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. |
| merge_topicA | Merge one topic into another, FOR THE ENGINEER: every thread under |
| 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. |
| list_casesA | List the engineer's recent cases (id, title, status, current focus) — to find the case to continue. |
| add_evidenceB | Store raw material VERBATIM as evidence: logs, error output, command results, config. Do not paraphrase or trim. Returns the evidence number. |
| 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. |
| note_turnA | Record one diagnostic step: |
| 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. |
| 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. |
| 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). |
| 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 |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.