twicc-session

name	twicc-session
description	Inspect a single session — view metadata, read raw item content by line number, read user/assistant messages, list subagents, read its plan, or list/inspect its workflows. Use when you or the user want to examine a session, read conversation content, or explore subagent activity.
argument-hint	<session_id> [content|messages|agents|plan|workflows|workflow]

TwiCC Session

Inspect a single session. Seven sub-commands:

• Default — full session metadata.
• content [LINE_OR_RANGE] [--contains TEXT ...] — raw JSONL items by line number and/or content substring(s) (provider-specific schema).
• messages [--contains TEXT ...] — user/assistant messages only, uniform shape across providers.
• agents — list subagents spawned by this session.
• plan [PATH] [--list] — the session's tracked plan documents (both providers): most recently updated one by default, a specific one by path, --list to enumerate.
• workflows [--limit N] [--offset N] — list this session's workflows (Claude Code only).
• workflow <ID> — show one (Claude Code only).

When to use

• You or the user want details about a specific session.
• You want to read conversation content (raw items or clean messages).
• You want to see which subagents were spawned by a session.
• You want to read the session's plan (e.g. inspect what a worker session planned).
• You want to list a session's workflows, or inspect one.

How to invoke

Prefer the mcp__twicc__* tools when you have them. Inside a TwiCC session your tool list may include mcp__twicc__* tools — one per command below (the command with / and - turned into _, e.g. mcp__twicc__create_session, mcp__twicc__update_session_settings). When present, use them instead of the $TWICC CLI: same arguments, same JSON result, no shell, and your session identity travels with the call so self/parent resolve on their own. Fall back to the $TWICC CLI below when those tools aren't available (outside a session, or when scripting from a terminal).

TwiCC's executable varies by launch mode (uvx, dev, installed tool). ALWAYS USE THIS TO RESOLVE $TWICC AT THE START OF EACH BASH INVOCATION:

TWICC=${TWICC_BIN:-$(command -v twicc 2>/dev/null)}
[ -n "$TWICC" ] || { echo "TwiCC executable not found in this context" >&2; exit 1; }

Then run $TWICC <args> — never quote $TWICC (use $TWICC args, never "$TWICC" args): it may expand to multiple words, which quoting would break.

Usage

Default — session metadata

$TWICC session <SESSION_ID>

Works for regular sessions and subagents.

{
  "id": "abc123-def456",
  "project_id": "-home-twidi-dev-myproject",
  "provider": "claude_code",
  "parent_session_id": null,
  "last_line": 150,
  "mtime": 1741654800.0,
  "created_at": "2025-03-10T14:30:00+00:00",
  "last_started_at": "2025-03-10T14:30:00+00:00",
  "last_updated_at": "2025-03-10T15:45:00+00:00",
  "last_stopped_at": "2025-03-10T15:50:00+00:00",
  "last_new_content_at": "2025-03-10T15:45:00+00:00",
  "last_viewed_at": "2025-03-10T16:00:00+00:00",
  "stale": false,
  "title": "Implement user authentication",
  "slug": null,
  "user_message_count": 12,
  "compute_version_up_to_date": true,
  "context_usage": 85000,
  "self_cost": 1.234,
  "subagents_cost": 0.567,
  "total_cost": 1.801,
  "cwd": "/home/twidi/dev/myproject",
  "git_branch": "feature/auth",
  "git_directory": "/home/twidi/dev/myproject",
  "model": {"raw": "claude-opus-4-20250514", "family": "opus", "version": "4"},
  "archived": false,
  "pinned": null,
  "permission_mode": "default",
  "selected_model": null,
  "effort": null,
  "thinking_enabled": null,
  "claude_in_chrome": false,
  "fast_mode": false,
  "context_max": 200000,
  "compacted": false,
  "hidden": false,
  "spawned_by": null,
  "spawn_root": null,
  "annotations": {"role": "reviewer"}
}

Key fields

• last_line — total item count; use as the upper bound for content ranges.
• provider — "claude_code" or "codex". Determines item schema for content.
• slug — provider short id (e.g. Codex subagent nickname), or null.
• parent_session_id — null for regular sessions, set for subagents.
• model — {"raw": "...", "family": "...", "version": "..."}.
• context_max / context_usage — max context window and current usage in tokens.
• compacted — whether the session has been compacted at least once.
• last_new_content_at — most recent item appended.
• last_viewed_at — when the user last opened the session in TwiCC.
• hidden — whether the session is hidden from all listings and broadcasts.
• spawned_by — session ID that spawned this session, or null.
• spawn_root — root session ID for the spawned-session tree, or null before a session joins one.
• annotations — free-form JSON object attached at session creation.

Content — raw items

$TWICC session <SESSION_ID> content [LINE_OR_RANGE] [--contains TEXT ...]

The lowest-level view: every raw item, including tool calls and results — unlike messages and search, which only ever see user/assistant text.

Filter by line/range, by substring, or both:

• Single line: content 5
• Range: content 10-20 (inclusive)
• Substring: content --contains "some text" — every item whose raw content contains the text.
• Multiple substrings: content --contains foo --contains bar — repeatable, AND-combined (an item must contain every term).
• Combined: content 10-20 --contains "some text" — the line/range scopes the substring search.

At least one of LINE_OR_RANGE / --contains is required.

--contains is case-insensitive and matches the raw JSONL string (the verbatim line as stored). Consequences: it also matches JSON keys (e.g. "role", "type"), and embedded newlines are escaped (\n), so a query spanning a line break won't match. This is the only way to substring-search across all raw items (tool_use/tool_result included).

Returns a JSON array. Each entry is {line_num, content}, where content is the raw JSONL object. Schema of content depends on provider:

• claude_code — Claude API objects (user/assistant messages, tool_use, tool_result, …).
• codex — Codex schema (user/assistant messages, function_call, function_call_output, …).

[
  {
    "line_num": 5,
    "content": {
      "type": "user",
      "message": {"role": "user", "content": [{"type": "text", "text": "Hello"}]},
      "timestamp": "2025-03-10T14:30:00.000Z"
    }
  }
]

Check last_line from the default sub-command first to know the valid range.

Messages — uniform transcript

$TWICC session <SESSION_ID> messages [OPTIONS]

User + assistant messages only, uniform shape across providers. No tool calls, no system noise.

• --range N or --range N-M — filter by JSONL line number (same numbering as content). Only user/assistant messages whose line_num falls within the range are returned — not the Nth message in the list.
• --role user|assistant — keep only one side.
• --contains TEXT — keep only messages whose text contains the substring. Repeatable and AND-combined (a message must contain every term). Case-insensitive. Unlike content's --contains (which matches the raw JSONL), this matches the extracted text shown below — no JSON keys, no tool noise. Applied before --tail/--limit/--offset, so paging windows the matching messages.
• --limit N — cap results (default: no cap).
• --offset N — skip first N messages (default: 0).
• --tail N — return the last N messages. Mutually exclusive with --limit/--offset.

[
  {"line_num": 3, "text": "Hello, can you help me?", "role": "user", "timestamp": "2025-03-10T14:30:00+00:00"},
  {"line_num": 4, "text": "Sure — what do you need?", "role": "assistant", "timestamp": "2025-03-10T14:30:02+00:00"}
]

Common patterns:

• Last agent reply: messages --role assistant --tail 1
• Last N exchanges: messages --tail N
• Focused window from search: messages --range A-B
• Messages mentioning a term: messages --contains "auth"
• Last reply mentioning a term: messages --role assistant --contains "auth" --tail 1

Agents — list subagents

$TWICC session <SESSION_ID> agents [--limit N] [--offset N]

Only valid on parent sessions (errors on subagents). Returns provider-internal subagents, not sessions created via create-session; use $TWICC topology <ID|self> for the spawned_by tree (skill: twicc-topology). Ordered by most recently active.

Plan — the session's tracked plan documents

$TWICC session <SESSION_ID> plan
$TWICC session <SESSION_ID> plan <PATH>
$TWICC session <SESSION_ID> plan --list

The session's plan-like documents: the native Claude plan (what plan mode writes) plus detected plans/specs/handoffs/notes... written by the session or its subagents — both providers.

Without argument: the content of the most recently updated tracked document (not necessarily the native plan), as {path, abs_path, content}. Errors (exit 1) when the session tracks none — the default view's plan_paths field tells you up front.

With a PATH argument: the content of that document. Matched against the tracked entries only (never an arbitrary filesystem path): give the stored path exactly as shown by --list (project-relative when the doc lives under the project, absolute otherwise) or its resolved absolute path. Errors (exit 1) on unknown path or missing file.

--list: every tracked document, newest first:

{"plan_paths": [{"path": "docs/plans/feature-plan.md", "exists": true,
                 "created_at": "...", "updated_at": "...", "source": "detected",
                 "abs_path": "/abs/path/to/docs/plans/feature-plan.md"}, ...]}

source is detected, subagent (written by a subagent), or claude_plan (the native plan); abs_path is always resolved (worktree-aware). The default view's plan_paths field carries the same entries (without abs_path), so you rarely need --list after fetching the session.

Workflows — list runs

$TWICC session <SESSION_ID> workflows [--limit N] [--offset N]

This session's workflows, newest first (Claude Code only). The default view's has_workflows boolean says whether any exist.

Workflow — one run

$TWICC session <SESSION_ID> workflow <ID>

One workflow, by the id from workflows. Errors (exit 1) when unknown.

Examples

$TWICC session abc123-def456
$TWICC session abc123 content 5
$TWICC session abc123 content 10-20
$TWICC session abc123 content --contains "TypeError"
$TWICC session abc123 content --contains TypeError --contains "auth.py"
$TWICC session abc123 content 10-200 --contains "TypeError"
$TWICC session abc123 messages --tail 1
$TWICC session abc123 messages --role user
$TWICC session abc123 messages --contains auth
$TWICC session abc123 messages --role assistant --contains auth --tail 1
$TWICC session abc123 agents
$TWICC session abc123 agents --limit 50
$TWICC session abc123 plan
$TWICC session abc123 plan docs/plans/feature-plan.md
$TWICC session abc123 plan --list
$TWICC session abc123 workflows
$TWICC session abc123 workflows --limit 5
$TWICC session abc123 workflow wf_cd590ff1

Related commands

• $TWICC sessions — find session IDs. Skill: twicc-sessions.
• $TWICC process <session_id> — live process state and PID. Skill: twicc-process.
• $TWICC topology <ID|self> — map spawned sessions around this node. Skill: twicc-topology.
• $TWICC search "<query>" — results include session_id + line_num for use with content. Skill: twicc-search.
• $TWICC project <project_id> — project details. Skill: twicc-project.

How to present results

1. Default: summarize title, date, model, branch.
2. Content: show items in readable form, distinguishing user vs assistant vs tool.
3. Messages: render transcript in order, prefixing each entry with its role.
4. Agents: list with titles; offer to inspect any specific subagent.
5. Plan: render the content markdown as-is.
6. You are in TwiCC — link to a session: [link text](/project/{project_id}/session/{session_id}).
7. Only include cost information if explicitly asked.