twicc-sessions

name	twicc-sessions
description	List sessions tracked by TwiCC, or batch-look up specific session_ids. Use when you or the user want to browse sessions, find a session ID, filter by project, or batch-fetch metadata for known ids.

TwiCC Sessions

List sessions, or batch-look up specific ones with sessions get. Only returns valid sessions (with a creation date and at least one user message), unless you use get (which returns anything you name explicitly).

When to use

• You or the user want to list or browse sessions.
• You need to find a session ID.
• You have a list of known session_ids and want to batch-fetch their metadata — use sessions get <ID>... (returns subagents, archived, and hidden too since you named them explicitly).

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

List

$TWICC sessions [OPTIONS]

Results are ordered by most recently active.

• --project <PROJECT> — filter by project (path or id; drop the leading dash on ids). A normal project also returns its git worktrees' sessions (a worktree's sessions belong to its main repository); a worktree project returns only its own. Non-existent project returns empty, no error.
• --workspace ID — filter to sessions of projects in the given workspace, including each member project's git worktrees. Mutually exclusive with --project.
• --limit N — max results (default: 20).
• --offset N — skip first N for pagination (default: 0).
• --include-archived — include archived sessions (excluded by default).
• --include-hidden — include hidden sessions (excluded by default).
• --only-hidden — only hidden sessions. Mutually exclusive with --include-hidden.
• --spawned-by <ID|self|parent> — filter to direct child sessions spawned by the given session ID. self is the current session (= my children); parent is the session that spawned the current one (= my siblings, myself included). Implies --include-hidden. Mutually exclusive with --spawn-tree and --descendants.
• --spawn-tree <ID|self> — filter to every session in the spawn tree that contains the given session ID. Any id in the tree works — root, middle, or leaf: the CLI looks it up and resolves to the tree it belongs to. A standalone session (no children, never spawned) queried by its own id is returned as a single-node tree. self resolves to the tree that contains the current session. Implies --include-hidden. Mutually exclusive with --spawned-by and --descendants.
• --descendants <ID|self|parent> — filter to the proper descendants of the given session (every session transitively spawned by it, target excluded). self is the current session; parent is the current session's spawner (= my siblings, their subtrees, and my own subtree). Implies --include-hidden. Mutually exclusive with --spawned-by and --spawn-tree. Use this when you want "everything under X" but not X itself — --spawn-tree gives the whole tree containing X (root included), --spawned-by only direct children.
• --siblings <ID|self> — filter to the siblings of the given session: the other sessions spawned by the same parent, target always excluded. self is the current session's peers. parent is not supported (siblings are relative to a node's own parent). Implies --include-hidden. Mutually exclusive with --spawned-by, --spawn-tree and --descendants. This is the direct way to list your peers; --spawned-by parent selects the same set but includes yourself.
• --annotation KEY[OP]VALUE — filter to sessions whose annotations object matches the expression. Repeatable; multiple flags are AND-combined. Does not imply --include-hidden (orthogonal). Five operators:
  • KEY=VALUE — annotation key equals VALUE.
  • KEY!=VALUE — annotation key differs from VALUE (or key absent).
  • KEY:exists — annotation key is present (any value).
  • KEY:not-exists — annotation key is absent.
  • KEY:in:V1,V2,... — annotation key equals one of the listed values; escape a literal comma with \,.
  • Values are inferred as typed: true/false → boolean, null → null, integers and floats parsed numerically, everything else → string (same rules as create-session --annotation).
  • Example: --spawn-tree self --annotation role=implementer

Batch lookup

$TWICC sessions get <SESSION_ID> [<SESSION_ID>...]

Returns one entry per id in input order (duplicates collapsed). No filter flags — all session types returned.

Output format

Listing

[
  {
    "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

• provider — "claude_code" or "codex". Determines item schema and supported settings.
• 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.

Batch lookup (get)

Same shape per entry, plus known boolean. When known: false, all other fields are null.

[
  {"id": "abc123-def456", "title": "Implement user authentication", ..., "known": true},
  {"id": "typo-or-unknown", "title": null, ..., "known": false}
]

Examples

$TWICC sessions
$TWICC sessions --project .
$TWICC sessions --project /home/twidi/dev/myproj
$TWICC sessions --workspace backend
$TWICC sessions --include-archived
$TWICC sessions --spawned-by self
$TWICC sessions --spawned-by parent
$TWICC sessions --spawn-tree self
$TWICC sessions --descendants self
$TWICC sessions --descendants parent
$TWICC sessions --siblings self
$TWICC sessions --limit 50 --offset 20
$TWICC sessions --annotation role=implementer
$TWICC sessions --spawn-tree self --annotation role=implementer
$TWICC sessions --annotation status:exists --annotation priority:in:high,critical
$TWICC sessions get abc123-def456
$TWICC sessions get abc123 def456 ghi789

Related commands

• $TWICC session <session_id> — full metadata for one session (exit 1 if missing). Skill: twicc-session.
• $TWICC topology <ID|self> — map a spawned-session tree. Skill: twicc-topology.
• $TWICC project <PROJECT> / $TWICC projects — project details or listing. Skill: twicc-project / twicc-projects.
• $TWICC search "<query>" — full-text search across sessions. Skill: twicc-search.

How to present results

1. Show session title, date, and message count.
2. If there are more results, offer to paginate with --offset.
3. You are in TwiCC — link to a session: [link text](/project/{project_id}/session/{session_id}).
4. Only include cost and model info if explicitly asked.
5. For get output: flag known: false entries as unknown (typo or already cleaned up).