Capture a coding session from inside it

A hands-on ENGRAM walkthrough · August 3, 2026

Pairs with Tutorial 5 (the Build Timeline): git tells ENGRAM what shipped; captured sessions tell it why — even from tools the Watcher can't see.

1. Why this tutorial exists

ENGRAM already has a passive Watcher that ships your Claude Code CLI sessions into your Knowledge Hub by tailing the transcript files on disk. It's automatic and complete — but it has three blind spots, all from the same root: it reconstructs meaning after the fact from one tool's private on-disk format.

1. It only sees Claude Code CLI. Work done in Cowork, Claude Desktop, a Goose-run agent, or any other coding tool leaves no ~/.claude/projects/*.jsonl for the Watcher to read. Those sessions are invisible.
2. It can't reach the pruned past. Once a transcript file is deleted, the meaning in it is gone — the Watcher can only re-read files that still exist.
3. Its signal is thin. A quiet git commit -q prints no SHA for the Watcher to catch, and the auto-captured recap is usually the tool's "this session is being continued…" boilerplate, not a distilled account of what you built.

Session capture fixes all three by capturing at the source. A skill — or a single MCP call — runs inside the live session and gathers ground truth: the exact HEAD SHA, the files you touched (git diff), and a summary you author. No dependence on a transcript file existing, surviving, or being parseable.

Crucially, it's additive: capture and the Watcher both key on the same session_id, so they enrich the same session in the graph — the capture supplies the exact SHA and a good summary, the Watcher (if it also ran) supplies the exhaustive action list. Nothing forks, nothing is duplicated.

2. What you'll do

1. Capture a coding session with the capture_session MCP tool — the harness-neutral way that works from any MCP-connected agent.
2. (Optional) Do the same with the /capture-session slash command in Claude Code.
3. See the captured session appear in Coding Sessions, converge with the Watcher's record, and light up as evidence (◇ N sess) on your Build Timeline components.

3. Prerequisites

Everything below runs as you — capture is filed under the identity of the PAT behind your MCP connection, and (like every ENGRAM write) is private to you.

Part 1 — Capture with the MCP tool (the harness-neutral way)

This is the primary path: it needs nothing installed beyond the MCP connection you already have, and it works from any agent — Cowork, Claude Desktop, a Goose worker, Claude Code — exactly the surfaces the Watcher is blind to.

At a session boundary (end of a work block, or after a milestone), have the agent gather three things with a shell and call the tool:

# 1. the session id — however your harness names the session
# 2. git ground-truth
head_sha=$(git rev-parse HEAD)
touched=$(git diff --name-only <base>..HEAD)   # <base> = HEAD at session start, or @{u}
repo_url=$(git remote get-url origin)

# 3. author a short "what we built / decided / rejected" summary

Then call capture_session:

capture_session(
    session_id="<your-session-id>",
    summary="Added jitter to the checkout-service token-refresh retry loop; "
            "root-caused the auth-suite flake to a missing backoff. Rejected a "
            "blanket retry-count bump as it masked the real timing bug.",
    head_sha="<head_sha>",
    touched=["services/checkout/auth.py", "services/checkout/tests/test_auth.py"],
    repo_url="git@github.com:your-org/checkout-service.git",
    branch="main",
)

• Only session_id and summary are required. The rest are optional but each one adds signal: head_sha + touched are what turn a session into precise component evidence on the Build Timeline; repo_url is what files the session under the right project.
• It converges, it doesn't duplicate. Re-run it with the same session_id and it enriches the same session — safe to call more than once (an interim capture, then a final one).
• It degrades by surface. No shell (a restricted/web agent)? Send just session_id + summary — still a durable record. Shell but no transcript (Cowork, Desktop)? Send the git ground-truth too — that's the sweet spot the Watcher can't reach.

Part 2 — The /capture-session slash command (Claude Code)

If you're in Claude Code, a slash command wraps the same capture with the gathering done for you:

/capture-session <session-id>

The command's skill gathers the git state, asks the agent to author the summary, and posts the capture — no manual shell steps.

Adding the skill. The slash command ships as a small skill folder. Drop it into your project's (or user) .claude/ directory:

.claude/
  commands/capture-session.md          # the /capture-session slash command
  skills/capture-session/
    SKILL.md                           # how to gather + author the summary
    capture.sh                         # git ground-truth + POST to ENGRAM

With the skill present and your ENGRAM MCP connection configured, /capture-session is available in the CLI. (The MCP tool in Part 1 needs none of this — reach for the slash command only for the Claude Code convenience.)

Part 3 — See it in ENGRAM

Open Coding Sessions and select the project. The captured session is there alongside any Watcher-ingested ones:

• In the session list — your capture, with the model, branch, and the summary you authored (not boilerplate).
• On the Build Timeline — if touched files map to components, the session shows up as ◇ N sess evidence next to them: click a component, see the sessions that built it, click one to open it. This is the Tutorial 5 timeline getting the high-fidelity "why" it was missing.
• Convergence in action — if the Watcher also saw this session (Claude Code CLI), you'll see one session, not two: the capture's exact SHA + good summary and the Watcher's full action list live on the same node.

What this does and doesn't give you

It gives you:

• A harness-neutral way to get a session into ENGRAM — Cowork, Desktop, Goose, or any MCP agent, not just the Claude Code CLI the Watcher requires.
• Ground truth at the moment of work — the exact SHA and touched files, captured before any transcript can be pruned.
• A summary worth reading — your account of what you built, feeding the Build Timeline's "click a bar, see the thinking" value.

It doesn't:

• Replace the Watcher. The two are complementary and converge on the same nodes; the Watcher stays automatic for Claude Code CLI, capture adds the surfaces and signals it can't reach.
• Fire on its own. Capture is on-demand — you (or your agent) run it at a session boundary. (An optional end-of-session reminder hook can nudge you, but it never captures for you.)
• Clone or change your repo. It only reads git; nothing is written to your working tree.

Appendix — Gotchas, ranked by how much time they'll cost you

1. 404 "Session capture is not enabled." The feature is off on your ENGRAM. It's an administrator setting on this shared system — ask your admin to enable it; you can't flip it yourself.
2. The session filed under the wrong (or no) project. Pass repo_url (git remote get-url origin). Without it, ENGRAM falls back to the working-directory path to name the project — which won't match a project created from git elsewhere.
3. No touched files → no timeline evidence. The ◇ N sess links come from touched mapping to component paths. A summary-only capture is a valid record but won't attach to components.
4. The base for "touched since session start." git diff --name-only <base>..HEAD needs a <base> — the HEAD SHA when the session started. If you didn't capture it, @{u} (the upstream) or the merge-base is a good best-effort; recording something beats nothing.
5. Quiet commits. git commit -q hides the SHA from the Watcher — capturing git rev-parse HEAD yourself is exactly how you get it into ENGRAM anyway.