genbox-agent

genbox-agent

Unified daemon for monitoring and controlling AI CLI sessions (Claude Code, Gemini CLI, OpenAI Codex) locally or in remote VMs.

Installation

You typically don't need to install this manually. Both the Genbox CLI and Genbox Desktop app will automatically install and manage the daemon for you.

If you want to install it globally (optional):

npm install -g genbox-agent

Quick Start

The daemon is typically started automatically by:

• Genbox Desktop: Launches daemon on app startup
• Genbox CLI: Uses npx genbox-agent on demand

To start manually:

genbox-agent --native --server

Usage

# Show version
genbox-agent --version

# Show help
genbox-agent --help

# Start daemon with HTTP/WebSocket server (for desktop app)
genbox-agent --native --server

# Start daemon without server
genbox-agent --native

# Custom port
genbox-agent --native --server --port 8080

Features

• Multi-Provider Support: Works with Claude Code, Gemini CLI, and OpenAI Codex
• Session Management: Create, monitor, and control AI CLI sessions
• Real-time Sync: Syncs session data from Claude Code's JSONL files
• HTTP/WebSocket API: REST API and real-time events for desktop apps
• State Tracking: Monitors session states (thinking, tool_use, waiting_for_input)

API Endpoints

When running with --server, the daemon exposes:

Endpoint	Method	Description
/health	GET	Health check and version info
/api/sessions	GET	List all sessions
/api/sessions/:id	GET	Get session details
/api/sessions/:id/messages	GET	Get session messages
/api/sessions/:id/prompt	POST	Send prompt to session

Configuration

Environment Variables

Variable	Description
GENBOX_ID	Instance ID (for cloud mode)
GENBOX_TOKEN	Auth token (for cloud mode)

CLI Options

Option	Description
--native	Run in local mode (no cloud connection)
--server	Enable HTTP/WebSocket server
--port <port>	Server port (default: 47191)
--control-token	Authentication token for API
--no-sync	Disable background sync

Requirements

• Node.js >= 18.0.0
• One or more AI CLIs installed:
  • Claude Code
  • Gemini CLI
  • OpenAI Codex CLI

How It Works

• Session Discovery: Detects active AI CLI sessions via dtach sockets
• JSONL Sync: Reads Claude Code's conversation files from ~/.claude/projects/
• State Inference: Tracks session states from JSONL content and file modification times
• Event Broadcasting: Emits real-time events via WebSocket for UI updates

Data Storage

• Database: SQLite at ~/.genbox/data/agent.db
• Logs: ~/.genbox/daemon.log
• Lock files: ~/.genbox/locks/

License

MIT