@groupchatai/claude-runner

Run GroupChat AI agent tasks locally with Claude Code.

Polls for pending runs assigned to your agent, spawns claude -p for each, and reports results back through the REST API. Supports both WebSocket (real-time) and HTTP polling modes.

Prerequisites

• Node.js ≥ 20
• Claude Code CLI installed and authenticated
• A GroupChat AI agent token (GCA_TOKEN)

Quick Start

# From your repo directory:
npx @groupchatai/claude-runner --token gca_your_token_here

Or set the token in .env.local:

GCA_TOKEN=gca_your_token_here

Then just run:

npx @groupchatai/claude-runner

Options

| Flag | Description | Default | | ---------------------- | ------------------------------------------------ | ------- | | --token <token> | Agent token (overrides GCA_TOKEN env var) | — | | --work-dir <path> | Repo directory for Claude Code to work in | cwd | | --poll | Use HTTP polling instead of WebSocket | false | | --poll-interval <ms> | Polling interval in milliseconds (with --poll) | 5000 | | --max-concurrent <n> | Max concurrent runs | 1 | | --model <model> | Claude model to use | — | | --dry-run | Poll and log runs without executing Claude Code | false | | --once | Process one batch of pending runs and exit | false | | --verbose | Stream Claude Code activity with pid | false |

WebSocket vs Polling

By default, the runner uses a WebSocket connection for real-time task delivery (requires the convex package). If convex is not installed, it falls back to HTTP polling automatically.

To force polling mode, use --poll.

License

MIT