gb session

Manage AI CLI sessions across local and cloud genboxes. The session command provides comprehensive tools for monitoring, controlling, and orchestrating multiple AI sessions.

Shortcut


gbs      # Equivalent to: gb session
gbsd     # Equivalent to: gb session --direct

Synopsis


gb session [session-name]
gb session <subcommand> [options]

Description

The session command is the central hub for AI session management. It allows you to:

List all running sessions across local and cloud environments
Watch sessions in real-time with a TUI or JSON streaming
View detailed session information and metrics
Stream session logs and transcripts
Send prompts to running sessions without attaching
Attach to, stop, or kill sessions

Subcommands

Subcommand	Description
`list`	List all sessions
`watch`	Real-time session monitoring
`show`	Detailed session information
`logs`	View session transcript and events
`send`	Send prompt to a running session
`attach`	Attach to a session
`start`	Start a new session
`stop`	Stop a session
`kill`	Kill/destroy a session

list

List all AI sessions across local and cloud environments.

Usage


gb session list [options]
gb session ls [options]

Options

Option	Description
`-l, --local`	Show only local sessions
`-c, --cloud`	Show only cloud sessions
`-d, --direct`	Show only direct (native) sessions
`-g, --genbox`	Show only local genbox sessions
`-a, --all`	Show all sessions including stopped
`--synced`	Show only API-synced sessions
`--json`	Output as JSON

Examples


# List all running sessions
gb session list
 
# JSON output for automation
gb session ls --json
 
# Show only cloud sessions
gb session list --cloud

watch

Real-time monitoring of all sessions with TUI or JSON streaming. Essential for orchestrating multiple AI agents.

Usage


gb session watch [options]

Options

Option	Description
`--json`	Output JSON snapshot and exit
`--stream`	Stream NDJSON updates continuously
`-i, --interval <seconds>`	Refresh interval (default: 3)
`--provider <provider>`	Filter by provider (claude, gemini, codex)
`--status <status>`	Filter by status (running, idle, stopped)
`--genbox <name>`	Filter by genbox name

Examples


# TUI mode with live updates
gb session watch
 
# JSON snapshot for scripts
gb session watch --json
 
# NDJSON streaming for AI agent orchestration
gb session watch --stream
 
# Filter by provider
gb session watch --provider claude
 
# Custom refresh interval
gb session watch -i 5

JSON Output Format


{
  "type": "snapshot",
  "timestamp": "2025-01-02T10:30:00Z",
  "sessions": [
    {
      "id": "a1b2c3d4",
      "name": "claude-swift-fox",
      "provider": "claude",
      "type": "cloud",
      "genbox": "dusty-summit",
      "status": "running",
      "state": "executing_tool",
      "currentTool": "Edit",
      "duration": "15m",
      "tokens": 45.2
    }
  ]
}

Streaming Events

When using --stream, events are emitted as newline-delimited JSON:


{"type":"snapshot","timestamp":"...","sessions":[...]}
{"type":"state_change","sessionId":"a1b2c3","currentState":"thinking"}
{"type":"session_started","session":{...}}
{"type":"session_ended","sessionId":"a1b2c3"}

show

Display detailed information about a specific session including metrics, token usage, file changes, and cost.

Usage


gb session show <session> [options]

Arguments

Argument	Description
`session`	Session name or ID (prefix match supported)

Options

Option	Description
`--json`	Output as JSON

Examples


# Detailed view
gb session show claude-swift-fox
 
# By ID prefix
gb session show a1b2c3
 
# JSON output
gb session show claude-swift-fox --json

Output

Shows a formatted view with:

Status: Current session status and state
Provider: AI provider and model
Genbox: Where the session is running
Metrics: Duration, tokens, cost, messages, tool usage
File Changes: Modified, created, deleted files
Last Message: Preview of most recent activity

logs

View session transcript and activity logs. Supports follow mode for real-time streaming.

Usage


gb session logs <session> [options]

Arguments

Argument	Description
`session`	Session name or ID

Options

Option	Description
`-f, --follow`	Follow mode - continuously show new activity
`-n, --tail <lines>`	Number of messages to show (default: 50)
`--events`	Show events instead of messages
`--tools`	Show only tool executions (with -f)
`--json`	Output as JSON

Examples


# View transcript
gb session logs claude-swift-fox
 
# Follow mode (like tail -f)
gb session logs claude-swift-fox -f
 
# Show events stream
gb session logs claude-swift-fox --events
 
# Follow only tool executions
gb session logs claude-swift-fox -f --tools
 
# JSON output
gb session logs abc123 --json

Output Format


[15:32:01] 💬 User: Fix the auth bug in token refresh
[15:32:03] 🤖 Assistant: I'll analyze the token refresh logic...
[15:32:05] ⚙  Tool: Read src/auth/token.ts
[15:32:06] ⚙  Tool: Edit src/auth/token.ts (+15/-3)
[15:32:08] 🤖 Assistant: I've fixed the token refresh by...
[15:32:10] ⌛ Waiting for input...

Note: Full transcript requires sessions to be started with --sync flag. Local-only sessions show basic info.

send

Send a prompt to a running session without attaching. Essential for AI orchestration workflows.

Usage


gb session send <session> [prompt] [options]

Arguments

Argument	Description
`session`	Session name or ID
`prompt`	Prompt text (or use -f/-e)

Options

Option	Description
`-f, --file <path>`	Read prompt from file
`-e, --editor`	Open $EDITOR to compose prompt
`--json`	Output result as JSON

Examples


# Send inline prompt
gb session send claude-swift-fox "Add unit tests for the changes"
 
# Send from file
gb session send claude-swift-fox -f prompt.txt
 
# Open editor for complex prompts
gb session send claude-swift-fox -e
 
# JSON output for automation
gb session send abc123 "Fix the bug" --json

JSON Response


{
  "success": true,
  "message": "Prompt sent to claude-swift-fox",
  "session": "claude-swift-fox",
  "promptLength": 35
}

attach

Attach to a running session to interact with it directly.

Usage


gb session attach <session>

Examples


# Attach to session
gb session attach claude-swift-fox
 
# Detach with Ctrl+\

start

Start a new AI session.

Usage


gb session start [options]

Options

Option	Description
`-c, --cloud`	Create cloud session
`--vm`	Use local VM (Multipass)
`--docker`	Use local Docker
`--direct`	Run directly on host (no isolation)
`--claude`	Use Claude provider
`--gemini`	Use Gemini provider
`--codex`	Use Codex provider
`-p, --prompt <prompt>`	Initial prompt
`-w, --workdir <dir>`	Working directory
`--sync`	Enable API sync for recording

Examples


# Interactive start
gb session start
 
# Start with specific provider and location
gb session start --claude --cloud
 
# With initial prompt
gb session start --claude --prompt "Fix the auth bug"

Orchestration Workflow

Here’s a complete workflow for orchestrating multiple AI sessions:


# 1. Start multiple background sessions
gb claude -p -b "Fix auth bug" --on fuzzy-quartz
gb gemini -p -b "Add unit tests" --on cool-ice
 
# 2. Monitor all sessions
gb session watch
 
# 3. Or use JSON streaming for AI orchestration
gb session watch --stream | python orchestrator.py
 
# 4. Check specific session status
gb session show claude-swift-fox
 
# 5. View what a session is doing
gb session logs claude-swift-fox -f
 
# 6. Send additional prompts
gb session send claude-swift-fox "Now commit the changes"
 
# 7. Attach when needed
gb session attach claude-swift-fox

Session Types

Type	Description
`native`	Direct session on local machine (no isolation)
`docker`	Local Docker container session
`multipass`	Local Multipass VM session
`cloud`	Remote cloud genbox session
`genbox`	Local genbox with full infrastructure

Session States

When sessions are synced to API, they track real-time state:

State	Description
`waiting_for_input`	Waiting for user prompt
`thinking`	Processing/generating response
`executing_tool`	Running a tool (Read, Edit, Bash, etc.)
`responding`	Streaming response to user

API Sync

For full session recording and monitoring, start sessions with --sync:


gb session start --sync
gb claude --sync

This enables:

Full transcript recording
Token and cost metrics
File change tracking
Real-time state monitoring
Remote prompt injection

gb session

Shortcut

Synopsis

Description

Subcommands

list

Usage

Options

Examples

watch

Usage

Options

Examples

JSON Output Format

Streaming Events

show

Usage

Arguments

Options

Examples

Output

logs

Usage

Arguments

Options

Examples

Output Format

send

Usage

Arguments

Options

Examples

JSON Response

attach

Usage

Examples

start

Usage

Options

Examples

Orchestration Workflow

Session Types

Session States

API Sync

See Also