SessionCast CLI

Node.js agent and CLI for SessionCast — a real-time terminal sharing and AI agent orchestration platform.

SessionCast enables any AI coding agent (Claude Code, Gemini CLI, Codex, Cursor, Aider) to control other agents across machines through tmux sessions.

Installation

npm install -g sessioncast-cli

Requirements: Node.js 18+, tmux (Linux/macOS) or itmux (Windows)

Windows Setup

# Install itmux
Invoke-WebRequest -Uri "https://github.com/itefixnet/itmux/releases/download/v1.1.0/itmux_1.1.0_x64_free.zip" -OutFile "$env:TEMP\itmux.zip"
Expand-Archive -Path "$env:TEMP\itmux.zip" -DestinationPath "C:\itmux" -Force

# Install SessionCast CLI
npm install -g sessioncast-cli

Use PowerShell in tmux sessions (recommended)

By default, itmux opens sessions with bash. Sessions created by SessionCast automatically use PowerShell, but if you also want PowerShell when using itmux manually:

# Create tmux config to use PowerShell as default shell
$tmuxConf = "C:\itmux\home\$env:USERNAME\.tmux.conf"
New-Item -Path $tmuxConf -ItemType File -Force
Add-Content -Path $tmuxConf -Value 'set-option -g default-command "powershell.exe"'

# For PowerShell 7+ (pwsh), use this instead:
# Add-Content -Path $tmuxConf -Value 'set-option -g default-command "pwsh.exe"'

Quick Start

1. Login

# Browser-based OAuth (recommended)
sessioncast login

# Or with agent token
sessioncast login agt_your_token_here

2. Configure the agent

Create ~/.sessioncast.yml:

machineId: my-machine
relay: wss://relay.sessioncast.io/ws
token: agt_your_agent_token_here

3. Start the agent

# Background (recommended)
nohup sessioncast agent > /tmp/sessioncast-agent.log 2>&1 &

# Foreground (for debugging)
sessioncast agent

4. View your sessions

Open app.sessioncast.io to see your terminal sessions in real-time.

CLI Commands

Authentication

sessioncast login              # Browser-based OAuth login
sessioncast login agt_xxx      # Login with agent token
sessioncast login sk-xxx       # Login with API key
sessioncast logout             # Clear stored credentials
sessioncast status             # Check authentication status

Session Discovery

sessioncast list               # List all sessions across machines
sessioncast list dev-server    # Filter by machine name
sessioncast agents             # List registered agents

Example output:

Sessions:

AGENT                  SESSION      STATUS    TARGET
dev-macbook            workspace    online    dev-macbook/workspace
dev-macbook            worker1      online    dev-macbook/worker1
staging-server         main         online    staging-server/main

Send Keys

Send keystrokes to any remote tmux session:

# Send a command (Enter is pressed automatically)
sessioncast send workspace "npm run build"

# Target a specific machine
sessioncast send dev-macbook/workspace "git status"
sessioncast send dev-macbook:workspace "git status"    # colon works too

# Send without pressing Enter (for special keys)
sessioncast send workspace "C-c" --no-enter            # Ctrl+C
sessioncast send workspace "C-l" --no-enter            # Ctrl+L (clear)

Agent

sessioncast agent                          # Start agent
sessioncast agent -c /path/to/config.yml   # Custom config path

AI Agent Orchestration

SessionCast's key capability is enabling AI-to-AI orchestration. Any terminal-based AI agent can create tmux sessions, launch other AI agents, and send them tasks.

Launch an AI Worker

# Create a tmux session and launch an AI agent
tmux new-session -d -s worker1
sessioncast send worker1 "claude"          # or: gemini, codex, aider, cursor
sleep 5

# Send a task
sessioncast send worker1 "Implement input validation for the signup form in src/validators/signup.ts"

Supported AI Agents

| Agent | Launch Command | Best For | |-------|---------------|----------| | Claude Code | claude | Multi-file tasks, architecture | | Gemini CLI | gemini | Code review, analysis | | OpenAI Codex | codex | Code generation, testing | | Cursor CLI | cursor | Interactive editing | | Aider | aider | Git-aware pair programming | | GitHub Copilot | gh copilot | GitHub-integrated tasks |

Dev → QA → Deploy Pipeline

# Setup sessions with different AI agents
tmux new-session -d -s dev
tmux new-session -d -s qa
tmux new-session -d -s deploy
sessioncast send dev "claude"
sessioncast send qa "codex"
sessioncast send deploy "gemini"
sleep 10

# Stage 1: Development
sessioncast send dev "Implement GET /api/users/:id endpoint in src/routes/users.ts"

# Stage 2: QA (after dev completes)
sessioncast send qa "Run tests: npm test -- --grep 'user profile'. Report any failures."

# Stage 3: Deploy (after QA passes)
sessioncast send deploy "Deploy to staging: git pull && npm run build && pm2 restart api"

Dev ↔ QA Feedback Loop

# QA finds issues → send back to dev
sessioncast send dev "QA found: GET /api/users/:id returns 500 when user not found. Should return 404."

# Dev fixes → QA re-tests
sessioncast send qa "Re-run user profile tests: npm test src/__tests__/users.test.ts"

Multi-Agent Fan-Out

# Parallel development across multiple areas
tmux new-session -d -s frontend
tmux new-session -d -s backend
tmux new-session -d -s tests

sessioncast send frontend "claude"
sessioncast send backend "gemini"
sessioncast send tests "codex"
sleep 10

sessioncast send frontend "Build Settings page at src/pages/Settings.tsx with theme toggle and language selector"
sessioncast send backend "Create REST endpoints: GET/PUT /api/settings in src/routes/settings.ts"
sessioncast send tests "Write integration tests for the settings API in src/__tests__/settings.test.ts"

Cross-Machine Control

# Control agents on different servers
sessioncast send dev-macbook/workspace "npm run build"
sessioncast send staging-server/main "git pull && npm test"
sessioncast send prod-server/deploy "pm2 reload api"

For more orchestration patterns (code review pipeline, incident response, monorepo development), see docs/claude-to-claude.md.

Configuration

Agent Config (~/.sessioncast.yml)

# Required
machineId: my-machine
relay: wss://relay.sessioncast.io/ws
token: agt_your_agent_token_here

# Optional: API configuration
api:
  enabled: true
  agentId: "your-agent-uuid"
  exec:
    enabled: true
    shell: /bin/bash
    workingDir: /home/user
    defaultTimeout: 30000
  llm:
    enabled: false

Environment Variables

| Variable | Description | |----------|-------------| | SESSIONCAST_CONFIG | Custom config file path | | TMUX_REMOTE_CONFIG | Alternative config file path |

CLI Config

After sessioncast login, credentials are stored automatically in the system config directory (~/.config/sessioncast/). No manual config needed for send, list, and other CLI commands.

Features

Agent Capabilities

• Auto-discovery: Detects and connects all tmux sessions automatically
• Real-time streaming: Captures terminal output with gzip compression
• Multi-pane support: Detects tmux panes and streams each independently
• File viewer: Cmd+Click on file paths to view files in browser
• Circuit breaker: Prevents reconnection storms with exponential backoff (max 5 retries, 30s max delay, 2min cooldown)

Web Viewer (app.sessioncast.io)

• Real-time terminal rendering with xterm.js
• Multi-pane layout view
• Interactive keyboard input
• File viewer panel
• Session sharing via links
• Dark/light theme

Architecture

┌──────────────┐     WebSocket      ┌──────────────┐     WebSocket     ┌──────────────┐
│    Agent      │ ◄────────────────► │    Relay      │ ◄───────────────► │   Viewer     │
│  (sessioncast │   screen/keys     │ (relay.       │   screen/keys    │  (app.       │
│   agent)      │   paneLayout      │  sessioncast  │   paneLayout     │  sessioncast  │
│               │                   │  .io)         │                  │  .io)         │
└──────┬───────┘                    └──────────────┘                   └──────────────┘
       │
       │ tmux capture-pane / send-keys
       ▼
┌──────────────┐
│  tmux        │
│  sessions    │
│  (AI agents) │
└──────────────┘

Message flow:

1. Agent captures tmux screen → sends screen/screenGz via WebSocket
2. Relay forwards to all connected viewers
3. Viewer sends keys → Relay forwards to agent → Agent runs tmux send-keys
4. For multi-pane: Agent sends paneLayout + per-pane screen with meta.pane

Troubleshooting

Session not found

# Verify available sessions
sessioncast list

# Use the exact target from the TARGET column
sessioncast send my-machine/worker1 "hello"

Agent not connecting

# Check tmux is running
tmux ls

# Check agent logs
tail -f /tmp/sessioncast-agent.log

# Restart agent
pkill -f "sessioncast agent"
nohup sessioncast agent > /tmp/sessioncast-agent.log 2>&1 &

Authentication issues

# Re-login
sessioncast logout
sessioncast login

# Verify
sessioncast status

License

MIT License - see LICENSE for details.

Links

• Homepage: sessioncast.io
• Web App: app.sessioncast.io
• npm: sessioncast-cli
• GitHub: sessioncast/sessioncast-cli
• Email: [email protected]