gb claude

Start or attach to a Claude AI session. Claude is Anthropic’s AI assistant, ideal for coding tasks, analysis, and complex problem-solving.

Shortcut


gbc      # Equivalent to: gb claude
gbcd     # Equivalent to: gb claude --direct

Synopsis


gb claude [options]
gb claude [subcommand] [args]

Description

The claude command provides a streamlined interface to start Claude Code sessions on genboxes (cloud or local) or directly on your machine. Sessions are persistent and can be detached/reattached using dtach.

Options

Option	Description
`--on <genbox>`	Use a specific genbox
`--direct`	Run directly on this machine (no isolation)
`-y, --yes`	Skip confirmation prompts
`-p, --prompt-mode`	Interactive prompt mode with optional images
`-e, --editor`	Use $EDITOR for prompt input (with -p)
`-b, --background`	Run session in background (with -p)

Subcommands

Subcommand	Description
`list`	List all Claude sessions
`attach <session>`	Attach to an existing session
`stop <session>`	Stop a session
`kill <session>`	Kill/destroy a session
`migrate <session>`	Migrate session to another genbox

Examples

Basic Usage


# Interactive mode - shows menu to select genbox
gb claude
 
# Use a specific genbox
gb claude --on dusty-summit
 
# Run directly on your machine (no isolation)
gb claude --direct

Prompt Mode

Prompt mode (-p) allows you to compose a multi-line prompt with optional images before starting the session:


# Interactive prompt mode
gb claude -p
 
# Use editor for complex prompts
gb claude -p -e
 
# Background mode - start session and return immediately
gb claude -p -b

Background Sessions

Background mode is essential for orchestration. The session runs in the background while you continue working:


# Start background session with prompt
gb claude -p -b
 
# You'll see:
# ✓ Session created: claude-abc123
# Session running in background.
# Attach with: gb claude attach claude-abc123

Session Management


# List all Claude sessions
gb claude list
 
# Attach to existing session
gb claude attach claude-swift-fox
 
# Stop a session (keeps socket)
gb claude stop claude-swift-fox
 
# Kill a session completely
gb claude kill claude-swift-fox

Image Support

When using prompt mode, you can include local images that will be automatically uploaded to the genbox:


# Start prompt mode
gb claude -p
 
# In the prompt interface:
# > Analyze this screenshot
# > /path/to/screenshot.png
# > (empty line to finish)

Workflow Examples

Feature Development


# Create a genbox for your feature
gb create feature-auth --profile full-stack
 
# Start Claude session
gb claude --on feature-auth
 
# Claude will have access to your codebase and can:
# - Read and edit files
# - Run commands
# - Analyze code
# - Make git commits

Parallel AI Workers


# Start multiple background sessions on different tasks
gb claude -p -b --on genbox-1
# Enter: "Implement user authentication"
 
gb claude -p -b --on genbox-2
# Enter: "Write unit tests for the API"
 
# Monitor all sessions
gb session watch
 
# Send follow-up prompts
gb session send claude-abc123 "Now add password reset"

Quick Fix


# Start session with inline prompt
gb claude -p -b --on my-genbox
# Enter prompt: "Fix the TypeScript error in src/auth/token.ts"
 
# Monitor progress
gb session logs claude-abc123 -f

Session Persistence

Sessions use dtach for persistence:

Detach: Press Ctrl+\ to detach (session keeps running)
Reattach: Use gb claude attach <session-name>
List sessions: Use gb claude list or gb session list

Best Practices

Use genboxes for isolation - protects your local environment
Enable sync (--sync) when you need session recording
Use background mode (-p -b) for orchestration workflows
Name your sessions meaningfully for easier management

Environment

Claude sessions run with:

--dangerously-skip-permissions flag (auto-approve tool usage)
Full access to the genbox filesystem
Ability to run shell commands
Git integration for commits