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

1. Session Discovery: Detects active AI CLI sessions via dtach sockets
2. JSONL Sync: Reads Claude Code's conversation files from ~/.claude/projects/
3. State Inference: Tracks session states from JSONL content and file modification times
4. 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