Claudette Runner

Distributed conversation runner for Claudette that executes Claude conversations on behalf of remote workspaces.

Overview

The Runner App is an npm module that:

• Receives messages from the orchestrator via ElectricSQL-synced collections
• Sends responses to the orchestrator via HTTP POST with JSONRPC format
• Manages GitHub repository checkouts per workspace
• Executes Claude conversations using the claude-code-sdk-ts

Installation

npm install -g @claudette/runner
# or
npx @claudette/runner start

Quick Start

Required Environment Variables

# Authentication token from the server
export CLAUDETTE_RUNNER_TOKEN="your-auth-token"

# Root directory for Git checkouts (optional, defaults to /workspace)
export CLAUDETTE_WORKSPACE_DIR="/path/to/workspace/root"

# ElectricSQL endpoint for live updates
export CLAUDETTE_ELECTRICSQL_URL="https://your-electric-url"

# Orchestrator API endpoint
export CLAUDETTE_ORCHESTRATOR_URL="https://your-orchestrator-url"

Starting the Runner

# Start with default configuration
npx claudette-runner start

# Start with custom config file
npx claudette-runner start --config runner-config.json

# Enable debug logging
npx claudette-runner start --debug

# Override workspace directory
npx claudette-runner start --workspace-dir /custom/workspace

# Override specific settings
npx claudette-runner start --runner-id "my-runner" --max-concurrent 10

CLI Options

npx claudette-runner --help

Options:
  -V, --version                output the version number
  -c, --config <path>          path to configuration file
  -d, --debug                  enable debug logging
  --data-dir <path>            override data directory
  --workspace-dir <path>       workspace directory for Git checkouts (default: /workspace)
  --runner-id <id>             override runner ID
  -h, --help                   display help for command

Commands:
  start                        start the runner (default)
  validate                     validate configuration without starting

Configuration

Configuration File (optional)

Create a runner-config.json file:

{
  "runnerId": "runner-1",
  "dataDir": "./data"
}

Environment Variables

| Variable | Required | Description | | ---------------------------- | -------- | ------------------------------------------------------ | | CLAUDETTE_RUNNER_TOKEN | Yes | Authentication token from server | | CLAUDETTE_WORKSPACE_DIR | No | Root directory for Git checkouts (default: /workspace) | | CLAUDETTE_ELECTRICSQL_URL | Yes | ElectricSQL endpoint | | CLAUDETTE_ORCHESTRATOR_URL | Yes | Orchestrator API endpoint | | CLAUDETTE_DATA_DIR | No | Override data directory | | DEBUG | No | Enable debug logging |

Programmatic

import { RunnerApp, ConfigManager } from "@claudette/runner";

// Load configuration
const config = await ConfigManager.loadConfig();

// Create and start runner
const runner = new RunnerApp(config);
await runner.start();

// Graceful shutdown
process.on("SIGTERM", async () => {
  await runner.stop();
  process.exit(0);
});

Features

• Hybrid Communication: Receives messages via ElectricSQL, sends via HTTP
• Repository Isolation: Separate Git checkouts per workspace
• Automatic Recovery: Retry logic with exponential backoff
• Comprehensive Logging: Winston-based logging with file rotation
• Graceful Shutdown: Handles signals properly
• Resource Management: Automatic cleanup and limits

Logging

Logs are written to:

• Console (colored output)
• {dataDir}/logs/combined.log - All logs
• {dataDir}/logs/error.log - Errors only
• {dataDir}/logs/debug.log - Debug logs (when debug enabled)

Architecture

The runner consists of several key components:

1. RunnerApp - Main entry point and lifecycle manager
2. MessageHandler - Processes incoming JSONRPC messages via ElectricSQL
3. ClaudeManager - Manages Claude conversations using claude-code-sdk-ts
4. RepositoryManager - Manages Git repository checkouts and workspace isolation

The runner operates as a standalone process that:

• Receives messages from orchestrator via ElectricSQL-synced collections
• Sends responses to orchestrator via HTTP POST
• Manages GitHub repository checkouts per workspace
• Executes Claude conversations using claude-code-sdk-ts

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

License

MIT