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):

``bash
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:

`bash
genbox-agent --native --server
`

Usage

`bash


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

$3

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

$3

| Option | Description |
|--------|-------------|
| --native | Run in local mode (no cloud connection) |
| --server | Enable HTTP/WebSocket server |
| --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