Session Management Guide

Gobby sessions are durable records of CLI and web-chat work. They connect transcripts, tasks, commits, handoff summaries, token usage, terminal state, and agent-run metadata across daemon restarts and context compactions.

Quick Start

# List recent sessions
gobby sessions list

# Show one session
gobby sessions show #42

# Read a transcript
gobby sessions messages #42 --limit 25

# Create a handoff summary for the current active session
gobby sessions create-handoff --output db "Paused before review"

# MCP examples assume progressive discovery has already loaded the server,
# tool list, and schema.

# Get your current session when injected context did not include it.
call_tool("gobby-sessions", "get_current_session", {
    "external_id": "<cli-session-id>",
    "source": "codex"
})

# Read the latest handoff-ready context.
call_tool("gobby-sessions", "get_handoff_context", {})

Mental Model

stateDiagram-v2
    [*] --> active: registered
    active --> paused: turn ends
    paused --> active: next turn
    active --> handoff_ready: compact or handoff
    paused --> handoff_ready: handoff
    active --> completed: web chat cleared
    active --> expired: session end or stale
    paused --> expired: stale
    handoff_ready --> expired: orphaned or stale

Status	Meaning
`active`	A session is registered and currently expected to receive activity.
`paused`	A turn finished or the session went idle, but the session may resume.
`handoff_ready`	Summary context is available for a successor session.
`completed`	A web-chat lifecycle ended cleanly.
`expired`	The session ended, went stale, or was soft-deleted.

Session records are keyed by external CLI identity, machine, source, project, and session type. Registration is idempotent for that key, so daemon restarts reuse the existing row instead of creating duplicates.

What A Session Stores

Field group	Examples
Identity	Internal UUID, project-scoped `#N`, external CLI ID, machine ID, source
Runtime	Status, source, session type, terminal context, parent session, agent depth
Work trace	Transcript path, rendered message counts, task links, commit window
Handoff	`summary_markdown`, digest fields, compact continuation context
Usage	Input, output, cache-write, cache-read token counts, model
Safety	Dirty-file baseline, edit marker, sandbox flags, approved tools

agent_depth separates human sessions from spawned agent sessions. Depth 0 sessions are user-facing; depth 1+ sessions are subagents and are cheaper to summarize during lifecycle processing.

Session Sources

Source	Typical origin
`claude`	Claude Code hooks
`codex`	Codex hook adapter or web-chat Codex backend
`gemini`	Gemini CLI hooks
`qwen`	Qwen CLI hooks
`droid`	Droid CLI hooks
`pipeline`	Pipeline automation
`system`	Bootstrapped root session for cron and pipeline work without a caller

The public get_current_session helper accepts claude, gemini, qwen, codex, and droid. Pipeline and system sessions are created by internal automation.

CLI Commands

`gobby sessions list`

List sessions with optional filters.

gobby sessions list [OPTIONS]

Option	Description
`-p, --project TEXT`	Filter by project name or UUID.
`-s, --status TEXT`	Filter by status such as `active`, `completed`, or `handoff_ready`.
`--source TEXT`	Filter by `claude`, `gemini`, `qwen`, `codex`, or `droid`.
`-n, --limit INTEGER`	Maximum rows to show.
`--json`	Emit JSON.

`gobby sessions show`

Show one session by #N, UUID, or prefix.

gobby sessions show SESSION_ID [--json]

`gobby sessions messages`

Render transcript messages from the live JSONL transcript or gzip archive fallback.

gobby sessions messages SESSION_ID [OPTIONS]

Option	Description
`-n, --limit INTEGER`	Maximum messages to show.
`-r, --role TEXT`	Filter by role: `user`, `assistant`, or `tool`.
`-o, --offset INTEGER`	Skip the first N messages.
`--json`	Emit JSON.

`gobby sessions stats`

Show aggregate counts by status and source.

gobby sessions stats [--project TEXT]

`gobby sessions create-handoff`

Create a handoff summary for a session. If --session-id is omitted, Gobby uses the current project's most recent active session.

gobby sessions create-handoff [OPTIONS] [NOTES]

Option	Description
`-s, --session-id TEXT`	Session to summarize.
`--output db\|file\|all`	Save to DB, file, or both. Default: `all`.
`--path TEXT`	Directory for file output. Default: `.gobby/session_summaries/`.

The command extracts active task, modified files, git status, recent commits, initial goal, recent activity, and a summary. It uses an LLM summary when available and falls back to code-derived context.

`gobby sessions restore`

Restore transcript files from gzip archives.

gobby sessions restore SESSION_REF [--path TEXT] [--json]
gobby sessions restore --all [--json]

Use this when a CLI deleted its original transcript file but you need the file back on disk for resume or inspection.

`gobby sessions delete`

Delete a session after confirmation.

gobby sessions delete SESSION_ID
gobby sessions delete SESSION_ID --yes

MCP Tools

Use the gobby-sessions server for session CRUD, transcripts, handoffs, registration, usage, terminal capture, and archive restoration. Fetch schemas with get_tool_schema before writing examples or automating calls.

Tool	Purpose
`get_current_session`	Resolve your own internal session ID from external CLI ID and source.
`get_session`	Read one session by `#N`, UUID, or prefix.
`list_sessions`	Browse sessions with project, status, source, and limit filters.
`session_stats`	Count sessions by status and source.
`get_usage_breakdown`	Aggregate token usage by source and model.
`get_session_messages`	Read rendered transcript messages.
`search_messages`	Deprecated; returns an unavailable error because DB message search was removed.
`set_handoff_context`	Set or generate handoff context for the current session.
`get_handoff_context`	Retrieve handoff context directly or from the latest `handoff_ready` session.
`register_session`	Register hookless clients such as SDK-driven agents.
`get_session_commits`	List commits made during a session timeframe.
`mark_loop_complete`	Mark an autonomous loop complete to prevent session chaining.
`capture_baseline_dirty_files`	Store the current dirty-file baseline for edit detection.
`restore_session_transcript`	Restore one transcript from archive.
`get_transcript_status`	Check archive availability and transcript file stats.
`send_keys`	Send keystrokes to a session-backed tmux terminal.
`capture_output`	Capture recent tmux output.
`compact_self`	Trigger the current CLI's compaction command.

Finding Your Own Session

Use get_current_session when injected context did not already provide a session reference.

call_tool("gobby-sessions", "get_current_session", {
    "external_id": "<external-id-from-context-or-GOBBY_SESSION_ID>",
    "source": "codex"
})

Do not use list_sessions(status="active", limit=1) for self-identification. Multiple terminals and agents can be active at the same time.

Reading Session Data

call_tool("gobby-sessions", "get_session", {
    "session_id": "#42"
})

call_tool("gobby-sessions", "get_session_messages", {
    "session_id": "#42",
    "limit": 50,
    "offset": 0,
    "full_content": False
})

call_tool("gobby-sessions", "get_session_commits", {
    "session_id": "#42",
    "max_commits": 25
})

Creating And Reading Handoffs

set_handoff_context operates on the current session context. Pass content for an agent-authored handoff, or omit it to generate a summary from transcript state.

call_tool("gobby-sessions", "set_handoff_context", {
    "content": "## Handoff\n\nCurrent state and next steps.",
    "set_handoff_ready": True
})

call_tool("gobby-sessions", "get_handoff_context", {
    "session_id": "#42",
    "link_child_session_id": "#43"
})

When no session_id is provided, get_handoff_context falls back to the most recent handoff_ready session. It can also search by project_id and source.

Hookless Registration

Clients that do not fire session-start hooks can register explicitly.

call_tool("gobby-sessions", "register_session", {
    "external_id": "<sdk-run-id>",
    "source": "codex",
    "title": "SDK driven analysis",
    "agent_depth": 0
})

machine_id and project_id are auto-resolved when omitted.

Terminal Tools

Terminal tools are for session-backed tmux contexts.

call_tool("gobby-sessions", "capture_output", {
    "session_id": "#42",
    "lines": 80
})

call_tool("gobby-sessions", "send_keys", {
    "session_id": "#42",
    "keys": "status\n",
    "literal": True
})

Use capture_output before raw tmux fallback when inspecting prompts, permission dialogs, or stalled terminals.

Handoff Flow

sequenceDiagram
    participant Parent
    participant Gobby
    participant Child

    Parent->>Gobby: set_handoff_context or create-handoff
    Gobby->>Gobby: store summary_markdown
    Gobby->>Gobby: mark parent handoff_ready
    Child->>Gobby: get_handoff_context
    Gobby->>Child: return context
    Gobby->>Gobby: optionally link child to parent

Handoffs are summary records, not separate session objects. A parent session is marked handoff_ready, and a successor reads summary_markdown through get_handoff_context. If link_child_session_id is provided, Gobby records the parent-child relationship.

Lifecycle Events

Rule authors should target semantic workflow events:

Semantic event	Raw runtime events that may feed it	Common use
`turn_start`	`before_agent`, provider-specific prompt-start events	Context injection and per-turn setup
`turn_end`	`after_agent`, `stop`, provider-specific turn-complete events	Stop gates, digest capture, cleanup

Raw before_agent, after_agent, and stop events are provider/runtime details. They are useful for adapter work, but they are not the main authoring API for portable workflow rules.

Agent termination is a separate lifecycle path. A spawned agent that has finished successfully must call gobby-agents:end_agent_run; relying on a raw stop or turn-end event does not release the agent run.

Troubleshooting

Session Not Found

Check daemon health with gobby status.
Confirm the project. Project-scoped #N references resolve inside the current project.
For self-lookup, use get_current_session with the external CLI ID and source.
For old sessions, try UUID or prefix if the project-scoped number is ambiguous.

Messages Are Missing

Use gobby sessions show SESSION_ID --json and inspect transcript_path.
Run gobby sessions restore SESSION_ID if the transcript archive exists but the original file was deleted.
Use get_transcript_status through MCP to check archive availability.

Handoff Is Empty

Confirm the parent has summary_markdown.
Create or update handoff context with gobby sessions create-handoff or set_handoff_context.
Confirm the parent status is handoff_ready.
Pass session_id to get_handoff_context when multiple handoff-ready sessions exist.

Hooks Are Not Updating Sessions

Verify hooks are installed with gobby install.
Check the CLI source in gobby sessions list --source SOURCE.
Review daemon logs under ~/.gobby/logs/.
For hookless clients, use register_session.

Data Storage

Path	Description
`~/.gobby/bootstrap.yaml` `database_url`	Runtime PostgreSQL hub DSN for sessions and related tables.
`~/.gobby/logs/`	Daemon logs.
`.gobby/session_summaries/`	Default file output for CLI-created handoff summaries.

Navigation Menu

Uh oh!

Session Management Guide

Quick Start

Mental Model

What A Session Stores

Session Sources

CLI Commands

`gobby sessions list`

`gobby sessions show`

`gobby sessions messages`

`gobby sessions stats`

`gobby sessions create-handoff`

`gobby sessions restore`

`gobby sessions delete`

MCP Tools

Finding Your Own Session

Reading Session Data

Creating And Reading Handoffs

Hookless Registration

Terminal Tools

Handoff Flow

Lifecycle Events

Troubleshooting

Session Not Found

Messages Are Missing

Handoff Is Empty

Hooks Are Not Updating Sessions

Data Storage

See Also

Uh oh!

FilesExpand file tree

sessions.md

Latest commit

History

sessions.md

File metadata and controls

Session Management Guide

Quick Start

Mental Model

What A Session Stores

Session Sources

CLI Commands

gobby sessions list

gobby sessions show

gobby sessions messages

gobby sessions stats

gobby sessions create-handoff

gobby sessions restore

gobby sessions delete

MCP Tools

Finding Your Own Session

Reading Session Data

Creating And Reading Handoffs

Hookless Registration

Terminal Tools

Handoff Flow

Lifecycle Events

Troubleshooting

Session Not Found

Messages Are Missing

Handoff Is Empty

Hooks Are Not Updating Sessions

Data Storage

See Also

`gobby sessions list`

`gobby sessions show`

`gobby sessions messages`

`gobby sessions stats`

`gobby sessions create-handoff`

`gobby sessions restore`

`gobby sessions delete`