Sessions

Overview

Every Claude Code conversation is kept as a transcript (~/.claude/projects/<slug>/<uuid>.jsonl). C3 keeps its own session records, snapshots and tasks beside the project. Before 2.143.0 nothing joined the two: "which session was I doing X in, is it worth going back to, how do I get back" meant opening JSONL files by hand, and nothing could record that a session was a dead end.

There's a third, unrelated thing with "sessions" in its name: c3_status(view='sessions') reads .c3/session_stats.jsonl and prints token/cost totals per host session — a budget report, not the catalog or the liveness heartbeat.

One row per conversation

The row key is the Claude Code session id — the transcript's file name and the value claude --resume takes. session_catalog.py joins everything that belongs to it:

A transcript is read from its head (64KB, widened to 512KB if a pasted prompt pushes the first one out) and its tail (256KB, then 1MB, then 4MB until a title turns up) — the whole file is never parsed. Results are cached per file in .c3/cache/session_catalog.json, keyed on size and mtime. The newest 200 transcripts per project are listed.

The transcript folder must be the exact Claude Code slug of the project path (or an exact alphanumeric match) — it never falls back to "a folder whose name contains the project name", because a wrong folder would resume another project's session. A transcript whose recorded cwd is a different directory is skipped. A session run from a worktree has its own slug and is still found through its C3 record, resuming in the worktree. CLAUDE_CONFIG_DIR is honored, as Claude Code itself honors it.

c3_session actions

c3_session(action=..., data=..., reasoning=..., description=..., summary=..., event_type=..., target=...). Two families: session-lifecycle actions (unchanged since before 2.143.0) and the catalog actions list / stale / unstale / note, added in 2.143.0 and taking the new target parameter.

Lifecycle

Session catalog (2.143.0)

# Mark this branch's earlier session as superseded
c3_session(action='stale', target='a1b2c3d4',
           reasoning='superseded by the 2.143 branch', data='<successor id>')

# Undo it
c3_session(action='unstale', target='a1b2c3d4')

# Leave a note before stopping
c3_session(action='note', data='Hub tab done', reasoning='Desk segment next')

# List sessions likely worth marking
c3_session(action='list', target='likely')

Stale, marks & hints

Stale means superseded, finished, or abandoned: don't resume this. Only an agent or a person sets it, and always with a reason. A successor session can be named as well. Marks append to .c3/session_marks.jsonl ({ts, provider, id, op, reason, successor, summary, next_steps, by: agent|user, by_session}) and fold last-wins — several MCP processes and the Hub can write at once, and an append never loses a concurrent row the way rewriting one JSON file would. The file is also the audit trail; every mark writes a session_mark activity row too.

Hints — heuristics, never a hide

Hints are grey chips that suggest a look. They never hide a row, and a live session gets none.

idle Nd ended by /clear branch gone short

The Hub's Likely stale filter shows unmarked rows that have at least one hint.

Liveness v2.128.0

Before 2.128.0 the hub's "live" light was inferred from activity-log rows, and it lied three different ways: a closed IDE read live for up to 20 minutes (a real session_end row was written but nothing read it), a quiet-but-open session read dead after 20 minutes of tool-call silence even with its MCP process right there, and a busy session sometimes read dead too — the lookup scanned only the log's last 100 lines, and this repo's own running session's session_start once sat 319 lines from the end of a 20,825-line log.

The fix is a fact, not an inference: the MCP server writes one heartbeat file per session, .c3/live/<c3_session_id>.json = {session_id, host_session_id, ide, pid, ts}, refreshed every 60s (HEARTBEAT_INTERVAL_S). A reader treats a file whose ts is within 180s (HEARTBEAT_TTL_S, three missed beats) as live. Clean shutdown removes the file before slower teardown steps run; a crash or a taskkill leaves a stale file, which the next reader ignores and prunes. pid is recorded for diagnostics only — liveness is decided by the timestamp, since pids are reused across reboots and there's no cheap portable "is this pid alive" check.

One heartbeat file per session, not per project, so two IDEs on one project, or a repo and its worktree, each report themselves; the hub card shows MCP×N. Where there's no heartbeat (an older C3 in another checkout, or a process killed without cleanup), the old activity-log inference is still the fallback, now also honoring a terminal session_end row.

Checking it by hand

ls .c3/live                      # one file per live session in this project
python -c "from services import session_live as s; print(s.live_sessions('.'))"

The hooks and the MCP server load their code at process start, so a change here is not live in the session that made it — a new IDE session is required, and the Hub must be restarted.

Hub Sessions tab

The top bar's Sessions view lists past sessions across every registered project (or one, via the left rail), one row each, with a resume button. It never returns another session's live prompts unless you expand that specific row.

Filters

Each row shows a live dot, the title, a LIVE pill when applicable, the branch, the project (in the all-projects view), the hint chips or the stale reason, and counts of linked tasks/decisions/a snapshot. Expanding a row loads its detail: first/last prompt, the agent note or last snapshot, linked tasks and recent decisions, the predecessor/successor chain, and a preview of the last 8 turns.

Row actions

Routes (Hub, loopback + CSRF guard)

These routes are deliberately not on the Oracle gateway. Oracle can bind to the tailnet, and transcript previews (someone else's prompts) should stay on this machine. The first all-projects listing on a machine reads every transcript head and tail once; around 1,000 transcripts took about 20 seconds on the box this was measured on. Later loads are served from the per-file cache.

c3_task & sessions

Sessions are conversation history; c3_task is durable project-management state that survives every conversation — tasks (backlog / in_progress / blocked / done, priority p0–p3, due dates, tags), milestones, and a decision-note log, stored in .c3/pm/pm.json. A session links to the tasks it created or touched, which is what links.tasks in the catalog and the Tasks section of a session's Hub detail view come from.

Milestones can be completed, not just archived v2.86.0

Archiving a milestone was the only way to close one, and archiving detaches every task from it — the record of what shipped under which milestone survived only in the event log. milestone_complete flips the lifecycle to completed (stamping completed_at): the milestone leaves default listings and the board, but its tasks keep their link. It refuses while open tasks remain. milestone_reopen undoes it.

# Link a task to this conversation
c3_task(action='link', task_id='a1b2c3d4', link_type='session', ref='current')

# Close out a shipped milestone, keeping the history
c3_task(action='milestone_complete', milestone='v2.145')

# What's blocking, and what's ready to unblock
c3_task(action='report')

Task ids accept any unique prefix (≥4 chars); milestones resolve by id or unique name. Read actions (list, get, board, report, history, the time_* reads) are plan-mode safe. Ephemeral session plans stay in c3_session(action='plan') — they don't belong in the durable task store.

Troubleshooting