### Quick Start: Install and Run GolemBot

Source: https://0xranx.github.io/golembot

Install GolemBot globally using npm. Then, create a new bot directory, run the guided setup wizard, and start an interactive REPL or the gateway service.

```bash
npm install -g golembot

mkdir my-bot && cd my-bot
golembot onboard          # guided setup wizard
golembot run              # interactive REPL
golembot gateway          # start IM + HTTP service + Dashboard
golembot fleet ls         # list all running bots
golembot skill search "data analysis"  # browse community skills
```

--------------------------------

### Initialize and Onboard GolemBot

Source: https://0xranx.github.io/golembot/guide/onboard-wizard.html

Commands to create a new directory and start the interactive setup wizard.

```bash
mkdir my-bot && cd my-bot
golembot onboard
```

```bash
golembot onboard --template customer-support
```

--------------------------------

### Initialize a New GolemBot Project

Source: https://0xranx.github.io/golembot/guide/getting-started.html

Creates a new bot directory and runs the onboard wizard for guided setup. Use --template to specify a scenario template.

```bash
mkdir my-bot && cd my-bot
golembot onboard
```

--------------------------------

### List installed skills

Source: https://0xranx.github.io/golembot/guide/cli-commands.html

Displays all skills currently installed in the assistant directory.

```bash
golembot skill list [-d <dir>]
```

--------------------------------

### Install Feishu Node SDK

Source: https://0xranx.github.io/golembot/channels/feishu.html

Install the necessary SDK for Feishu integration using pnpm.

```bash
pnpm add @larksuiteoapi/node-sdk
```

--------------------------------

### Verify Agent Installation

Source: https://0xranx.github.io/golembot/reference/coding-cli-cursor.html

Check the installed version of the agent binary.

```bash
agent --version
```

--------------------------------

### Full Configuration Example (golem.yaml)

Source: https://0xranx.github.io/golembot/guide/configuration.html

A comprehensive example of a `golem.yaml` file, illustrating various configuration options for GolemBot.

```APIDOC
## Full Example 

```yaml
name: my-bot
engine: claude-code

groupChat:
  groupPolicy: smart
  historyLimit: 30
  maxTurns: 5

inbox:
  enabled: true
  retentionDays: 7

historyFetch:
  enabled: true
  pollIntervalMinutes: 15
  initialLookbackMinutes: 60

channels:
  slack:
    botToken: ${SLACK_BOT_TOKEN}
    appToken: ${SLACK_APP_TOKEN}

gateway:
  port: 3000
  token: ${GOLEM_TOKEN}
```
```

--------------------------------

### Full GolemBot Configuration Example

Source: https://0xranx.github.io/golembot/guide/configuration.html

This comprehensive example demonstrates all available configuration options for GolemBot, including engine settings, permissions, system prompts, performance tuning, scheduled tasks, and channel integrations. Use this as a reference for advanced customization.

```yaml
name: my-assistant
engine: claude-code          # cursor | claude-code | opencode | codex
model: claude-sonnet         # optional, preferred model

# Optional: bypass agent permission prompts
skipPermissions: true

# Optional: Codex runtime mode (Codex engine only)
codex:
  mode: unrestricted         # optional shorthand: unrestricted | safe
  sandbox: workspace-write   # read-only | workspace-write | danger-full-access
  approval: on-request       # untrusted | on-request | never
  search: true
  addDirs:
    - ../shared-assets

# Optional: granular agent permissions (Cursor engine only)
permissions:
  allowedPaths:
    - ./src
    - ./tests
  deniedPaths:
    - ./.env
    - ./secrets
  allowedCommands:
    - npm test
    - npm run build
  deniedCommands:
    - rm -rf *

# Optional: role/persona definition — injected into AGENTS.md as a System Instructions
# section, read by the engine once per session (not prepended to every message)
systemPrompt: |
  You are a marketing assistant named Aria. Never introduce yourself as OpenCode
  or any coding assistant. Reply in the same language the user uses.

# Optional: production hardening
timeout: 120                 # engine timeout in seconds (default: 300)
maxConcurrent: 20            # max parallel chats (default: 10)
maxQueuePerSession: 2        # max queued requests per user (default: 3)
sessionTtlDays: 14           # prune idle sessions after N days (default: 30)

# Optional: streaming message delivery for IM channels
streaming:
  mode: streaming            # buffered (default) | streaming
  showToolCalls: true        # show 🔧 tool hints in IM (default: false)

# Optional: group chat behaviour (applies to all channels)
groupChat:
  groupPolicy: mention-only  # mention-only (default) | smart | always
  historyLimit: 20           # recent messages to inject as context (default: 20)
  maxTurns: 10               # max consecutive bot replies per group (default: 10)

# Optional: scheduled tasks
tasks:
  - id: daily-standup
    name: daily-standup
    schedule: "0 9 * * 1-5"
    prompt: |
      Summarize all git commits in the last 24 hours,
      grouped by author. Flag any breaking changes.
    enabled: true
    target:
      channel: feishu
      chatId: "oc_xxxxx"

# Optional: persistent message queue (crash-safe, sequential processing)
inbox:
  enabled: true
  retentionDays: 7             # days to keep completed entries (default: 7)

# Optional: catch up on missed messages after restart
historyFetch:
  enabled: true
  pollIntervalMinutes: 15      # periodic poll interval (default: 15)
  initialLookbackMinutes: 60   # first-run lookback window (default: 60)

# Optional: route engine to a third-party LLM provider
provider:
  baseUrl: "https://openrouter.ai/api"
  apiKey: "${OPENROUTER_API_KEY}"
  model: "anthropic/claude-sonnet-4"
  models:                            # per-engine overrides
    codex: "openai/gpt-4.1-mini"

# Optional: IM channel configuration
channels:
  feishu:
    appId: ${FEISHU_APP_ID}
    appSecret: ${FEISHU_APP_SECRET}
  dingtalk:
    clientId: ${DINGTALK_CLIENT_ID}
    clientSecret: ${DINGTALK_CLIENT_SECRET}
  wecom:
    botId: ${WECOM_BOT_ID}
    secret: ${WECOM_SECRET}

# Optional: gateway service configuration
gateway:
  port: 3000
  host: 127.0.0.1
  token: ${GOLEM_TOKEN}
```

--------------------------------

### EmailAdapter Class Implementation

Source: https://0xranx.github.io/golembot/api/channel-adapter.html

Example implementation of a custom ChannelAdapter for email integration. Demonstrates constructor, start, reply, and stop methods.

```typescript
import type { ChannelAdapter, ChannelMessage } from 'golembot';

export default class EmailAdapter implements ChannelAdapter {
  readonly name: string;
  readonly maxMessageLength = 10000; // optional — overrides the default 4000

  constructor(private config: Record<string, unknown>) {
    this.name = (config.channelName as string) ?? 'email';
  }

  async start(onMessage: (msg: ChannelMessage) => void | Promise<void>): Promise<void> {
    // Start listening (IMAP, webhook, polling, etc.)
    // Call onMessage() for each incoming message:
    onMessage({
      channelType: 'email',
      senderId: email.from,
      senderName: email.fromName,
      chatId: email.threadId,
      chatType: 'dm',
      text: email.body,
      raw: email,
    });
  }

  async reply(msg: ChannelMessage, text: string): Promise<void> {
    // Send the reply (SMTP, API call, etc.)
  }

  async stop(): Promise<void> {
    // Clean up connections
  }

  // Optional: send typing indicator while the AI is thinking
  async typing(msg: ChannelMessage): Promise<void> {
    await this.client.sendTyping(msg.chatId).catch(() => {});
  }
}
```

--------------------------------

### Install Slack Bolt SDK

Source: https://0xranx.github.io/golembot/channels/slack.html

Install the required Slack Bolt SDK for Node.js.

```bash
npm install @slack/bolt
```

--------------------------------

### Install discord.js SDK

Source: https://0xranx.github.io/golembot/channels/discord.html

Install the discord.js library using npm. This is a prerequisite for creating a Discord bot.

```bash
npm install discord.js
```

--------------------------------

### Run the setup wizard

Source: https://0xranx.github.io/golembot/guide/cli-commands.html

Initiates the interactive onboarding process to configure a new assistant.

```bash
golembot onboard [-d <dir>] [--template <name>]
```

--------------------------------

### Install OpenCode CLI

Source: https://0xranx.github.io/golembot/reference/coding-cli-opencode.html

Install the OpenCode package globally using npm or build directly from the Go source.

```bash
npm install -g opencode-ai
```

```bash
go install github.com/anomalyco/opencode@latest
```

--------------------------------

### Install Cursor Agent via curl

Source: https://0xranx.github.io/golembot/reference/coding-cli-cursor.html

Recommended command to install the standalone agent binary.

```bash
curl https://cursor.com/install -fsS | bash
```

--------------------------------

### Verify OpenCode Installation

Source: https://0xranx.github.io/golembot/reference/coding-cli-opencode.html

Check the currently installed version of the OpenCode CLI.

```bash
opencode --version
```

--------------------------------

### Install Telegram SDK

Source: https://0xranx.github.io/golembot/channels/telegram.html

Install the grammy library required for Telegram bot functionality.

```bash
npm install grammy
```

--------------------------------

### Set Environment Variables and Run

Source: https://0xranx.github.io/golembot/channels/telegram.html

Export the bot token and start the Golem gateway.

```bash
export TELEGRAM_BOT_TOKEN=123456:ABCdef...
golem gateway
```

--------------------------------

### golembot onboard

Source: https://0xranx.github.io/golembot/guide/cli-commands.html

Runs the interactive setup wizard for GolemBot.

```APIDOC
## golembot onboard

### Description
Run the interactive setup wizard.

### Method
CLI Command

### Endpoint
golembot onboard [-d <dir>] [--template <name>]

### Parameters
#### Query Parameters
- **-d, --dir** (string) - Optional - Working directory. Default: `.`
- **--template** (string) - Optional - Scenario template to use. Default: Interactive prompt
```

--------------------------------

### Start HTTP Service

Source: https://0xranx.github.io/golembot/reference/architecture.html

Launch the built-in lightweight HTTP service using the CLI.

```bash
golembot serve --port 3000 --token my-secret
```

--------------------------------

### Install GolemBot with pnpm or yarn

Source: https://0xranx.github.io/golembot/guide/getting-started.html

Alternative installation methods for GolemBot using pnpm or yarn package managers.

```bash
pnpm add -g golembot
# or
yarn global add golembot
```

--------------------------------

### Start GolemBot Gateway

Source: https://0xranx.github.io/golembot/guide/dashboard.html

Start the GolemBot gateway. Use the default port or specify a custom port.

```bash
golembot gateway          # default: http://localhost:3000
```

```bash
golembot gateway -p 3010  # custom port: http://localhost:3010
```

--------------------------------

### Install AI Coding Agents

Source: https://0xranx.github.io/golembot/reference/coding-cli-comparison.html

Commands to install the respective CLI tools for each engine.

```bash
curl https://cursor.com/install -fsS | bash
```

```bash
npm i -g @anthropic-ai/claude-code
```

```bash
npm i -g opencode-ai
```

```bash
npm i -g @openai/codex
```

--------------------------------

### Basic Usage

Source: https://0xranx.github.io/golembot/api/create-assistant.html

A complete example of creating an assistant and processing stream events.

```typescript
import { createAssistant } from 'golembot';

const assistant = createAssistant({ dir: './my-bot' });

for await (const event of assistant.chat('What files are in this directory?')) {
  switch (event.type) {
    case 'text':
      process.stdout.write(event.content);
      break;
    case 'done':
      console.log(`\n(${event.durationMs}ms, $${event.costUsd})`);
      break;
  }
}
```

--------------------------------

### SSE Client Example with Curl

Source: https://0xranx.github.io/golembot/api/http-api.html

Example of how to use curl to interact with the Golem Bot's chat endpoint, demonstrating authentication and JSON payload.

```bash
curl -N -X POST http://localhost:3000/chat \
  -H "Authorization: Bearer my-secret" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'
```

--------------------------------

### Install GolemBot Dependency

Source: https://0xranx.github.io/golembot/guide/embed.html

Install the package as a local dependency using npm or pnpm.

```bash
npm install golembot
# or
pnpm add golembot
```

--------------------------------

### Set Environment Variables and Run

Source: https://0xranx.github.io/golembot/channels/slack.html

Export the necessary Slack tokens as environment variables before starting the Golem gateway.

```bash
export SLACK_BOT_TOKEN=xoxb-...
export SLACK_APP_TOKEN=xapp-...
golem gateway
```

--------------------------------

### Install Channel SDK Dependencies

Source: https://0xranx.github.io/golembot/channels/overview.html

Install specific peer dependencies required for individual IM channel integration.

```bash
# Feishu
pnpm add @larksuiteoapi/node-sdk

# DingTalk
pnpm add dingtalk-stream

# WeCom
pnpm add @wecom/aibot-node-sdk

# Slack
pnpm add @slack/bolt

# Telegram
pnpm add grammy

# Discord
pnpm add discord.js

# WeChat (no SDK needed — uses built-in fetch)
# Just add the token to golem.yaml
```

--------------------------------

### Start the Fleet Dashboard

Source: https://0xranx.github.io/golembot/guide/cli-commands.html

Launches the web server for the Fleet Dashboard to monitor all running bots.

```bash
golembot fleet serve [-p <port>] [--host <host>]
```

--------------------------------

### Define Environment Variables

Source: https://0xranx.github.io/golembot/guide/configuration.html

Example of a .env file for storing sensitive credentials.

```sh
FEISHU_APP_ID=cli_xxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxx
GOLEM_TOKEN=my-secret-token
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxx
```

--------------------------------

### Start Golem Server Programmatically

Source: https://0xranx.github.io/golembot/api/http-api.html

Start the Golem server using the `startServer` function. This is an asynchronous operation.

```typescript
import { createAssistant, startServer } from 'golembot';

const assistant = createAssistant({ dir: './my-bot' });
await startServer(assistant, { port: 3000, token: 'my-secret' });
```

--------------------------------

### Search and Install Skills via CLI

Source: https://0xranx.github.io/golembot/skills/overview.html

Commands for interacting with community skill registries like ClawHub and skills.sh.

```bash
# Search for skills (defaults to ClawHub)
golembot skill search "data analysis"

# Search a specific registry
golembot skill search "data analysis" --registry skills.sh

# Install from ClawHub
golembot skill add clawhub:data-analysis

# Install from skills.sh
golembot skill add skills.sh:owner/repo/skill

# All skill commands support --json for agent-friendly output
golembot skill search "markdown" --json
```

--------------------------------

### Authentication Header Example

Source: https://0xranx.github.io/golembot/api/http-api.html

Example of how to include the Bearer token in the Authorization header for API requests.

```http
Authorization: Bearer <token>
```

--------------------------------

### Search and Install Community Skills with GolemBot

Source: https://0xranx.github.io/golembot

Use the `golembot skill search` command to find skills from ClawHub or skills.sh. Install skills using `golembot skill add` with the appropriate registry and skill identifier.

```bash
$ golembot skill search "code review"

ClawHub results for "code review" (3):

  code-review          5-dimension code review with severity tiers
  pr-reviewer          Automated PR review with inline comments
  security-audit       Security vulnerability scanner for codebases

Install: golembot skill add clawhub:<slug>

$ golembot skill search "code review" --registry skills.sh

skills.sh results for "code review" (2):

  acme/tools/code-review    Comprehensive code review assistant
  devkit/review/pr-check    PR review with CI integration

Install: golembot skill add skills.sh:<owner>/<repo>/<skill>
```

--------------------------------

### Install dingtalk-stream Package

Source: https://0xranx.github.io/golembot/channels/dingtalk.html

Install the necessary package to enable DingTalk stream communication. This is a prerequisite for connecting GolemBot to DingTalk.

```bash
pnpm add dingtalk-stream
```

--------------------------------

### Configure GolemBot via YAML

Source: https://0xranx.github.io/golembot/guide/inbox.html

Example configuration file for setting up the bot engine, history fetching, and channel credentials.

```yaml
name: my-bot
engine: claude-code

inbox:
  enabled: true
  retentionDays: 7

historyFetch:
  enabled: true
  pollIntervalMinutes: 15
  initialLookbackMinutes: 60

channels:
  feishu:
    appId: ${FEISHU_APP_ID}
    appSecret: ${FEISHU_APP_SECRET}
  slack:
    botToken: ${SLACK_BOT_TOKEN}
    appToken: ${SLACK_APP_TOKEN}

gateway:
  port: 3000
```

--------------------------------

### Install WeCom AI Bot SDK

Source: https://0xranx.github.io/golembot/channels/wecom.html

Install the WeCom AI Bot Node.js SDK using pnpm. This is a prerequisite for integrating GolemBot with WeCom.

```bash
pnpm add @wecom/aibot-node-sdk
```

--------------------------------

### Install and Authenticate Codex CLI

Source: https://0xranx.github.io/golembot/engines/codex.html

Install the Codex CLI globally and authenticate using either ChatGPT OAuth or an API key. For API key authentication, set the OPENAI_API_KEY environment variable.

```bash
npm install -g @openai/codex
```

```bash
codex login
```

```bash
export OPENAI_API_KEY=sk-...
```

--------------------------------

### GolemBot Serve

Source: https://0xranx.github.io/golembot/guide/cli-commands.html

Starts the HTTP SSE (Server-Sent Events) server for GolemBot.

```APIDOC
## `golembot serve` 

### Description
Start the HTTP SSE server.

### Method
CLI Command

### Endpoint
golembot serve [-d <dir>] [-p <port>] [-t <token>] [--host <host>] [--api-key <key>]

### Parameters
#### Command Line Options
- **-d, --dir <dir>** (string) - Optional - Assistant directory. Default: `.`
- **-p, --port <port>** (integer) - Optional - HTTP port. Default: `3000`
- **-t, --token <token>** (string) - Optional - Bearer auth token. Default: `GOLEM_TOKEN` environment variable
- **--host <host>** (string) - Optional - Bind address. Default: `127.0.0.1`
- **--api-key <key>** (string) - Optional - Agent API key. Default: From environment variables

### Notes
See HTTP API for endpoint details, including `POST /abort` for cancelling the current task over HTTP.
```

--------------------------------

### Start an interactive GolemBot REPL

Source: https://0xranx.github.io/golembot/guide/cli-commands.html

Run `golembot run` to start an interactive command-line interface for conversing with your assistant. Supports various slash commands for managing the session, engine, model, and skills. Multi-line input is supported using `"""` delimiters.

```bash
golembot run [-d <dir>] [--api-key <key>]
```

```bash
/help
```

```bash
/status
```

```bash
/engine [name]
```

```bash
/model [list|name]
```

```bash
/skill
```

```bash
/stop
```

```bash
/cron list
```

```bash
/cron run <id>
```

```bash
/cron enable <id>
```

```bash
/cron disable <id>
```

```bash
/cron del <id>
```

```bash
/cron history <id>
```

```bash
/reset
```

```bash
/quit
```

```bash
/exit
```

--------------------------------

### Manage Installed Skills

Source: https://0xranx.github.io/golembot/skills/overview.html

Commands to list, add, or remove skills from the local environment.

```bash
# List installed skills
golembot skill list

# Add a skill from a local path
golembot skill add /path/to/my-skill

# Remove a skill
golembot skill remove my-skill
```

--------------------------------

### Chat Usage Examples

Source: https://0xranx.github.io/golembot/api/create-assistant.html

Demonstrates handling chat streams for single and multi-user scenarios.

```typescript
// Single user
for await (const event of assistant.chat('Hello')) {
  if (event.type === 'text') process.stdout.write(event.content);
}

// Multi-user
for await (const event of assistant.chat('Hello', { sessionKey: 'user-123' })) {
  // ...
}
```

--------------------------------

### Start GolemBot Gateway

Source: https://0xranx.github.io/golembot/testing/im-playbook.html

Launch the bot with a specific directory and verbose logging enabled to monitor message traffic.

```bash
golem gateway --dir ./my-bot --verbose
```

--------------------------------

### CI/CD Authentication for Codex

Source: https://0xranx.github.io/golembot/reference/coding-cli-comparison.html

Example of piping an API key into the Codex login command for automated environments.

```bash
printenv OPENAI_API_KEY | codex login --with-api-key
```

--------------------------------

### OpenCode Integration Modes

Source: https://0xranx.github.io/golembot/reference/coding-cli-opencode.html

Commands for running OpenCode in CLI mode or starting the HTTP server for persistent sessions.

```bash
opencode run --format json "prompt"
```

```bash
opencode serve --port 4096
# → POST /session/:id/message { parts: [{ type: "text", text: "prompt" }] }
# → GET /event (SSE stream)
```

--------------------------------

### Codex CLI JSONL Output Example

Source: https://0xranx.github.io/golembot/reference/coding-cli-codex.html

The `--json` flag outputs newline-delimited JSON (NDJSON) to stdout. This example shows typical event types like thread start, turn progression, and item completion.

```json
{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"bash -lc ls","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"Here is the analysis..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}
```

--------------------------------

### Start GolemBot Service with Docker Compose

Source: https://0xranx.github.io/golembot/guide/docker.html

Command to deploy the GolemBot service defined in docker-compose.yml in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Initialize Assistant Directory

Source: https://0xranx.github.io/golembot/api/create-assistant.html

Sets up a new assistant directory with required configuration files.

```typescript
await assistant.init({ engine: 'claude-code', name: 'my-bot' });
```

--------------------------------

### Initialize and run GolemBot via CLI

Source: https://0xranx.github.io/golembot/reference/architecture.html

Use the CLI for the quickest start to initialize a project and begin a REPL conversation.

```bash
npm install -g golembot

mkdir ~/my-assistant && cd ~/my-assistant
golembot init         # Interactive: choose engine, pick a name, generate config, copy default skills
golembot run          # REPL conversation
```

--------------------------------

### Initialization Workflow

Source: https://0xranx.github.io/golembot/reference/architecture.html

Steps performed during the assistant initialization process.

```text
golembot init (or assistant.init())
1. Check if directory already has golem.yaml → error if yes
2. Interactive prompts: engine type (cursor/claude-code/opencode), assistant name
3. Create golem.yaml
4. Create skills/ directory
5. Copy built-in skills to skills/ (general + im-adapter)
6. Create .golem/ directory (internal state)
7. Generate AGENTS.md
8. Generate .gitignore (ignoring .golem/)
```

--------------------------------

### Verify Claude Code Installation

Source: https://0xranx.github.io/golembot/reference/coding-cli-claude-code.html

Check the currently installed version of the Claude Code CLI.

```bash
claude --version
```

--------------------------------

### Initialization Workflow (`golembot init`)

Source: https://0xranx.github.io/golembot/reference/architecture.html

Details the steps involved in initializing a new GolemBot project.

```APIDOC
## `init` Workflow 

### Description
Initializes a new GolemBot project, setting up necessary configuration files and directories.

### Command
```bash
golembot init
# or
assistant.init()
```

### Steps
1. Check if the directory already contains `golem.yaml`. If yes, throw an error.
2. Present interactive prompts for engine type (e.g., cursor, claude-code, opencode) and assistant name.
3. Create the `golem.yaml` configuration file.
4. Create the `skills/` directory.
5. Copy built-in skills (general and IM-adapter) to the `skills/` directory.
6. Create the `.golem/` directory for internal state.
7. Generate `AGENTS.md`.
8. Generate `.gitignore` file, ensuring `.golem/` is ignored.
```

--------------------------------

### Install GolemBot Globally

Source: https://0xranx.github.io/golembot/guide/getting-started.html

Installs GolemBot globally using npm. Ensure Node.js version is 18 or higher.

```bash
npm install -g golembot
```

--------------------------------

### Install Claude Code CLI

Source: https://0xranx.github.io/golembot/reference/coding-cli-claude-code.html

Global installation command for the Claude Code CLI using npm. Requires Node.js version 18 or higher.

```bash
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Initialize Golembot Instances

Source: https://0xranx.github.io/golembot/guide/group-chat.html

Commands to initialize multiple bot instances with specific roles and engines.

```bash
# Bot A: product analyst
golembot init -n analyst-bot -e claude-code -r "product analyst"

# Bot B: user researcher (in a different directory)
golembot init -n research-bot -e claude-code -r "user researcher"
```

--------------------------------

### CreateAssistantOpts Interface

Source: https://0xranx.github.io/golembot/api/create-assistant.html

Configuration options for initializing an assistant, including directory paths and engine overrides.

```typescript
interface CreateAssistantOpts {
  dir: string;                  // Path to the assistant directory
  engine?: string;              // Override engine from golem.yaml
  model?: string;               // Override model from golem.yaml
  apiKey?: string;              // Agent API key
  maxConcurrent?: number;       // Max parallel chats across all sessions (default: 10)
  maxQueuePerSession?: number;  // Max queued requests per sessionKey (default: 3)
  timeoutMs?: number;           // Engine invocation timeout in ms (default: 300000)
}
```

--------------------------------

### Manually Initialize GolemBot Project

Source: https://0xranx.github.io/golembot/guide/getting-started.html

Initializes a GolemBot project with a specified engine and bot name, creating configuration files and directories.

```bash
mkdir my-bot && cd my-bot
golembot init -e claude-code -n my-bot
```

--------------------------------

### Install OpenAI Codex CLI

Source: https://0xranx.github.io/golembot/reference/coding-cli-codex.html

Install the Codex CLI globally using npm or via Homebrew on macOS. Binaries are also available on GitHub Releases.

```bash
# npm (global)
npm install -g @openai/codex

# Homebrew (macOS)
brew install codex

# GitHub Releases platform binaries
# macOS Apple Silicon: codex-aarch64-apple-darwin.tar.gz
# macOS x86_64:        codex-x86_64-apple-darwin.tar.gz
# Linux x86_64 (musl): codex-x86_64-unknown-linux-musl.tar.gz
# Linux arm64 (musl):  codex-aarch64-unknown-linux-musl.tar.gz
```

--------------------------------

### Run GolemBot Interactive REPL

Source: https://0xranx.github.io/golembot/guide/getting-started.html

Starts the GolemBot interactive command-line interface for chatting with an AI agent. Use /help for commands.

```bash
golembot run
```

--------------------------------

### Claude Code stream-json Event Examples

Source: https://0xranx.github.io/golembot/reference/coding-cli-claude-code.html

Examples of NDJSON events emitted by the Claude Code CLI, including assistant replies, tool calls, and tool results.

```json
{"type":"assistant","session_id":"session_01","message":{"id":"msg_1","type":"message","role":"assistant","content":[{"type":"text","text":"Planning next steps."}],"usage":{"input_tokens":120,"output_tokens":45}}}
```

```json
{"type":"assistant","session_id":"session_01","message":{"id":"msg_2","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_1","name":"Bash","input":{"command":"ls -la"}}]}}
```

```json
{"type":"user","session_id":"session_01","message":{"id":"msg_3","type":"message","role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_1","content":"total 2\nREADME.md\nsrc\n"}]}}
```

```json
{"type":"tool_result","tool_use_id":"toolu_2","content":[{"type":"text","text":"Task completed"}]}
```

--------------------------------

### GolemBot Initialization

Source: https://0xranx.github.io/golembot/guide/cli-commands.html

Initializes a new GolemBot assistant directory with default configurations and files.

```APIDOC
## `golembot init` 

### Description
Initialize a new assistant directory.

### Method
CLI Command

### Endpoint
golembot init [-e <engine>] [-n <name>] [-r <role>]

### Parameters
#### Command Line Options
- **-e, --engine <engine>** (string) - Optional - Engine type (`cursor`, `claude-code`, `opencode`, `codex`). Default: `cursor`
- **-n, --name <name>** (string) - Optional - Assistant name. Default: Interactive prompt
- **-r, --role <role>** (string) - Optional - Persona role (e.g. "product analyst", "customer support"). Default: None

### Description
Creates `golem.yaml`, `skills/` (with built-in skills: `general`, `im-adapter`, `multi-bot`), `AGENTS.md`, `.golem/`, and `.gitignore`. When `--role` is provided, it writes `persona.role` into `golem.yaml` — this role is propagated to fleet registration so peer bots can see each other's specializations.
```

--------------------------------

### Start GolemBot unified gateway

Source: https://0xranx.github.io/golembot/guide/cli-commands.html

The `golembot gateway` command starts a unified service that combines IM adapters and the HTTP API. It reads channel configurations from `golem.yaml` and auto-registers with the Fleet directory. Enable `--verbose` for channel log output.

```bash
golembot gateway [-d <dir>] [-p <port>] [-t <token>] [--host <host>] [--api-key <key>] [--verbose]
```

--------------------------------

### GET /health

Source: https://0xranx.github.io/golembot/api/http-api.html

Checks the health status of the GolemBot server.

```APIDOC
## GET /health

### Description
Health check endpoint (no authentication required).

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Current status (e.g., "ok").
- **timestamp** (string) - ISO 8601 timestamp.
```

--------------------------------

### List Skills via CLI

Source: https://0xranx.github.io/golembot/skills/create-skill.html

Verify that a skill has been added correctly by listing all available skills using the GolemBot CLI.

```bash
golembot skill list
```

--------------------------------

### CursorEngine Implementation

Source: https://0xranx.github.io/golembot/reference/architecture.html

Details the CursorEngine, which invokes the `agent` CLI using `child_process.spawn` and handles stream-json output.

```APIDOC
## CursorEngine

### Description
The `CursorEngine` implements the `AgentEngine` interface by spawning the `agent` CLI process. It handles skill injection by creating symbolic links and processes the `stream-json` output, stripping ANSI codes before yielding `StreamEvent` objects. It also includes logic for segment accumulation to deduplicate summary events.

### Method
```typescript
class CursorEngine implements AgentEngine {
  async *invoke(prompt, opts) {
    // 1. Inject Skills: symlink skillPaths to .cursor/skills/
    // 2. spawn: agent -p <prompt> --output-format stream-json --stream-partial-output ...
    // 3. stripAnsi + parse stream-json line by line → yield StreamEvent
    // 4. segmentAccum deduplication (Cursor's summary events)
  }
}
```

### Key Features
- **Skill Injection**: Uses symbolic links to inject skills into the `.cursor/skills/` directory.
- **CLI Invocation**: Spawns the `agent` CLI with specific arguments for streaming JSON output.
- **Output Processing**: Parses `stream-json` output, removes ANSI escape codes, and yields `StreamEvent`.
- **Deduplication**: Implements `segmentAccum` to handle potential duplicate summary events.
```

--------------------------------

### Pre-login with API Key

Source: https://0xranx.github.io/golembot/reference/coding-cli-codex.html

Logs in using an API key, storing the credentials in `~/.codex/auth.json`. This is the recommended method for headless or CI/CD environments.

```bash
# Pre-login with API key (stored in ~/.codex/auth.json)
printenv OPENAI_API_KEY | codex login --with-api-key
```

--------------------------------

### Start GolemBot HTTP SSE server

Source: https://0xranx.github.io/golembot/guide/cli-commands.html

Use `golembot serve` to launch the HTTP Server-Sent Events (SSE) server. This allows interaction with the assistant via HTTP requests. The `--token` option sets a Bearer auth token.

```bash
golembot serve [-d <dir>] [-p <port>] [-t <token>] [--host <host>] [--api-key <key>]
```

--------------------------------

### GolemBot Run

Source: https://0xranx.github.io/golembot/guide/cli-commands.html

Starts an interactive REPL (Read-Eval-Print Loop) conversation with the assistant.

```APIDOC
## `golembot run` 

### Description
Start an interactive REPL conversation.

### Method
CLI Command

### Endpoint
golembot run [-d <dir>] [--api-key <key>]

### Parameters
#### Command Line Options
- **-d, --dir <dir>** (string) - Optional - Assistant directory. Default: `.`
- **--api-key <key>** (string) - Optional - Agent API key. Default: From environment variables

### REPL Slash Commands
#### Description
Commands available within the interactive REPL session for managing the assistant's state and operations.

| Command | Description |
|---|---|
| `/help` | Show available commands |
| `/status` | Show current engine, model, and skills |
| `/engine [name]` | Show or switch engine |
| `/model [list|name]` | Show, list available, or switch model |
| `/skill` | List installed skills |
| `/stop` | Stop the current running task |
| `/cron list` | List all scheduled tasks and their status |
| `/cron run <id>` | Trigger a scheduled task immediately |
| `/cron enable <id>` | Enable a scheduled task |
| `/cron disable <id>` | Disable a scheduled task |
| `/cron del <id>` | Delete a scheduled task |
| `/cron history <id>` | Show recent execution history for a task |
| `/reset` | Clear current session |
| `/quit`, `/exit` | Exit the REPL |

### Notes
- These slash commands also work in IM channels (Feishu, Telegram, Slack, etc.) and via the HTTP API (`POST /chat` with a slash command as the message returns a JSON response instead of an SSE stream).
- `/stop` cancels the current in-flight task for the session without clearing history. Use `/reset` if you want to clear the session itself.
- Supports multi-line input with `"""` delimiters. Displays duration and cost (when available) on completion.
```

--------------------------------

### GET /api/channels

Source: https://0xranx.github.io/golembot/api/http-api.html

Lists all available IM channels and their proactive messaging capabilities.

```APIDOC
## GET /api/channels

### Description
List available IM channels and whether they support proactive send. Requires authentication.

### Method
GET

### Endpoint
/api/channels

### Response
#### Success Response (200)
- **channels** (array) - List of channels with name and canSend boolean
```

--------------------------------

### Golembot Full Example Configuration

Source: https://0xranx.github.io/golembot/guide/configuration.html

This YAML configuration defines the core settings for a Golembot instance, including engine, chat policies, channel integrations, and gateway settings. Ensure sensitive tokens are provided via environment variables.

```yaml
name: my-bot
engine: claude-code

groupChat:
  groupPolicy: smart
  historyLimit: 30
  maxTurns: 5

inbox:
  enabled: true
  retentionDays: 7

historyFetch:
  enabled: true
  pollIntervalMinutes: 15
  initialLookbackMinutes: 60

channels:
  slack:
    botToken: ${SLACK_BOT_TOKEN}
    appToken: ${SLACK_APP_TOKEN}

gateway:
  port: 3000
  token: ${GOLEM_TOKEN}
```

--------------------------------

### Initialize a new GolemBot assistant

Source: https://0xranx.github.io/golembot/guide/cli-commands.html

Use `golembot init` to create a new assistant directory with default configurations and skills. The `--role` option sets the assistant's persona in `golem.yaml` for fleet registration.

```bash
golembot init [-e <engine>] [-n <name>] [-r <role>]
```

--------------------------------

### Start GolemBot Gateway

Source: https://0xranx.github.io/golembot/channels/dingtalk.html

Launch the GolemBot gateway service. Use the --verbose flag to see connection messages and activity prefixed with [dingtalk].

```bash
golembot gateway --verbose
```

--------------------------------

### GET /api/events

Source: https://0xranx.github.io/golembot/api/http-api.html

Provides a real-time activity stream via Server-Sent Events (SSE).

```APIDOC
## GET /api/events

### Description
Real-time activity stream via Server-Sent Events. Each message processed by the gateway is broadcast as an SSE event. Requires authentication.

### Method
GET

### Endpoint
/api/events

### Query Parameters
- **token** (string) - Optional - Authentication token if not using Authorization header
```

--------------------------------

### Create Golem Server Programmatically

Source: https://0xranx.github.io/golembot/api/http-api.html

Initialize and create a Golem server instance using the `createGolemServer` function. Requires an assistant instance.

```typescript
import { createAssistant, createGolemServer } from 'golembot';

const assistant = createAssistant({ dir: './my-bot' });
const server = createGolemServer(assistant, {
  port: 3000,
  token: 'my-secret',
  hostname: '127.0.0.1',
});
```

--------------------------------

### GitHub Actions Integration

Source: https://0xranx.github.io/golembot/reference/coding-cli-cursor.html

Example configuration for running GolemBot within a GitHub Actions workflow.

```APIDOC
## GitHub Actions Integration

### Description
Automate GolemBot execution in CI/CD environments using the CURSOR_API_KEY.

### Request Example
- name: Install Cursor CLI
  run: |
    curl https://cursor.com/install -fsS | bash
    echo "$HOME/.cursor/bin" >> $GITHUB_PATH

- name: Run Cursor Agent
  env:
    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
  run: |
    agent -p "Your prompt here" --model gpt-5.2
```

--------------------------------

### Task Configuration in golem.yaml

Source: https://0xranx.github.io/golembot/guide/scheduled-tasks.html

Example of how to define scheduled tasks within the golem.yaml configuration file.

```APIDOC
## Task Configuration in golem.yaml

### Description
Tasks are configured in the `tasks` array within your `golem.yaml` file. Each task requires an `id`, `name`, `schedule`, and `prompt`. Optional fields include `enabled` and `target` for delivery.

### Task Fields

| Field        | Type    | Required | Description                                                                 |
|--------------|---------|----------|-----------------------------------------------------------------------------|
| `id`         | `string`| Yes      | Unique identifier for the task.                                             |
| `name`       | `string`| Yes      | Human-readable name for the task.                                           |
| `schedule`   | `string`| Yes      | Defines when the task should run. Supports cron, interval, daily, and weekly formats. |
| `prompt`     | `string`| Yes      | The prompt to be executed by the agent.                                     |
| `enabled`    | `boolean`| No       | Whether the task is active. Defaults to `true`.                             |
| `target`     | `object`| No       | Specifies where the task results should be delivered. If omitted, results are logged only. |
| `target.channel` | `string`| --       | The type of IM channel for delivery (e.g., `feishu`, `slack`, `telegram`). |
| `target.chatId`  | `string`| --       | The specific chat or group ID within the channel to send results to.        |

### Schedule Formats

| Format            | Example         | Description                                                                 |
|-------------------|-----------------|-----------------------------------------------------------------------------|
| Standard 5-field cron | `0 9 * * 1-5`   | Minute, hour, day-of-month, month, day-of-week.                             |
| Interval shorthand  | `every 30m`     | Run the task every 30 minutes.                                              |
| Daily shorthand     | `daily 09:00`   | Run the task once per day at the specified time.                            |
| Weekly shorthand    | `weekly mon 09:00`| Run the task once per week on the specified day and time.                   |

### Example `golem.yaml` Task Configuration
```yaml
tasks:
  - id: daily-standup
    name: daily-standup
    schedule: "0 9 * * 1-5"
    prompt: |
      Summarize all git commits in the last 24 hours,
      grouped by author. Flag any breaking changes.
    enabled: true
    target:
      channel: feishu
      chatId: "oc_xxxxx"

  - id: dependency-check
    name: dependency-check
    schedule: "weekly mon 10:00"
    prompt: Check package.json for outdated or vulnerable dependencies.
    target:
      channel: slack
      chatId: "C0123456789"
```
```