OpenBrowserClaw

https://github.com/wexare-ai/openbrowserclaw
Admin
A browser-native personal AI assistant that runs entirely in a browser tab with zero infrastructure,...
Tokens:14,942
Snippets:76
Trust Score:3.8
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install and Run OpenBrowserClaw

Source: https://github.com/wexare-ai/openbrowserclaw/blob/master/README.md

Follow these commands to install dependencies and start the development server. Ensure you are in the project directory.

```bash
cd openbrowserclaw
npm install
npm run dev
```

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

### Development Commands

Source: https://github.com/wexare-ai/openbrowserclaw/blob/master/README.md

Run these commands to start a local development server with Hot Module Replacement (HMR), create a production build, preview the production build, or perform TypeScript type checking.

```bash
npm run dev        # Vite dev server with HMR
npm run build      # Production build → dist/
npm run preview    # Preview production build
npm run typecheck  # TypeScript type checking
```

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

### HTTP Requests (`fetch_url`)

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

This tool enables making HTTP requests using the browser's `fetch()` API. It supports GET and POST methods, custom headers, and JSON bodies. HTML responses are automatically converted to text and truncated at 20KB.

```APIDOC
## `fetch_url`

### Description
Makes HTTP requests to a specified URL. Supports various methods, headers, and request bodies. HTML responses are stripped to text and truncated.

### Method
Not applicable (Tool invocation)

### Parameters
#### Input
- **url** (string) - Required - The URL to fetch.
- **method** (string) - Optional - The HTTP method (e.g., 'GET', 'POST'). Defaults to 'GET'.
- **headers** (object) - Optional - An object containing request headers.
- **body** (string) - Optional - The request body, typically JSON stringified.

### Request Example
```typescript
// GET request
const fetchGet = {
  name: 'fetch_url',
  input: {
    url: 'https://api.github.com/repos/anthropics/anthropic-sdk-python'
  }
};

// POST request with JSON body
const fetchPost = {
  name: 'fetch_url',
  input: {
    url: 'https://httpbin.org/post',
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: 'hello', value: 42 })
  }
};

// GET with custom headers
const fetchAuth = {
  name: 'fetch_url',
  input: {
    url: 'https://api.example.com/data',
    headers: { 'Authorization': 'Bearer token123' }
  }
};
```

### Response Example
```
[HTTP 200]
{"id":123,...,"stargazers_count":1234,...}

// or for POST:
[HTTP 200]
{"json":{"message":"hello","value":42},...}
```

### Notes
Subject to browser CORS restrictions.
HTML responses are auto-stripped to readable text.
```

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

### Execute Shell Commands with Bash Tool

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

The `bash` tool allows Claude to execute shell commands within a JS-emulated shell. It supports pipes, redirects, and various operators. Examples demonstrate file operations, chaining commands with `&&` and `||`, processing JSON with `jq`, and text transformation with `sed`.

```typescript
// Claude invokes the bash tool internally. The tool definition:
const bashTool = {
  name: 'bash',
  input: {
    command: 'echo "line1\nline2\nline3" | grep line | wc -l',
    timeout: 10  // seconds, default 30, max 120
  }
};
// Returns: "3\n"
```

```typescript
// File operations via bash
// command: 'echo "data" > output.txt && cat output.txt'
// Returns: "data\n"
```

```typescript
// Chaining with && and ||
// command: 'mkdir notes && echo "created" || echo "failed"'
// Returns: "created\n"
```

```typescript
// Practical example: process JSON data
// command: 'echo '{\"name\":\"Alice\",\"score\":95}\' | jq .name'
// Returns: '"Alice"\n'
```

```typescript
// Using sed for text transformation
// command: 'echo "hello world" | sed s/world/earth/g'
// Returns: "hello earth\n"
```

```typescript
// Supported commands: echo, printf, cat, head, tail, wc, grep, sort, uniq,
// tr, cut, sed, awk, ls, mkdir, cp, mv, rm, touch, pwd, cd, date,
// sleep, seq, base64, jq, tee, xargs, test, rev, basename, dirname
```

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

### Manage Conversation Sessions with Orchestrator

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Use `newSession` to clear message history and start a fresh conversation. Use `compactContext` to summarize long conversations and reduce token usage, but ensure the orchestrator is idle before calling it.

```typescript
// Start a new session (clears IndexedDB messages for the group)
await orchestrator.newSession('br:main');
orchestrator.events.on('session-reset', ({ groupId }) => {
  console.log('Session cleared for:', groupId);
});

// Compact context when conversation is long (must be idle)
if (orchestrator.getState() === 'idle') {
  await orchestrator.compactContext('br:main');
}
orchestrator.events.on('context-compacted', ({ groupId, summary }) => {
  console.log('Compacted:', summary.slice(0, 100) + '...');
  // History is now replaced by the summary in IndexedDB
});
```

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

### Configure and Manage Telegram Bot Integration

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Integrate a Telegram bot using long-polling over HTTPS. The browser tab must remain open for message reception and response. This setup requires a bot token and registered chat IDs.

```typescript
// Configure and start the Telegram channel
const orchestrator = new Orchestrator();
await orchestrator.init();

await orchestrator.configureTelegram(
  '7123456789:AAHxyz_your_bot_token',
  ['987654321']  // Registered chat IDs
);
// Channel starts long-polling (30s timeout) automatically
```

```typescript
// Direct channel API
orchestrator.telegram.configure('7123456789:AAHxyz_your_bot_token', ['987654321']);
orchestrator.telegram.onMessage((msg) => {
  // msg.groupId = 'tg:987654321'
  // msg.sender  = 'Alice'
  // msg.content = 'Hello!'
  console.log(`Telegram from ${msg.sender}: ${msg.content}`);
});
orchestrator.telegram.start();
```

```typescript
// Send a message to a Telegram chat
await orchestrator.telegram.send('tg:987654321', 'Hello from OpenBrowserClaw! 👋');
// Messages >4096 chars are auto-split at newline boundaries

// Bot commands available in any chat (no registration required):
// /chatid → replies with the chat ID to register
// /ping   → replies "Pong! 🏓 OpenBrowserClaw is running."
```

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

### Orchestrator Session Management

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Methods to manage conversation sessions within the orchestrator. `newSession` starts a fresh conversation by clearing message history, while `compactContext` summarizes the history to reduce token usage.

```APIDOC
## orchestrator.newSession(groupId?)

### Description
Clears all message history for a specified group, initiating a new conversation.

### Method
`newSession`

### Parameters
#### Path Parameters
- **groupId** (string) - Optional - The identifier for the group whose session should be reset.

### Request Example
```typescript
await orchestrator.newSession('br:main');
```

## orchestrator.compactContext(groupId?)

### Description
Asks the AI model to summarize the current conversation history and replaces the full history with this summary to reduce token usage. This operation should ideally be performed when the system is idle.

### Method
`compactContext`

### Parameters
#### Path Parameters
- **groupId** (string) - Optional - The identifier for the group whose context should be compacted.

### Request Example
```typescript
if (orchestrator.getState() === 'idle') {
  await orchestrator.compactContext('br:main');
}
```
```

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

### Deployment Commands

Source: https://github.com/wexare-ai/openbrowserclaw/blob/master/README.md

Build the project for production and upload the resulting static files to any hosting provider. No server is required as the project consists of HTML, CSS, and JavaScript.

```bash
npm run build
# Upload dist/ to any static host:
# GitHub Pages, Cloudflare Pages, Netlify, Vercel, S3, etc.
```

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

### File System Tools (`read_file`, `write_file`, `list_files`)

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

These tools allow for reading, writing, and listing files within the Origin Private File System (OPFS) workspace. Files are persisted across browser sessions.

```APIDOC
## `write_file`

### Description
Writes content to a specified file path in the OPFS workspace. Directories are created automatically if they do not exist.

### Method
Not applicable (Tool invocation)

### Parameters
#### Input
- **path** (string) - Required - The path to the file, including directories.
- **content** (string) - Required - The content to write to the file.

### Request Example
```typescript
const writeTool = {
  name: 'write_file',
  input: {
    path: 'notes/meeting-2025.md',
    content: '# Meeting Notes\n\n- Discussed Q1 goals\n- Action items assigned'
  }
};
```

### Response Example
```
Written 57 bytes to notes/meeting-2025.md
```

## `read_file`

### Description
Reads the content of a specified file from the OPFS workspace.

### Method
Not applicable (Tool invocation)

### Parameters
#### Input
- **path** (string) - Required - The path to the file to read.

### Request Example
```typescript
const readTool = {
  name: 'read_file',
  input: { path: 'notes/meeting-2025.md' }
};
```

### Response Example
```
# Meeting Notes\n\n- Discussed Q1 goals\n- Action items assigned
```

## `list_files`

### Description
Lists files and directories within a specified path in the OPFS workspace. If no path is provided, it lists the root workspace.

### Method
Not applicable (Tool invocation)

### Parameters
#### Input
- **path** (string) - Optional - The directory path to list. Defaults to the root workspace.

### Request Example
```typescript
// List files in 'notes' directory
const listTool = {
  name: 'list_files',
  input: { path: 'notes' }
};

// List root workspace
const listRoot = {
  name: 'list_files',
  input: {} 
};
```

### Response Example
```
meeting-2025.md\nmeeting-2025-02.md\n
// or for root:
CLAUDE.md\nnotes/\nscripts/\n
(Files are sorted, directories end with '/')
```

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

### Initialize Orchestrator and Listen for Events

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Initialize the Orchestrator and set up event listeners for 'ready', 'message', 'state-change', 'tool-activity', 'token-usage', and 'error'. Ensure clean shutdown on window unload.

```typescript
import { Orchestrator } from './src/orchestrator';

const orchestrator = new Orchestrator();
await orchestrator.init();

// Listen for ready
orchestrator.events.on('ready', () => console.log('OpenBrowserClaw ready'));

// Listen for new messages (both user and assistant)
orchestrator.events.on('message', (msg) => {
  console.log(`[${msg.sender}] ${msg.content}`);
  // msg: { id, groupId, sender, content, timestamp, channel, isFromMe, isTrigger }
});

// Listen for state changes: 'idle' | 'thinking' | 'responding'
orchestrator.events.on('state-change', (state) => {
  console.log('State:', state);
});

// Listen for tool activity
orchestrator.events.on('tool-activity', ({ tool, status }) => {
  console.log(`Tool ${tool}: ${status}`); // e.g. "Tool bash: running"
});

// Listen for token usage
orchestrator.events.on('token-usage', (usage) => {
  console.log(`Tokens: ${usage.inputTokens} in / ${usage.outputTokens} out`);
});

// Listen for errors
orchestrator.events.on('error', ({ groupId, error }) => {
  console.error(`Error in ${groupId}: ${error}`);
});

// Shut down cleanly
window.addEventListener('beforeunload', () => orchestrator.shutdown());
```

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

### Write, Read, and List Files in OPFS Workspace

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Use these tools to manage files within the Origin Private File System. Files persist across browser sessions. Directories are created automatically when writing files.

```typescript
// Write a file (creates directories automatically)
const writeTool = {
  name: 'write_file',
  input: {
    path: 'notes/meeting-2025.md',
    content: '# Meeting Notes\n\n- Discussed Q1 goals\n- Action items assigned'
  }
};
// Returns: "Written 57 bytes to notes/meeting-2025.md"
```

```typescript
// Read a file
const readTool = {
  name: 'read_file',
  input: { path: 'notes/meeting-2025.md' }
};
// Returns: "# Meeting Notes\n\n- Discussed Q1 goals\n- Action items assigned"
```

```typescript
// List files in a directory
const listTool = {
  name: 'list_files',
  input: { path: 'notes' }
};
// Returns: "meeting-2025.md\nmeeting-2025-02.md\n"  (sorted, dirs end with /)
```

```typescript
// List root workspace
const listRoot = {
  name: 'list_files',
  input: {}  // path defaults to root
};
// Returns: "CLAUDE.md\nnotes/\nscripts/\n"
```

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

### Orchestrator Initialization and Event Listeners

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Initialize the Orchestrator, set up event listeners for various events like readiness, messages, state changes, tool activity, token usage, and errors. Ensure clean shutdown.

```APIDOC
## Orchestrator Initialization and Event Listeners

### Description
Initialize the `Orchestrator` and set up event listeners for various events. This includes listening for readiness, new messages (both user and assistant), state changes (idle, thinking, responding), tool activity, token usage, and errors. It also demonstrates how to shut down the orchestrator cleanly.

### Method
`new Orchestrator()` and `orchestrator.init()`

### Initialization
```typescript
import { Orchestrator } from './src/orchestrator';

const orchestrator = new Orchestrator();
await orchestrator.init();

// Listen for ready
orchestrator.events.on('ready', () => console.log('OpenBrowserClaw ready'));

// Listen for new messages (both user and assistant)
orchestrator.events.on('message', (msg) => {
  console.log(`[${msg.sender}] ${msg.content}`);
  // msg: { id, groupId, sender, content, timestamp, channel, isFromMe, isTrigger }
});

// Listen for state changes: 'idle' | 'thinking' | 'responding'
orchestrator.events.on('state-change', (state) => {
  console.log('State:', state);
});

// Listen for tool activity
orchestrator.events.on('tool-activity', ({ tool, status }) => {
  console.log(`Tool ${tool}: ${status}`); // e.g. "Tool bash: running"
});

// Listen for token usage
orchestrator.events.on('token-usage', (usage) => {
  console.log(`Tokens: ${usage.inputTokens} in / ${usage.outputTokens} out`);
});

// Listen for errors
orchestrator.events.on('error', ({ groupId, error }) => {
  console.error(`Error in ${groupId}: ${error}`);
});

// Shut down cleanly
window.addEventListener('beforeunload', () => orchestrator.shutdown());
```
```

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

### API Key and Model Configuration

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Configure the Anthropic API key securely and set the AI model. Check if the system is configured and change the assistant's name.

```APIDOC
## API Key and Model Configuration

### Description
Manage the Anthropic API key and the AI model used by the orchestrator. The API key is stored encrypted. You can also check if the system is configured, change the assistant's name, and set the active model.

### Methods
- `orchestrator.setApiKey(key)`
- `orchestrator.isConfigured()`
- `orchestrator.setModel(modelName)`
- `orchestrator.getModel()`
- `orchestrator.setAssistantName(name)`

### Usage
```typescript
// Check if a key is already configured
if (!orchestrator.isConfigured()) {
  const key = prompt('Enter your Anthropic API key:') ?? '';
  await orchestrator.setApiKey(key); // Encrypts and persists to IndexedDB
  console.log('API key saved. isConfigured:', orchestrator.isConfigured()); // true
}

// Change the model (default: 'claude-sonnet-4-6')
await orchestrator.setModel('claude-opus-4-5');
console.log('Active model:', orchestrator.getModel()); // 'claude-opus-4-5'

// Rename the assistant (changes @trigger pattern)
await orchestrator.setAssistantName('Aria');
// Now messages must include "@Aria" to trigger the agent in non-default groups
```
```

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

### Shell Emulator: Execute Bash-like Commands

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Execute bash-like commands in pure JavaScript using OPFS. Supports pipes, redirects, and variable expansion. Handles errors and allows custom environments and timeouts.

```typescript
import { executeShell } from './src/shell';

// Simple command
const result = await executeShell('echo "Hello, World!"', 'br:main');
// { stdout: 'Hello, World!\n', stderr: '', exitCode: 0 }

// Pipes and text processing
const r2 = await executeShell(
  'echo -e "banana\napple\ncherry\napple" | sort | uniq | wc -l',
  'br:main'
);
// { stdout: '3\n', stderr: '', exitCode: 0 }

// File operations with redirect
const r3 = await executeShell(
  'echo "# TODO\n- Task 1\n- Task 2" > todo.md && cat todo.md',
  'br:main'
);
// { stdout: '# TODO\n- Task 1\n- Task 2\n', stderr: '', exitCode: 0 }

// JSON processing with jq
const r4 = await executeShell(
  `echo '{"users":[{"name":"Alice"},{"name":"Bob"}]}' | jq '.users[0].name'`,
  'br:main'
);
// { stdout: '"Alice"\n', stderr: '', exitCode: 0 }

// Error handling
const r5 = await executeShell('cat nonexistent.txt', 'br:main');
// { stdout: '', stderr: 'cat: nonexistent.txt: No such file', exitCode: 1 }

// Custom environment and timeout
const r6 = await executeShell(
  'echo $GREETING $NAME',
  'br:main',
  { GREETING: 'Hello', NAME: 'World' },
  5 // timeout seconds
);
// { stdout: 'Hello World\n', stderr: '', exitCode: 0 }
```

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

### Create Scheduled Tasks

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Use the create_task tool to set up cron-scheduled prompts that run automatically while the browser tab is open. Supports standard cron syntax for scheduling.

```typescript
// Daily morning briefing at 9:00 AM weekdays
const taskTool = {
  name: 'create_task',
  input: {
    schedule: '0 9 * * 1-5',
    prompt: 'Give me a brief summary of: 1) weather in London, 2) top tech news from hackernews, 3) my upcoming tasks for today'
  }
};
// Returns: "Task created successfully.\nSchedule: 0 9 * * 1-5\nPrompt: Give me a brief..."

// Every hour
// schedule: '0 * * * *'

// Every 30 minutes
// schedule: '*/30 * * * *'

// Every Monday at noon
// schedule: '0 12 * * 1'

// Cron format: minute hour day-of-month month day-of-week
// Supports: * (any), N (exact), N-M (range), N,M (list), */N (step)
```

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

### Fetch URL Tool for HTTP Requests

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

This tool utilizes the browser's fetch() API for making HTTP requests. HTML responses are automatically converted to text, and responses are limited to 20KB. Be aware of browser CORS restrictions.

```typescript
// GET request
const fetchGet = {
  name: 'fetch_url',
  input: {
    url: 'https://api.github.com/repos/anthropics/anthropic-sdk-python',
  }
};
// Returns: "[HTTP 200]\n{\"id\":123,...,\"stargazers_count\":1234,...}"
```

```typescript
// POST request with JSON body
const fetchPost = {
  name: 'fetch_url',
  input: {
    url: 'https://httpbin.org/post',
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: 'hello', value: 42 })
  }
};
// Returns: "[HTTP 200]\n{\"json\":{\"message\":\"hello\",\"value\":42},...}"
```

```typescript
// GET with custom headers
const fetchAuth = {
  name: 'fetch_url',
  input: {
    url: 'https://api.example.com/data',
    headers: { 'Authorization': 'Bearer token123' }
  }
};
// Subject to browser CORS restrictions
// HTML responses are auto-stripped to readable text
```

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

### Shell Emulator - executeShell()

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Executes bash-like commands in pure JavaScript over OPFS, supporting pipes, redirects, and variable expansion.

```APIDOC
## `executeShell(command, groupId, env?, timeoutSec?)`

### Description
Executes bash-like commands in pure JavaScript. Supports pipes, redirects, operators, and variable expansion without any VM or native binary.

### Parameters
- **command** (string) - Required - The bash-like command to execute.
- **groupId** (string) - Required - An identifier for the group context.
- **env** (object) - Optional - A key-value object for custom environment variables.
- **timeoutSec** (number) - Optional - The timeout in seconds for the command execution.

### Returns
- **Promise<object>** - A promise that resolves to an object containing `stdout`, `stderr`, and `exitCode`.
  - **stdout** (string) - The standard output of the command.
  - **stderr** (string) - The standard error of the command.
  - **exitCode** (number) - The exit code of the command.

### Examples
```javascript
// Simple command
await executeShell('echo "Hello, World!"', 'br:main');
// { stdout: 'Hello, World!\n', stderr: '', exitCode: 0 }

// Pipes and text processing
await executeShell('echo -e "banana\napple\ncherry\napple" | sort | uniq | wc -l', 'br:main');
// { stdout: '3\n', stderr: '', exitCode: 0 }

// File operations with redirect
await executeShell('echo "# TODO\n- Task 1\n- Task 2" > todo.md && cat todo.md', 'br:main');
// { stdout: '# TODO\n- Task 1\n- Task 2\n', stderr: '', exitCode: 0 }

// JSON processing with jq
await executeShell(`echo '{"users":[{"name":"Alice"},{"name":"Bob"}]}' | jq '.users[0].name'`, 'br:main');
// { stdout: '"Alice"\n', stderr: '', exitCode: 0 }

// Error handling
await executeShell('cat nonexistent.txt', 'br:main');
// { stdout: '', stderr: 'cat: nonexistent.txt: No such file', exitCode: 1 }

// Custom environment and timeout
await executeShell('echo $GREETING $NAME', 'br:main', { GREETING: 'Hello', NAME: 'World' }, 5);
// { stdout: 'Hello World\n', stderr: '', exitCode: 0 }
```
```

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

### IndexedDB Configuration Keys

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Import and utilize `CONFIG_KEYS` for accessing IndexedDB configuration settings within the application.

```typescript
import { CONFIG_KEYS } from './src/config';
// CONFIG_KEYS.ANTHROPIC_API_KEY  = 'anthropic_api_key'
// CONFIG_KEYS.TELEGRAM_BOT_TOKEN = 'telegram_bot_token'
// CONFIG_KEYS.TELEGRAM_CHAT_IDS  = 'telegram_chat_ids'
// CONFIG_KEYS.MODEL              = 'model'
// CONFIG_KEYS.MAX_TOKENS         = 'max_tokens'
// CONFIG_KEYS.ASSISTANT_NAME     = 'assistant_name'
```

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

### Set API Key, Model, and Assistant Name

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Configure the Orchestrator by setting the Anthropic API key, choosing the AI model, and defining a custom assistant name for triggering.

```typescript
// Check if a key is already configured
if (!orchestrator.isConfigured()) {
  const key = prompt('Enter your Anthropic API key:') ?? '';
  await orchestrator.setApiKey(key); // Encrypts and persists to IndexedDB
  console.log('API key saved. isConfigured:', orchestrator.isConfigured()); // true
}

// Change the model (default: 'claude-sonnet-4-6')
await orchestrator.setModel('claude-opus-4-5');
console.log('Active model:', orchestrator.getModel()); // 'claude-opus-4-5'

// Rename the assistant (changes @trigger pattern)
await orchestrator.setAssistantName('Aria');
// Now messages must include "@Aria" to trigger the agent in non-default groups
```

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

### Agent Tools - Bash

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

The `bash` tool allows the agent to execute shell commands within a sandboxed JavaScript-emulated shell. It supports various standard Unix commands, pipes, and redirects.

```APIDOC
## bash tool

### Description
Executes bash commands in a JS-emulated shell backed by OPFS. Supports pipes, redirects, and operators.

### Method
`bash.execute` (internal invocation)

### Parameters
#### Input Object
- **command** (string) - Required - The bash command to execute.
- **timeout** (number) - Optional - The maximum time in seconds to allow the command to run (default: 30, max: 120).

### Request Example
```typescript
// Example of executing a simple command
const bashTool = {
  name: 'bash',
  input: {
    command: 'echo "line1\nline2\nline3" | grep line | wc -l',
    timeout: 10
  }
};
// Returns: "3\n"

// Example with file operations
// command: 'echo "data" > output.txt && cat output.txt'
// Returns: "data\n"

// Example using jq for JSON processing
// command: 'echo '{"name":"Alice","score":95}\' | jq .name'
// Returns: '"Alice"\n'
```

### Response
#### Success Response
- **output** (string) - The standard output of the executed command.

### Supported Commands
echo, printf, cat, head, tail, wc, grep, sort, uniq, tr, cut, sed, awk, ls, mkdir, cp, mv, rm, touch, pwd, cd, date, sleep, seq, base64, jq, tee, xargs, test, rev, basename, dirname
```

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

### TaskScheduler / matchesCron()

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Evaluates standard 5-field cron expressions and provides a utility for direct cron matching.

```APIDOC
## `matchesCron(cronExpression, date)`

### Description
Evaluates a standard 5-field cron expression against a given date to determine if it matches.

### Parameters
- **cronExpression** (string) - Required - The 5-field cron expression to evaluate (minute hour day month weekday).
- **date** (Date) - Required - The date object to test against the cron expression.

### Returns
- **boolean** - True if the date matches the cron expression, false otherwise.

### Cron Syntax
- **Wildcards**: `*` (any)
- **Exact**: `5` (value 5)
- **Range**: `1-5` (Mon-Fri), `9-17` (business hours)
- **List**: `1,15` (1st and 15th)
- **Step**: `*/5` (every 5), `0-30/10` (0,10,20,30)

### Example
```javascript
matchesCron('0 9 * * 1-5', new Date('2025-03-10T09:00:00')); // true
matchesCron('*/15 * * * *', new Date('2025-03-10T09:00:00')); // true
```
```

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

### OPFS File Management for Groups

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Manages per-group file workspaces within the browser's Origin Private File System. Files are scoped to `openbrowserclaw/groups/<groupId>/`. Supports reading, writing, listing, and deleting files, as well as requesting persistent storage and checking storage estimates.

```typescript
import {
  readGroupFile, writeGroupFile, listGroupFiles,
  deleteGroupFile, groupFileExists, requestPersistentStorage, getStorageEstimate
} from './src/storage';

// Write a file (creates intermediate directories automatically)
await writeGroupFile('br:main', 'data/config.json', JSON.stringify({ version: 1 }));
await writeGroupFile('br:main', 'CLAUDE.md', '# Memory\n\nUser prefers TypeScript.');

// Read a file
const content = await readGroupFile('br:main', 'data/config.json');
// '{\"version\":1}'

// List files in a directory (dirs end with /)
const entries = await listGroupFiles('br:main', 'data');
// ['config.json', 'results/']  (sorted alphabetically)

// List root
const root = await listGroupFiles('br:main');
// ['CLAUDE.md', 'data/']

// Check existence
const exists = await groupFileExists('br:main', 'CLAUDE.md');
// true

// Delete a file
await deleteGroupFile('br:main', 'data/old-config.json');

// Request persistent storage (prevents browser eviction)
const granted = await requestPersistentStorage();
// true if browser granted persistence

// Get current storage usage
const { usage, quota } = await getStorageEstimate();
console.log(`Used: ${(usage / 1024 / 1024).toFixed(1)} MB / ${(quota / 1024 / 1024).toFixed(0)} MB`);
```

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

### Scheduled Tasks (`create_task`)

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Creates cron-scheduled tasks that automatically run a specified prompt. The scheduler operates while the browser tab is open.

```APIDOC
## `create_task`

### Description
Creates a cron-scheduled task that executes a given prompt at specified intervals.

### Method
Not applicable (Tool invocation)

### Parameters
#### Input
- **schedule** (string) - Required - The cron schedule string (e.g., '0 9 * * 1-5').
- **prompt** (string) - Required - The prompt to execute when the schedule fires.

### Request Example
```typescript
// Daily morning briefing at 9:00 AM weekdays
const taskTool = {
  name: 'create_task',
  input: {
    schedule: '0 9 * * 1-5',
    prompt: 'Give me a brief summary of: 1) weather in London, 2) top tech news from hackernews, 3) my upcoming tasks for today'
  }
};
```

### Response Example
```
Task created successfully.
Schedule: 0 9 * * 1-5
Prompt: Give me a brief...
```

### Cron Format Details
- Format: `minute hour day-of-month month day-of-week`
- Supports: `*` (any), `N` (exact), `N-M` (range), `N,M` (list), `*/N` (step).
- Examples:
  - Every hour: `0 * * * *`
  - Every 30 minutes: `*/30 * * * *`
  - Every Monday at noon: `0 12 * * 1`
```

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

### Persistent Memory (`update_memory`)

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

This tool writes content to `CLAUDE.md` in the group workspace. This file is loaded as system context on every conversation turn, providing persistent memory across sessions.

```APIDOC
## `update_memory`

### Description
Updates the persistent memory file `CLAUDE.md` with new content. This file serves as system context for future interactions.

### Method
Not applicable (Tool invocation)

### Parameters
#### Input
- **content** (string) - Required - The content to write to `CLAUDE.md`.

### Request Example
```typescript
const memoryTool = {
  name: 'update_memory',
  input: {
    content: `# User Preferences\n\n## Communication Style\n- Prefers concise, bullet-point answers\n- Uses metric units\n- Timezone: UTC+1\n\n## Active Projects\n- Project Alpha: React dashboard, deadline March 2025\n- Daily standup notes stored in notes/standups/\n\n## Important Context\n- Name: Alex\n- Primary language: TypeScript
`
  }
};
```

### Response Example
```
Memory updated successfully.
```

### Notes
`CLAUDE.md` is prepended to every future system prompt for this group.
```

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

### Database Operations for Messages, Config, and Tasks

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Manages persistent state including messages, sessions, tasks, and configuration. All functions return Promises. Ensure `openDatabase()` is called once before any other database function.

```typescript
import {
  openDatabase, saveMessage, getRecentMessages,
  buildConversationMessages, getConfig, setConfig,
  saveTask, getAllTasks, deleteTask, getEnabledTasks,
  clearGroupMessages
} from './src/db';

await openDatabase(); // Must be called once before any other db function

// Save a message
await saveMessage({
  id: 'msg_01ABC',
  groupId: 'br:main',
  sender: 'User',
  content: 'Hello!',
  timestamp: Date.now(),
  channel: 'browser',
  isFromMe: false,
  isTrigger: true,
});

// Get 50 most recent messages for a group (oldest-first)
const messages = await getRecentMessages('br:main', 50);
// [{ id, groupId, sender, content, timestamp, channel, isFromMe, isTrigger }, ...]

// Build Claude API conversation format from stored messages
const conversation = await buildConversationMessages('br:main', 50);
// [{ role: 'user', content: 'User: Hello!' }, { role: 'assistant', content: 'Hi there!' }]

// Config key-value store
await setConfig('model', 'claude-opus-4-5');
const model = await getConfig('model'); // 'claude-opus-4-5'

// Task management
const task = {
  id: 'task_01XYZ',
  groupId: 'br:main',
  schedule: '0 8 * * *',
  prompt: 'Check the weather and summarize it',
  enabled: true,
  lastRun: null,
  createdAt: Date.now(),
};
await saveTask(task);
const allTasks = await getAllTasks();  // Task[]
const enabled  = await getEnabledTasks(); // Task[] where enabled=true
await deleteTask('task_01XYZ');

// Clear a group's conversation history
await clearGroupMessages('br:main');
```

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

### Build Trigger Pattern with buildTriggerPattern

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Use `buildTriggerPattern` to create a regular expression for invoking the agent. The pattern is case-insensitive and matches the assistant's name when preceded by '@'.

```typescript
import {
  ASSISTANT_NAME,
  DEFAULT_MODEL,
  DEFAULT_MAX_TOKENS,
  CONTEXT_WINDOW_SIZE,
  ANTHROPIC_API_URL,
  SCHEDULER_INTERVAL,
  FETCH_MAX_RESPONSE,
  buildTriggerPattern,
} from './src/config';

// Build custom trigger pattern
const pattern = buildTriggerPattern('Andy');
pattern.test('@Andy hello');     // true
pattern.test('hey @andy!');      // true (case-insensitive)
pattern.test('hello world');     // false

const customPattern = buildTriggerPattern('Aria');
customPattern.test('@Aria help me'); // true
```

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

### Database Operations

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Functions for interacting with the persistent state, including messages, sessions, tasks, and configuration.

```APIDOC
## Database Operations

### Description
Manages persistent state including messages, sessions, tasks, and configuration. All functions return Promises.

### Functions

- **`openDatabase()`**: Must be called once before any other database function.
- **`saveMessage(message)`**: Saves a message object to the database.
- **`getRecentMessages(groupId, limit)`**: Retrieves the most recent messages for a given group.
- **`buildConversationMessages(groupId, limit)`**: Constructs conversation messages in a specific format from stored messages.
- **`setConfig(key, value)`**: Sets a configuration value.
- **`getConfig(key)`**: Retrieves a configuration value.
- **`saveTask(task)`**: Saves a task object.
- **`getAllTasks()`**: Retrieves all tasks.
- **`getEnabledTasks()`**: Retrieves tasks that are enabled.
- **`deleteTask(taskId)`**: Deletes a task by its ID.
- **`clearGroupMessages(groupId)`**: Clears all messages for a given group.
```

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

### Update Persistent Memory (CLAUDE.md)

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

This tool writes content to CLAUDE.md, which is loaded as system context for future conversations. Use it to store important information that should be remembered across sessions.

```typescript
// Claude updates memory when it learns something important
const memoryTool = {
  name: 'update_memory',
  input: {
    content: `# User Preferences

## Communication Style
- Prefers concise, bullet-point answers
- Uses metric units
- Timezone: UTC+1

## Active Projects
- Project Alpha: React dashboard, deadline March 2025
- Daily standup notes stored in notes/standups/

## Important Context
- Name: Alex
- Primary language: TypeScript
`
  }
};
// Returns: "Memory updated successfully."
// CLAUDE.md is now prepended to every future system prompt for this group
```

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

### TaskScheduler: Cron Scheduling and Matching

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Instantiate and manage scheduled tasks using cron expressions. The `matchesCron` function is exported for direct testing of cron expression validity against a given date.

```typescript
import { TaskScheduler, matchesCron } from './src/task-scheduler';

// Instantiate with a runner function
const scheduler = new TaskScheduler(async (groupId, prompt) => {
  // This is called when a task fires
  console.log(`Running scheduled task for ${groupId}: ${prompt}`);
  await orchestrator.invokeAgent(groupId, prompt); // internal method
});

scheduler.start(); // Checks for due tasks every 60 seconds
scheduler.stop();  // Clears the interval

// Direct cron matching (exported for testing)
const now = new Date('2025-03-10T09:00:00'); // Monday 9am

matchesCron('0 9 * * 1-5', now);  // true  — 9am weekdays
matchesCron('0 9 * * 0',   now);  // false — 9am Sundays only
matchesCron('*/15 * * * *', now); // true  — every 15 minutes (minute=0)
matchesCron('0 12 1 * *',  now);  // false — noon on 1st of month

// Cron syntax: "minute hour day month weekday"
// Wildcards:  * (any)
// Exact:      5 (value 5)
// Range:      1-5 (Mon-Fri), 9-17 (business hours)
// List:       1,15 (1st and 15th)
// Step:       */5 (every 5), 0-30/10 (0,10,20,30)
```

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

### OPFS Storage Layer

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Functions for managing files within the browser's Origin Private File System, scoped to specific groups.

```APIDOC
## OPFS Storage Layer

### Description
Manages per-group file workspaces in the browser's Origin Private File System. Files are scoped to `openbrowserclaw/groups/<groupId>/`.

### Functions

- **`writeGroupFile(groupId, filePath, content)`**: Writes content to a file within a group's workspace. Creates intermediate directories automatically.
- **`readGroupFile(groupId, filePath)`**: Reads the content of a file from a group's workspace.
- **`listGroupFiles(groupId, directoryPath)`**: Lists files and directories within a specified path in a group's workspace. Directories are indicated by a trailing '/'.
- **`groupFileExists(groupId, filePath)`**: Checks if a file exists within a group's workspace.
- **`deleteGroupFile(groupId, filePath)`**: Deletes a file from a group's workspace.
- **`requestPersistentStorage()`**: Requests persistent storage from the browser to prevent eviction.
- **`getStorageEstimate()`**: Retrieves the current storage usage and quota.
```

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

### Crypto Layer

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

Utilities for encrypting and decrypting sensitive values using AES-256-GCM.

```APIDOC
## Crypto Layer

### Description
Encrypts secrets with AES-256-GCM using a non-extractable `CryptoKey` stored in IndexedDB. The raw key material is never exposed to JavaScript.

### Functions

- **`encryptValue(value)`**: Encrypts a given string value. Returns a base64-encoded string containing the IV and ciphertext.
- **`decryptValue(encryptedValue)`**: Decrypts a base64-encoded string back into its original plaintext value.
```

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

### Loading Splash Screen Styles for OpenBrowserClaw

Source: https://github.com/wexare-ai/openbrowserclaw/blob/master/index.html

Styles the loading splash screen that appears when the #app element is empty before the React application mounts. It centers the 'Loading OpenBrowserClaw...' text.

```css
/* Loading splash — only applies when #app is empty (before React mounts) */
#app:empty {
  display: flex;
  align-items: center;
  justify-content: center;
}

#app:empty::before {
  content: 'Loading OpenBrowserClaw...';
  font-size: 16px;
  opacity: 0.5;
}
```

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

### EventBus - orchestrator.events

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

A typed event bus for subscribing to and emitting orchestrator lifecycle events.

```APIDOC
## `orchestrator.events.on(eventName, handler)` / `.off(eventName, handler)` / `.emit(eventName, payload)`

### Description
Provides methods to subscribe to, unsubscribe from, and emit events related to the orchestrator's lifecycle. All UI state is driven by these events.

### Methods
- **`on(eventName, handler)`**: Subscribes a handler function to a specific event.
- **`off(eventName, handler)`**: Unsubscribes a handler function from a specific event.
- **`emit(eventName, payload)`**: Emits an event with an optional payload.

### Event Names and Payloads
- **`typing`**: `{ groupId: string, typing: boolean }` - Indicates typing status for a group.
- **`thinking-log`**: `{ kind: 'api-call' | 'tool-call' | 'tool-result' | 'text' | 'info', label: string, detail?: string, timestamp: number }` - Logs thinking activity.
- **`message`**: `{ content: string, isFromMe: boolean }` - Represents a new message in the chat.
- **`token-usage`**: `{ inputTokens: number, outputTokens: number, contextLimit: number }` - Reports token usage against the context limit.
- **`state-change`**: `OrchestratorState` - Reports changes in the orchestrator's state.

### Example
```javascript
// Subscribe to typing events
orchestrator.events.on('typing', ({ groupId, typing }) => {
  document.getElementById('typing-indicator')!.hidden = !typing;
});

// Subscribe to message events
orchestrator.events.on('message', (msg) => {
  const bubble = document.createElement('div');
  bubble.className = msg.isFromMe ? 'assistant' : 'user';
  bubble.textContent = msg.content;
  document.getElementById('chat')!.append(bubble);
});

// Unsubscribe from state-change events
const handler = (state) => console.log(state);
orchestrator.events.on('state-change', handler);
orchestrator.events.off('state-change', handler);
```
```

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

### Evaluate JavaScript Code with Javascript Tool

Source: https://context7.com/wexare-ai/openbrowserclaw/llms.txt

The `javascript` tool enables Claude to execute JavaScript code directly within the Web Worker scope, offering fast execution for calculations, JSON transformations, and data processing without needing to boot a VM. The value of the last expression is automatically captured as the result.

```typescript
// Claude invokes the javascript tool:
const jsTool = {
  name: 'javascript',
  input: {
    code: `
      const data = [3, 1, 4, 1, 5, 9, 2, 6];
      const sorted = [...data].sort((a, b) => a - b);
      const sum = data.reduce((a, b) => a + b, 0);
      const avg = sum / data.length;
      ({ sorted, sum, avg: avg.toFixed(2) })
    `
  }
};
// Returns: '{
//   "sorted": [1,1,2,3,4,5,6,9],
//   "sum": 31,
//   "avg": "3.88"
// }'
```

```typescript
// String processing
// code: `"Hello, World!".split('').reverse().join('')`
// Returns: "!dlroW ,olleH"
```

```typescript
// Date calculations
// code: `new Date().toISOString()`
// Returns: "2025-01-15T10:30:00.000Z"
```

```typescript
// The last expression's value is captured automatically
// Undefined → "(no return value)", null → "null"
// Objects → JSON.stringify with 2-space indent
```

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

### Critical Path CSS for OpenBrowserClaw

Source: https://github.com/wexare-ai/openbrowserclaw/blob/master/index.html

Applies essential styles to prevent unstyled content flashes. Ensures the body has no default margin and the main app container fills the viewport with a system font.

```css
/* Critical path CSS — prevent flash of unstyled content */
body { margin: 0; }
#app { height: 100vh; height: 100dvh; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
```
Tokens:
Raw