Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
CASEBOOK_DBYesPath to the local SQLite database file for storing Worktrail records.
CASEBOOK_MCP_EMAILYesEmail 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

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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 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.

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: 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).

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

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

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A3.6/5.0

Scored across 30 tools

Disambiguation3/5

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.

Naming Consistency4/5

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.

Tool Count2/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessOutdated data