Click on "Install 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., "@pleach which of my branches dealt with the flux bug?"
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.
Branch tracking, visualization, and merging for Claude Code sessions.
Claude Code can fork a conversation (/branch, --fork-session) but keeps no
record of what forked from what, shows no tree anywhere, and has no way to bring
two divergent branches back together. pleach adds those three things.
Unofficial third-party tool. Not affiliated with or endorsed by Anthropic. It reads session transcripts already on your disk and shells out to your own
claudebinary. It never touches credentials and never bundles Claude Code source.
* 9703da58 (leaky-bucket) 2026-08-01
| * a7aa4a1d (sliding-window) 2026-08-01
|/
| * 36a05f40 (token-bucket) 2026-08-01
|/
* 97c6581b 2026-08-01If you can read git log --graph, you already know how to read this.
Python 3.9+ and an installed claude. No dependencies, no build step, no
pip install — it runs from a checkout. (Claude Code 2.x ships as a native
binary and brings no Node runtime, which is why this is Python.)
Related MCP server: Session Buddy
Three commands, modeled on git:
pleach log # the session graph for this project — works instantly,
# even on history from before you installed pleach
pleach branch 9703da58 # fork a session; prints the `claude --resume` command
pleach merge a7aa a1d3 # reconcile two branches via a background agentThat's the whole core. Ids take any unambiguous prefix, like git SHAs. Typing
bare pleach prints this cheatsheet.
Two optional extras that pay for themselves:
pleach name 9703da58 leaky-bucket # labels show in the graph, like branch names
pleach init --write # install hooks: new forks tracked live
# (backs up settings.json; --uninstall reverses)There is no index to build and no scan step — every command refreshes lineage for the current project automatically, the way git just reads your repo.
pleach uiFull-screen interactive graph in the spirit of VS Code's git-graph panel, keys
modeled on tig/lazygit: j/k move between nodes, enter toggles the detail
panel, n names, b branches, s opens a branch summary in a pager, m
marks a node and m on a second node merges the pair (dry-run or dispatch),
r prints the resume command, a toggles all projects, q quits.
The VS Code extension takes the same keys, so the two surfaces are one set of
muscle memory: j/k (or arrows) move, g/G jump to the ends, enter resumes,
b branches, n renames, s summarizes, o opens the transcript, m pins a
session as the other half of a merge, a toggles all projects, / focuses the
filter, and ? lists the lot.
Claude Code's TUI has no extension point for custom panes, so ui can't render
inside a session — run it in a terminal pane next to one, exactly how the VS
Code git graph sits next to the editor. Inside a session, /pleach (from the
plugin) is the same functionality with Claude as the interaction layer: it
shows the graph and resolves "branch the top one as X" or "merge those two"
into the right commands for you.
Command | What it does |
| Interactive full-screen graph — navigate, name, branch, merge. |
| Git-style session graph. |
| Fork a session (a file copy — no API call). |
| Reconcile two branches via a background agent. |
| Label a session; labels show in the graph. |
| What happened in a branch, distilled. Cached. |
| Full-text search across transcripts. |
| Render a transcript as readable markdown. Local, free. |
| Parent, branch point, children, entry count. |
| Merges run here, and whether the agent has finished. |
| What's tracked, what's live, what's configured. |
| Flat table of tracked sessions. |
| Full rescan of every project (per-project refresh is automatic). |
| Drop stale index entries; |
| Environment checks; |
| Run the MCP server (stdio) — see below. |
pleach mcp is a zero-dependency MCP server
over stdio. Register it once:
claude mcp add --scope user pleach -- python3 /path/to/checkout/bin/pleach mcpFrom then on, Claude — in any terminal session and inside the official VS
Code extension's panel — can query your session graph directly. Ask it "which
of my branches dealt with the flux bug?" and it can call pleach_grep, read
the graph with pleach_log, pull a branch digest with pleach_summary, or
hand you the exact claude --resume command via pleach_show.
Tools exposed: pleach_log, pleach_show, pleach_grep, pleach_export,
pleach_summary, pleach_branch, pleach_name, pleach_merge_plan,
pleach_merge, pleach_status. Reads are free and local (summaries cost a
cached haiku call). The only side-effectful tools are pleach_branch (copies
a transcript, same as pleach branch) and pleach_merge (dispatches a
background merge agent); pleach_merge_plan is the dry run and its tool
description tells the model to use it first.
Remove with claude mcp remove pleach.
A merge is not a replay of tool calls. It is:
Reconstruct the shared context. Find the last entry both branches share — their branch point — and rebuild the conversation as it stood there.
Summarize each branch separately. A cheap model reads each full branch and reports what was tried, what worked, what failed, what was decided.
Seed a new agent from the shared context and hand it both summaries to reconcile.
Step 3 runs as a background session (claude agents to watch it), so it doesn't
disturb the session you're in. The merge agent is read-only by default: it
is given no tools at all, since it is pure synthesis over two summaries already
in its prompt. Pass --allow-writes if you actually want it editing files.
Merge bases are reused when the branch point hasn't moved, so re-merging the
same pair doesn't accumulate transcripts. pleach prune --snapshots --yes
removes the ones pleach created.
Use --dry-run to see the merge base, its confidence, and the exact prompt
without dispatching anything.
Because the agent runs in the background, pleach merges says which merges
have finished, and pleach export <merge-session> reads the reconciliation.
The extension does both for you: the sidebar tracks a dispatched merge from
"running" to "ready" and offers a Read the merge button.
Built against measured behaviour, not assumptions. The experiments and results are in PLAN.md §8, and the whole pipeline has been run end to end against real sessions:
Fork copying (§8.2). Forks preserve entry uuids exactly while rewriting
the sessionId field — the property that makes retroactive inference work.
Inference (§8.9). 19 edges inferred from real history, each re-derived independently from the raw transcripts: 19/19 correct parent and exact branch point.
Live fork detection (§8.10). Confirmed against a real fork with hooks installed.
Merge-base synthesis (§8.6). Confirmed: Claude Code resumes a transcript
pleach wrote. Merge bases are exact, and pleach branch costs no API calls.
The merge pipeline. Dispatched, ran, and produced a real reconciliation seeded from the correct shared context.
pleach doctor --test-synthesis re-checks the synthesis property on your
machine. If a future release breaks it, merges fall back to forking the live
parent and say so with a drifted warning rather than silently using a wrong
base.
Still untested: the interactive /branch and /fork TUI commands. All fork
testing used the --fork-session CLI flag. scan catches those either way.
The lineage index is the only place fork edges, names, and merge history live — none of it can be rebuilt by rescanning transcripts. So pleach never replaces a file it could not read:
An unreadable ~/.pleach/lineage.json is recovered from lineage.json.bak
(written before every change) or, failing that, left exactly as it is while
the command exits 3. It is never overwritten with an empty index.
An unreadable ~/.claude/settings.json stops pleach init entirely, with
the same exit code. --write and --uninstall both back it up first, and
--uninstall leaves the file alone if none of pleach's hooks are in it.
(A UTF-8 BOM counts as readable — it used to count as "empty".)
Transcript text is untrusted input: it is whatever a session contained,
including anything an agent quoted from a web page. Text sent to a model is
fenced with a per-call nonce and the rules are restated after the content, so a
transcript that contains instructions gets reported rather than obeyed —
verified end to end against a deliberately poisoned transcript. Merge agents
still run with no tools unless you pass --allow-writes.
Claude Code has no fork hook, and it signals forks differently across versions — pleach handles both.
On recent versions (measured on 2.1.219), SessionStart announces the fork
explicitly with source: "fork", but reports the child id and never names
the parent. The parent is recovered by prefix-matching the child's transcript
against its siblings, which is exact because a fork's transcript literally
begins with its parent's.
On older versions (2.1.207), SessionStart instead reports the parent with
source: "resume" — indistinguishable from a plain resume — and the child only
appears on UserPromptSubmit. There the signal is the mismatch between the two
events.
This is why init installs three hooks rather than one: on both paths a single
SessionStart hook detects nothing. Details in pleach/track.py.
One consequence worth knowing: the child's transcript is not on disk when
SessionStart fires, so parent resolution is retried on later events and falls
back to scan. A missed hook degrades to inference, never to a lost branch.
Edges found live are marked observed. Edges reconstructed by scan are marked
inferred — those pick the closest plausible ancestor, so in rare cases (a
branch taken immediately, before the parent did further work) they may attribute
to a grandparent rather than a parent. A shallower tree, not a wrong one.
bin/pleach entry point
pleach/track.py hook handler — the fork-detection state machine
pleach/infer.py retroactive lineage inference
pleach/transcript.py JSONL parsing, prefix comparison, branch points
pleach/mergebase.py shared-context reconstruction
pleach/merge.py the merge pipeline
pleach/graph.py tree building and rendering
test/smoke.py offline end-to-end testsRun the tests with python3 test/smoke.py. They use a throwaway config dir and
never touch your real ~/.claude.
Everything pleach records lives in ~/.pleach/ (override with PLEACH_HOME).
The only thing it ever writes into ~/.claude/projects/ is a reconstructed
merge base, which is tagged and removable with pleach prune --snapshots --yes.
It never modifies an existing transcript.
MIT.
Fork a session into a new tracked branch (copies the transcript under a new id, exactly like pleach branch). Returns the new session id and the claude --resume command to start working on it.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Project directory to scope to. Omit to use the current project. | |
| name | No | Label for the new branch. | |
| session | Yes | Session id, or any unambiguous prefix (like git). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It explicitly states that the operation copies the transcript under a new id, indicating non-destructive behavior, and discloses the return value (session id and resume command). This is meaningful context beyond a simple 'fork' statement, though it omits potential failure modes or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that leads with the core action, includes a precise parenthetical clarifying the copy behavior, and states the output. Every word contributes, with no wasted content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter and no output schema, the description provides the essential context: what it does, how it behaves (copies transcript), and what it returns. Minor gaps include potential branch naming collisions or behavior when the session does not exist, but these are not critical for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions (cwd, name, session), so the schema is doing the heavy lifting. The description adds no parameter-specific meaning beyond what the schema already provides, placing it at the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource: 'Fork a session into a new tracked branch' and further clarifies the mechanism ('copies the transcript under a new id'). This clearly distinguishes it from sibling tools like pleach_log, pleach_show, and pleach_grep, which are read-only operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: when you want to branch a session into a new tracked copy. However, it provides no explicit exclusions or alternative tool references (e.g., when to prefer pleach_merge or pleach_name), so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A session's conversation rendered as readable markdown (tool dumps elided). Local and free. Long transcripts are truncated at max_chars; prefer pleach_summary for a whole-branch digest.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Project directory to scope to. Omit to use the current project. | |
| session | Yes | Session id, or any unambiguous prefix (like git). | |
| max_chars | No | Truncate beyond this many characters (default 40000). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that tool dumps are elided, transcripts are truncated at max_chars, and the output is markdown. This is meaningful behavioral context, though it doesn't specify how truncation is signaled or how output is delivered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two front-loaded sentences deliver purpose and key limitations with no waste. Every word earns its place, including the alternative tool recommendation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema or annotations, the description gives sufficient context: output format, elision, truncation, and when to use a sibling. Minor gaps include absence of explicit return delivery method, but the core behavior is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the truncation behavior tied to max_chars but adds no substantive meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renders a session's conversation as readable markdown with tool dumps elided. It distinguishes from the sibling pleach_summary by contrasting truncation with whole-branch digest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends pleach_summary for whole-branch digests, providing a clear alternative for a different use case. It also notes the local/free nature, but lacks broader when-to-use or when-not-to-use guidance beyond that.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search across session transcripts (conversation text, not tool dumps). Answers 'which branch was the one where we worked out X?'. Returns matching sessions newest-first with snippets.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Project directory to scope to. Omit to use the current project. | |
| term | Yes | Substring to search for. | |
| limit | No | Max matching sessions to return (default 40). | |
| all_projects | No | ||
| case_sensitive | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that search is over conversation text, not tool dumps, and that results are returned newest-first with snippets. It does not mention auth, rate limits, or side effects, but for a search tool this is reasonable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences deliver the core purpose, scope, an example, and output behavior with zero filler. The description is front-loaded with the main verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, the description explains what it returns (sessions with snippets) and ordering (newest-first). It lacks edge cases like empty results or handling of all_projects/case_sensitive, but the overall context is sufficient for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60%, with descriptions for cwd, term, and limit. The description does not add further parameter semantics; all_projects and case_sensitive remain unexplained. Since coverage is moderate, the description should compensate, but it does not provide additional detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Full-text search across session transcripts' and clarifies scope by saying 'conversation text, not tool dumps'. It even gives an example question it answers, which clearly differentiates it from sibling tools like pleach_log or pleach_show.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit example use case ('which branch was the one where we worked out X?') implying when to use it, and adds an exclusion ('not tool dumps'). However, it does not name alternative tools or state when not to use it beyond that exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The Claude Code session branch graph for this project: an ASCII git-style graph plus one record per session (id, name, parent, live, subject, merges), newest first. Start here to see what branches exist.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Project directory to scope to. Omit to use the current project. | |
| limit | No | Max sessions to list, newest first (default 60). | |
| all_projects | No | Every project, not just this one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description is the sole source of behavioral info. It describes the output format ('ASCII git-style graph plus one record per session...') and ordering ('newest first'), which is helpful. However, it doesn't explicitly state that the tool is read-only or whether it has any side effects, though the 'log' name and output description imply a safe listing operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core output, and every sentence adds value. It avoids repetition of schema details and is appropriately sized for the tool's scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description appropriately summarizes the return value: an ASCII graph plus records with fields listed. It covers the operation's breadth (listing sessions) and ordering. Given the tool's moderate complexity, this is nearly complete; a minor gap is that it doesn't elaborate on what the graph looks like or what 'live' means in the records.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters (cwd, limit, all_projects) are already fully documented. The description only adds 'newest first' which reinforces the limit ordering but doesn't explain parameter usage beyond what the schema provides. Thus the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool produces an ASCII git-style session branch graph and per-session records, with the instruction 'Start here to see what branches exist.' This gives a specific verb and resource, and positions it as the overview tool among siblings, though it doesn't explicitly differentiate from pleach_branch or pleach_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Start here to see what branches exist' provides clear context for when to use this tool: as an entry point for exploring sessions. It implies a first-stop purpose but doesn't mention when not to use it or name alternative tools explicitly, which separates it from a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SIDE-EFFECTFUL: materializes a merge base and dispatches a background Claude agent to reconcile the two branches (read-only unless allow_writes). Use pleach_merge_plan first and confirm with the user before calling this.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Project directory to scope to. Omit to use the current project. | |
| branch_a | Yes | ||
| branch_b | Yes | ||
| allow_writes | No | Let the merge agent edit files (default read-only). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the side-effectful nature ('SIDE-EFFECTFUL'), background execution, merge-base materialization, and the default read-only behavior. This gives the agent essential safety and behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense, information-rich sentences with no redundancy. Front-loaded warning and clear action guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While it covers side effects, background dispatch, read-only default, and preconditions, it omits expectations for the agent's output or completion status. For a complex, side-effectful tool with no output schema, a bit more detail on the result or failure modes would round it out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers only cwd and allow_writes; branch_a and branch_b lack descriptions. The description mentions 'two branches' but does not clarify their roles or ordering, leaving ambiguity. It adds no meaningful semantics beyond the schema for the required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function: materialize a merge base and dispatch a background agent to reconcile two branches. It distinguishes from sibling pleach_merge_plan by explicitly positioning this as the execution step after planning, with a different scope and side-effect profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use pleach_merge_plan first and confirm with the user before calling, providing clear sequencing and an alternative. It also specifies the read-only default unless allow_writes is set, clarifying when to enable writes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dry-run a merge of two branches: branch point, merge-base method and confidence, and the exact prompt the merge agent would get. Dispatches nothing and writes nothing (summaries are computed, cached, small cost). Review this before calling pleach_merge.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Project directory to scope to. Omit to use the current project. | |
| branch_a | Yes | Session id or prefix. | |
| branch_b | Yes | Session id or prefix. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full disclosure: it states 'Dispatches nothing and writes nothing', notes that summaries are cached, and mentions small cost. This is strong behavioral transparency for a read-only dry-run operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and each clause adds meaningful detail (dry-run, outputs, safety guarantees, usage hint). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema or annotations, the description covers what it does, what it doesn't do, what it returns, and how to use it in sequence. It doesn't detail error cases or exact return structure, but those are not essential for a dry-run planning tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The tool description does not add extra semantic detail beyond the schema's minimal 'Session id or prefix' for branch_a/branch_b, but it's already clear from context. Baseline of 3 applies when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Dry-run'), identifies the resource ('a merge of two branches'), enumerates the outputs (branch point, merge-base method, confidence, exact prompt), and implicitly distinguishes itself from the sibling tool 'pleach_merge'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs 'Review this before calling pleach_merge', creating a clear sequential workflow. While it doesn't formally list exclusions or alternative scenarios, the 'before' guidance implies its place in the tool pipeline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Label a session; labels show in the graph.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Project directory to scope to. Omit to use the current project. | |
| label | Yes | ||
| session | Yes | Session id, or any unambiguous prefix (like git). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose that labels show in the graph, but it does not mention whether labeling is idempotent, overwrites existing labels, or requires the session to exist. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the action and effect. There is no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description omits behavioral context such as overwrite behavior, session existence requirements, or relationship to other tools. The lack of annotations and output schema means the description should provide more context, but it remains minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes 'cwd' and 'session' but leaves 'label' undocumented. The description adds that labels show in the graph, giving purpose to the label parameter, but it does not clarify format or constraints. With 67% schema coverage, the description should compensate more for the missing label description, but this is partial credit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Label' and resource 'session', and states the effect 'labels show in the graph.' This distinguishes it from sibling tools like pleach_log and pleach_show, which have different actions and resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when you want to label a session for graph display) but provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full detail for one session: lineage (parent, branch point, children), transcript path, entry count, merges it took part in, and the command to resume it.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Project directory to scope to. Omit to use the current project. | |
| session | Yes | Session id, or any unambiguous prefix (like git). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It explicitly lists the type of information returned (lineage, transcript path, entry count, merges, resume command), which implies a read-only inspection tool. It does not mention error behavior or permissions but is substantially transparent for a show tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is front-loaded with the main purpose and lists specific details without unnecessary words. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With two simple parameters and no output schema, the description adequately explains what the tool returns and the scope of one session. It could mention potential error conditions or permission requirements, but given the tool's simplicity, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter semantics are fully documented in the schema. The description adds no additional parameter information, but it does not need to; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows full detail for one session, enumerating specific content (lineage, transcript path, entry count, merges, resume command). This distinguishes it from sibling tools like summary or status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Full detail for one session' clearly indicates when to use this tool, but it does not explicitly mention alternatives or when-not-to-use conditions. Context is clear, though no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What pleach is tracking for this project: session/fork counts, live sessions, observed vs inferred edges.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Project directory to scope to. Omit to use the current project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether the tool is read-only, whether it has side effects, or any prerequisites. The description only lists the data categories without clarifying the operation's safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or redundant wording. Every word contributes meaning, making it highly concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists the key data categories returned (session/fork counts, live sessions, edges), which gives the agent a good idea of what to expect. However, it does not specify the output format or response structure, and since there is no output schema, the description leaves some ambiguity. Still, for a simple status tool with one optional parameter, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full documentation for the only parameter 'cwd' (with a clear description and optionality). The description adds no information about parameters, so the baseline score of 3 is appropriate given complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource (pleach tracking data) and lists specific content (session/fork counts, live sessions, observed vs inferred edges), giving a clear idea of what the tool reports. However, it lacks an explicit action verb like 'get' or 'show', relying on the noun phrase 'What pleach is tracking'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like pleach_log or pleach_summary. It only states what the tool reports, without any context on selection criteria or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize what a branch attempted, what worked, what failed, and what was decided. Cached per branch head; a cache miss makes model calls (small cost, works at any transcript size).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Project directory to scope to. Omit to use the current project. | |
| model | No | Summarizer model (default haiku). | |
| session | Yes | Session id, or any unambiguous prefix (like git). | |
| no_cache | No | Force re-summarization. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral transparency burden. It discloses caching per branch head, the cost implications of a cache miss (model calls), and the capability to handle any transcript size, which are valuable behavioral traits beyond the basic purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the purpose and follows with behavioral/cost details. Every word contributes value, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description covers purpose, caching behavior, cost, and scale, which is quite complete. It could mention what the output looks like or any prerequisites, but the purpose is clear enough for an agent to infer the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are explained in the schema. The description adds context about caching and cost that relates to the no_cache parameter, but it does not elaborate on individual parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Summarize') and defines the resource as a branch's attempt outcomes. It distinguishes itself from siblings like pleach_log (raw log) and pleach_status (current state) by focusing on attempted, worked, failed, and decided aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining a concise summary of branch activity, and notes it works at any transcript size, but it does not explicitly state when to use this tool over alternatives or provide exclusions. No sibling tools are named as alternatives, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct aspect of session branching: graph overview, session details, search, export, summary, forking, labeling, merge planning, merging, and tracking stats. There is no meaningful overlap between any two tools.
All tools share the consistent 'pleach_' prefix and snake_case, but the second part mixes verbs (show, grep, export, branch, name, merge) and nouns (log, summary, status, merge_plan). This is mostly consistent with minor deviations.
Ten tools is well-scoped for a session branching system, covering the full range of operations without redundancy or bloat. Each tool earns its place in the set.
The tool surface covers core operations: branch, merge (with planning), inspect (log, show, grep, export, summary), label, and status. A minor gap is no delete/archive operation for sessions, but this is likely intentional and does not block primary workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
Cross-agent artifact workspace with provenance across Claude Code, Codex, Cursor, LangGraph.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Intelligent context infrastructure for AI teams: knowledge graph, sessions, tasks, documents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/foudrayelias-ALPHA/pleach'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
