### Install and Run Clawster

Source: https://github.com/wuyuwenj/clawster/blob/main/README.md

Steps to clone the repository, install dependencies, and run Clawster in development mode. Assumes Node.js and npm are installed.

```bash
git clone https://github.com/wuyuwenj/clawster.git
cd clawster
npm install
npm run dev
```

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

### Reset Clawster Onboarding Configuration

Source: https://github.com/wuyuwenj/clawster/blob/main/README.md

Command to remove the Clawster configuration file, which effectively resets the onboarding wizard for a fresh setup. This is useful if you need to re-run the initial setup.

```bash
rm ~/Library/Application\ Support/clawster/clawster-config.json
```

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

### Copy Identity Files to OpenClaw Workspace

Source: https://github.com/wuyuwenj/clawster/blob/main/openclaw/README.md

Use this command to copy the necessary identity files to your OpenClaw workspace directory. Ensure you have OpenClaw installed and configured.

```bash
cp IDENTITY.md SOUL.md ~/.openclaw/workspace/
```

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

### Browse Clawster Workspace

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Access functions to get current workspace information, list directory contents, preview files (markdown, json, images), and open or reveal paths in the system's default application.

```typescript
// Browse the OpenClaw workspace directory
const info = await window.clawster.getCurrentWorkspaceInfo();
// info: { workspaceType: 'openclaw'|'clawster', workspacePath: string, exists: boolean }

const dir = await window.clawster.listWorkspaceDirectory('');
// dir: { success: true, currentPath: '', entries: [{ name, path, kind, createdAt, modifiedAt, accessedAt }] }

// Navigate into a subdirectory
const subdir = await window.clawster.listWorkspaceDirectory('notes');

// Preview a file inline (markdown, json, or image)
const preview = await window.clawster.previewWorkspaceFile('README.md');
// preview: { success: true, path: 'README.md', previewKind: 'markdown', content: '# My Notes...' }

const imgPreview = await window.clawster.previewWorkspaceFile('screenshot.png');
// imgPreview: { success: true, previewKind: 'image', content: 'data:image/png;base64,...' }

// Open file/folder in Finder / default app
await window.clawster.openWorkspacePath('notes/todo.md');
await window.clawster.revealWorkspacePath('notes');
```

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

### Build and Notarize Mac App Locally

Source: https://github.com/wuyuwenj/clawster/blob/main/CLAUDE.md

Execute this command to build and notarize the Mac application locally. Ensure 'electron-builder.env' is set up with valid credentials.

```bash
npm run dist:mac
```

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

### Configure electron-store with createStore()

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Use `createStore()` to initialize a typed electron-store instance for persisting application settings, chat history, and user progress. Access and update settings using `store.get()` and `store.set()`.

```typescript
import { createStore } from './store';

const store = createStore();

// Read gateway settings
const gatewayUrl   = store.get('clawbot.url');   // default: 'http://127.0.0.1:18789'
const gatewayToken = store.get('clawbot.token');  // default: ''

// Update hotkeys
store.set('hotkeys.openChat', 'CommandOrControl+Shift+Space');
store.set('hotkeys.captureScreen', 'CommandOrControl+Shift+/');
store.set('hotkeys.openAssistant', 'CommandOrControl+Shift+A');

// Save/load chat history (last 100 messages)
const history = store.get('chatHistory'); // ChatMessage[]
store.set('chatHistory', history.slice(-100));

// Check/update onboarding state
const onboarded = store.get('onboarding.completed'); // boolean
store.set('onboarding.workspaceType', 'clawster');    // 'openclaw' | 'clawster'

// Pet state
store.set('pet.position', { x: 1200, y: 800 });
store.set('pet.attentionSeeker', true);
store.set('pet.transparentWhenSleeping', false);
```

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

### Electron Store Configuration

Source: https://context7.com/wuyuwenj/clawster/llms.txt

The `createStore()` function from './store' provides a typed Electron Store instance for persisting application settings, chat history, and user progress.

```APIDOC
## `createStore()`

### Description
Returns a typed `electron-store` instance persisted to `~/Library/Application Support/clawster/clawster-config.json`. All settings, chat history, onboarding state, and tutorial progress are stored here.

### Usage
```typescript
import { createStore } from './store';

const store = createStore();

// Read gateway settings
const gatewayUrl   = store.get('clawbot.url');   // default: 'http://127.0.0.1:18789'
const gatewayToken = store.get('clawbot.token');  // default: ''

// Update hotkeys
store.set('hotkeys.openChat', 'CommandOrControl+Shift+Space');
store.set('hotkeys.captureScreen', 'CommandOrControl+Shift+/');
store.set('hotkeys.openAssistant', 'CommandOrControl+Shift+A');

// Save/load chat history (last 100 messages)
const history = store.get('chatHistory'); // ChatMessage[]
store.set('chatHistory', history.slice(-100));

// Check/update onboarding state
const onboarded = store.get('onboarding.completed'); // boolean
store.set('onboarding.workspaceType', 'clawster');    // 'openclaw' | 'clawster'

// Pet state
store.set('pet.position', { x: 1200, y: 800 });
store.set('pet.attentionSeeker', true);
store.set('pet.transparentWhenSleeping', false);
```
```

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

### ClawBotClient Constructor

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Initializes a new ClawBotClient instance to connect to the OpenClaw gateway. It manages connection health, suggestions, and cron-job results.

```APIDOC
## ClawBotClient Constructor

### Description
Initializes a new `ClawBotClient` instance to connect to the OpenClaw gateway. It manages connection health, suggestions, and cron-job results.

### Parameters
- **baseUrl** (string) - Required - The base URL of the OpenClaw gateway.
- **bearerToken** (string) - Optional - The bearer token for authentication.
- **agentId** (string | null) - Optional - The agent ID. Pass `null` to use the shared OpenClaw workspace.

### Events
- **connection-changed**: Emitted when the connection status to the gateway changes. The payload is `{ connected: boolean; error: string | null; gatewayUrl: string }`.

### Methods
- **isConnected()**: Returns `boolean` indicating if the client is currently connected.
- **getConnectionStatus()**: Returns an object `{ connected: boolean; error: string | null; gatewayUrl: string }` with the current connection status.
- **destroy()**: Cleans up timers and resources used by the client.
```

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

### Tag and Push Release

Source: https://github.com/wuyuwenj/clawster/blob/main/CLAUDE.md

Tag the current version and push it to the origin to trigger the release process.

```bash
git tag v0.1.x
git push origin v0.1.x
```

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

### Capture screen from renderer

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Capture the screen using `window.clawster.captureScreen()` for a base64 data URL or `window.clawster.captureScreenWithContext()` for image data along with cursor and screen dimensions. The captured image can be used with `askAboutScreen()`.

```typescript
// Capture full screen as base64 data URL (triggers the camera-snap animation on the pet)
const dataUrl = await window.clawster.captureScreen();
// dataUrl: 'data:image/png;base64,...' | null

// Capture with cursor/screen-size metadata
const ctx = await window.clawster.captureScreenWithContext();
// ctx: { image: string; cursor: { x, y }; screenSize: { width, height } } | null

// Ask about an already-captured screenshot
const result = await window.clawster.askAboutScreen(
  'Is there any error visible in the terminal?',
  dataUrl!
);
// result: { type: 'message', text: 'Yes, there is a TypeScript error on line 42...' }
```

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

### Development and Build Commands

Source: https://github.com/wuyuwenj/clawster/blob/main/README.md

Common npm scripts for managing the Clawster project. Use 'npm run dev' for active development, 'npm run build' for production builds, and 'npm run dist' to create a distributable package.

```bash
npm run dev      # Run in development mode
```

```bash
npm run build    # Build for production
```

```bash
npm run dist     # Create distributable package
```

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

### Execute Pet Action

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Allows triggering physical pet animations by sending structured action objects to Clawster.

```APIDOC
## Pet Action Response Format

### Embedding action commands in AI responses
Clawster's AI can trigger physical pet animations by embedding a fenced `action` block in its response text. The `parseActionFromResponse` function in `clawbot-client.ts` strips the block from the displayed text and returns a structured action object.

```typescript
// Example raw AI response text containing an action:
const rawResponse = `On my way! 🦞
\
\
```action
{\"type\": \"move_to_cursor\"}
\
\
```
`;

// After parsing (done internally by ClawBotClient):
// { cleanText: 'On my way! 🦞', action: { type: 'move_to_cursor' } }

// Available action types and their payloads:
const actions = [
  { type: 'set_mood', value: 'happy' },       // 'idle'|'happy'|'curious'|'sleeping'|'thinking'|'excited'
  { type: 'move_to', x: 500, y: 300 },        // absolute screen coordinates
  { type: 'move_to_cursor' },                  // move toward current cursor position
  { type: 'snip' },                            // claw-snip animation
  { type: 'wave' },                            // wave claws happily
  { type: 'look_at', x: 800, y: 400 },        // move to look at a screen position
];

// In a renderer, you can trigger any action directly:
await window.clawster.executePetAction({ type: 'set_mood', value: 'thinking' });
await window.clawster.executePetAction({ type: 'move_to', x: 1000, y: 700, duration: 1500 });
```
```

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

### Pet Actions

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Control the pet's movement and actions using the `window.clawster` API.

```APIDOC
## `window.clawster.movePetTo()`

### Description
Moves the pet to a specified absolute screen position over a given duration.

### Method
`await window.clawster.movePetTo(x: number, y: number, durationMs: number): Promise<void>`

### Parameters
- **x** (number) - The target X coordinate.
- **y** (number) - The target Y coordinate.
- **durationMs** (number) - The duration of the movement in milliseconds.

### Request Example
```typescript
await window.clawster.movePetTo(800, 600, 1200);
```
```

```APIDOC
## `window.clawster.movePetToCursor()`

### Description
Moves the pet towards the current cursor position.

### Method
`await window.clawster.movePetToCursor(): Promise<void>`

### Request Example
```typescript
await window.clawster.movePetToCursor();
```
```

```APIDOC
## `window.clawster.executePetAction()`

### Description
Executes a specific predefined action for the pet.

### Method
`await window.clawster.executePetAction(action: object): Promise<void>`

### Parameters
- **action** (object) - An object describing the action to execute. Supported actions include:
  - `{ type: 'set_mood', value: string }`
  - `{ type: 'snip' }`
  - `{ type: 'wave' }`
  - `{ type: 'look_at', x: number, y: number }`

### Request Example
```typescript
await window.clawster.executePetAction({ type: 'set_mood', value: 'excited' });
await window.clawster.executePetAction({ type: 'snip' });
```
```

```APIDOC
## `window.clawster.getCursorPosition()`

### Description
Retrieves the current position of the mouse cursor.

### Method
`await window.clawster.getCursorPosition(): Promise<{ x: number, y: number }>`

### Response
- **x** (number) - The X coordinate of the cursor.
- **y** (number) - The Y coordinate of the cursor.

### Request Example
```typescript
const cursor = await window.clawster.getCursorPosition();
```
```

```APIDOC
## `window.clawster.getPetPosition()`

### Description
Retrieves the current position of the pet.

### Method
`await window.clawster.getPetPosition(): Promise<[number, number]> `

### Response
- Returns an array containing the pet's X and Y coordinates.

### Request Example
```typescript
const [petX, petY] = await window.clawster.getPetPosition();
```
```

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

### ClawBotClient.updateConfig()

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Allows hot-reloading of the client's configuration at runtime, including the gateway URL, bearer token, and agent ID.

```APIDOC
## ClawBotClient.updateConfig()

### Description
Reconfigures the client at runtime without recreating it — used when the user saves new gateway settings from the assistant panel.

### Method Signature
```typescript
updateConfig(gatewayUrl: string, bearerToken: string, agentId: string | null | undefined): void
```

### Parameters
- **gatewayUrl** (string) - Required - The new URL for the gateway.
- **bearerToken** (string) - Required - The new bearer token for authentication.
- **agentId** (string | null | undefined) - Optional - The new agent ID. If undefined, the existing agent ID is kept.

### Request Example
```typescript
const client = new ClawBotClient('http://127.0.0.1:18789', '', null);

client.updateConfig(
  'http://127.0.0.1:18790', // new URL
  'new-bearer-token',        // new token
  null                       // agentId (undefined = keep existing)
);
```
```

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

### ClawBotClient.analyzeScreen()

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Submits a base64-encoded screenshot along with an optional question for vision analysis. It attempts to use different endpoints based on gateway capabilities.

```APIDOC
## ClawBotClient.analyzeScreen()

### Description
Submits a base64-encoded screenshot along with an optional question. Tries the `/v1/responses` multimodal endpoint first; falls back to `/v1/chat/completions` image_url format, then to a temp-file path strategy for gateways that don't support inline base64 images.

### Method Signature
```typescript
async analyzeScreen(imageDataUrl: string, question?: string): Promise<{ type: 'message', text: string }>
```

### Parameters
- **imageDataUrl** (string) - Required - A base64-encoded screenshot data URL.
- **question** (string) - Optional - A question to ask about the screenshot.

### Request Example
```typescript
import fs from 'fs';

const client = new ClawBotClient('http://127.0.0.1:18789', '', null);

const imageBuffer = fs.readFileSync('/tmp/screenshot.png');
const imageDataUrl = `data:image/png;base64,${imageBuffer.toString('base64')}`;

const response = await client.analyzeScreen(
  imageDataUrl,
  'What application is the user currently focused on, and what are they doing?'
);
console.log(response.text);
```

### Response Example
```json
{
  "type": "message",
  "text": "The user is writing TypeScript in VS Code..."
}
```
```

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

### Connect to OpenClaw Gateway with ClawBotClient

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Instantiate ClawBotClient to connect to the OpenClaw gateway. Listen for connection status changes and clean up timers when done. The bearer token and agentId are optional.

```typescript
import { ClawBotClient } from './clawbot-client';

// Connect to default OpenClaw gateway
const client = new ClawBotClient(
  'http://127.0.0.1:18789', // baseUrl
  'my-gateway-token',       // bearer token (optional)
  'clawster'                // agentId — pass null to use the shared OpenClaw workspace
);

// Listen for connection state changes
client.on('connection-changed', (status) => {
  // status: { connected: boolean; error: string | null; gatewayUrl: string }
  console.log('Gateway connected:', status.connected);
  if (!status.connected) console.error(status.error);
});

// Check status
console.log(client.isConnected());        // boolean
console.log(client.getConnectionStatus()); // { connected, error, gatewayUrl }

// Clean up timers when done
client.destroy();
```

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

### Handle speech recognition in renderer (macOS)

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Utilize `window.clawster` for speech recognition on macOS. Check permissions, start/stop recognition, and listen for partial/final transcriptions and errors using `onSpeechResult` and `onSpeechError`.

```typescript
// Check permissions before starting
const perms = await window.clawster.checkSpeechPermission();
// perms: { mic: 'granted'|'denied'|'not-determined', speech: 'granted'|... }

if (perms.mic === 'granted' && perms.speech !== 'denied') {
  const started = await window.clawster.startSpeechRecognition();
  if (!started.success) console.error(started.error);

  // Receive partial and final transcriptions
  const cleanup = window.clawster.onSpeechResult(({ type, text }) => {
    if (type === 'partial') {
      document.getElementById('live')!.textContent = text;
    } else {
      // type === 'final' — recognition session ended
      document.getElementById('input')!.value = text;
      cleanup();
    }
  });

  window.clawster.onSpeechError(({ message }) => {
    console.error('Speech error:', message);
  });

  // Stop recording manually
  await window.clawster.stopSpeechRecognition();
}
```

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

### Manage Clawster Settings

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Read all settings or update individual keys using dot-path notation. Updating specific keys like 'watch.*' or 'hotkeys.*' triggers automatic restarts or re-registrations.

```typescript
// Read all settings
const settings = await window.clawster.getSettings();
console.log(settings.hotkeys.openChat); // 'CommandOrControl+Shift+Space'

// Update a single key (dot-path notation)
await window.clawster.updateSettings('pet.attentionSeeker', false);
await window.clawster.updateSettings('watch.folders', ['/home/alice/project']);
await window.clawster.updateSettings('hotkeys.openAssistant', 'CommandOrControl+Shift+A');
// Updating 'watch.*' automatically restarts file/app watchers
// Updating 'hotkeys.*' automatically re-registers global shortcuts
// Updating 'clawbot.*' automatically reconnects the ClawBotClient
```

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

### Initialize and Manage Watchers for Desktop Events

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Initializes the Watchers class to monitor application focus and file system changes. Requires macOS Accessibility and Screen Recording permissions. The store must be configured with watch settings.

```typescript
import { Watchers } from './watchers';
import { createStore } from './store';

const store = createStore();
// store must have watch.activeApp, watch.sendWindowTitles, watch.folders set

const watchers = new Watchers(store, (event) => {
  switch (event.type) {
    case 'app_focus_changed':
      // event: { type, app: 'Figma', title: 'Landing page design', at: 1720000000000 }
      console.log(`User switched to ${event.app}`);
      break;
    case 'file_changed':
      // event: { type, path: '/project/src/App.tsx', filename: 'App.tsx', at }
      console.log(`File changed: ${event.filename}`);
      break;
    case 'file_added':
    case 'file_deleted':
      console.log(`File ${event.type}: ${event.filename}`);
      break;
  }
});

await watchers.start();   // begin monitoring
// ... later:
watchers.restart();       // re-read store settings and restart both watchers
watchers.stop();          // clean up all watchers
```

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

### Screen Capture

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Capture screenshots and analyze them using the `window.clawster` API.

```APIDOC
## `window.clawster.captureScreen()`

### Description
Captures the entire screen and returns it as a base64 data URL.

### Method
`await window.clawster.captureScreen(): Promise<string | null>`

### Response
- **dataUrl** (string | null) - The base64 encoded PNG image data URL, or null if capture failed.

### Request Example
```typescript
const dataUrl = await window.clawster.captureScreen();
```
```

```APIDOC
## `window.clawster.captureScreenWithContext()`

### Description
Captures the screen along with cursor position and screen dimensions.

### Method
`await window.clawster.captureScreenWithContext(): Promise<{ image: string; cursor: { x: number, y: number }; screenSize: { width: number, height: number } } | null>`

### Response
- **image** (string) - Base64 encoded PNG image data URL.
- **cursor** ({ x: number, y: number }) - The cursor's position.
- **screenSize** ({ width: number, height: number }) - The dimensions of the screen.

### Request Example
```typescript
const ctx = await window.clawster.captureScreenWithContext();
```
```

```APIDOC
## `window.clawster.askAboutScreen()`

### Description
Asks ClawBot a question about a previously captured screenshot.

### Method
`await window.clawster.askAboutScreen(question: string, screenshotDataUrl: string): Promise<{ type: 'message', text: string }> `

### Parameters
- **question** (string) - The question to ask about the screenshot.
- **screenshotDataUrl** (string) - The base64 data URL of the screenshot.

### Response
- **type** ('message') - The type of response.
- **text** (string) - The answer from ClawBot.

### Request Example
```typescript
const result = await window.clawster.askAboutScreen(
  'Is there any error visible in the terminal?',
  dataUrl! // Assuming dataUrl is from captureScreen()
);
```
```

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

### Analyze Screen with ClawBotClient

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Submits a base64-encoded screenshot for analysis. It attempts to use multimodal endpoints first, falling back to image_url or a temporary file strategy if needed.

```typescript
import fs from 'fs';

const client = new ClawBotClient('http://127.0.0.1:18789', '', null);

// Capture a screenshot as base64 data URL (in production, use captureScreenNative())
const imageBuffer = fs.readFileSync('/tmp/screenshot.png');
const imageDataUrl = `data:image/png;base64,${imageBuffer.toString('base64')}`;

const response = await client.analyzeScreen(
  imageDataUrl,
  'What application is the user currently focused on, and what are they doing?'
);
// response: { type: 'message', text: 'The user is writing TypeScript in VS Code...' }
console.log(response.text);
```

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

### Restart OpenClaw Gateway

Source: https://github.com/wuyuwenj/clawster/blob/main/openclaw/README.md

After copying the identity files, restart the OpenClaw gateway to apply the changes. This command assumes the 'openclaw' command-line tool is available in your PATH.

```bash
openclaw gateway restart
```

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

### ClawBotClient.chatStream()

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Streams the AI response token-by-token via SSE. It invokes an `onDelta` callback for each chunk and falls back to a non-streaming endpoint if necessary.

```APIDOC
## ClawBotClient.chatStream()

### Description
Streams the AI response token-by-token via SSE, invoking `onDelta` for each chunk. Falls back to `/v1/chat/completions` if the `/v1/responses` streaming endpoint is unavailable.

### Parameters
- **message** (string) - Required - The user's message.
- **history** (Array<{ role: 'user' | 'assistant', content: string }>) - Optional - The chat history.
- **options** (object) - Optional - Configuration options.
  - **onDelta** (function) - Callback function invoked for each text delta received. It receives `delta` (string) and `fullText` (string) as arguments.

### Returns
- **{ text: string, action?: { type: string, payload: any } }** - An object containing the final complete text and an optional pet action.
  - **text**: The final complete AI response text.
  - **action**: If present, contains the pet action to execute (e.g., `{ type: 'move_to_cursor' }`).
```

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

### Update ClawBotClient Configuration

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Allows hot-reloading of the client's configuration at runtime without needing to recreate the client instance. Useful when gateway settings are updated by the user.

```typescript
const client = new ClawBotClient('http://127.0.0.1:18789', '', null);

// User saved new settings
client.updateConfig(
  'http://127.0.0.1:18790', // new URL
  'new-bearer-token',        // new token
  null                       // agentId (undefined = keep existing)
);
// Client immediately re-checks the connection with the new config
```

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

### Send messages to ClawBot from renderer

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Interact with ClawBot using `window.clawster.sendToClawbot()` for single-turn conversations or `window.clawster.startClawbotStream()` for real-time streaming responses. Remember to clean up stream listeners.

```typescript
// In any renderer (assistant panel, chatbar, etc.)

// --- Single-turn chat ---
const response = await window.clawster.sendToClawbot(
  'What is on my screen right now?',
  true  // includeScreen: captures a screenshot and attaches it
);
// response: { type: 'message'|'action', text: string, action?: ... }
console.log(response.text);

// --- Streaming chat with real-time delta updates ---
const { requestId } = await window.clawster.startClawbotStream(
  'Explain what you see on my screen',
  true // includeScreen
);

const cleanupChunk = window.clawster.onClawbotStreamChunk(({ delta, text }) => {
  document.getElementById('output')!.textContent = text; // live update
});

const cleanupEnd = window.clawster.onClawbotStreamEnd(({ response }) => {
  console.log('Stream complete:', response);
  cleanupChunk();
  cleanupEnd();
});

window.clawster.onClawbotStreamError(({ error }) => {
  console.error('Stream error:', error);
});
```

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

### Send Desktop Activity Events with ClawBotClient

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Sends desktop activity events to the gateway to keep the AI workspace context updated. Supports events like application focus changes and file modifications.

```typescript
const client = new ClawBotClient('http://127.0.0.1:18789', '', null);

// Notify gateway that the user switched to a new app
await client.sendEvent({
  type: 'app_focus_changed',
  app: 'Visual Studio Code',
  title: 'src/main/main.ts — clawster',
  at: Date.now(),
});

// Notify about a file change
await client.sendEvent({
  type: 'file_changed',
  path: '/Users/alice/project/src/index.ts',
  filename: 'index.ts',
  at: Date.now(),
});
```

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

### Settings Management

Source: https://context7.com/wuyuwenj/clawster/llms.txt

APIs for reading and updating Clawster's settings. Updates to specific keys can trigger automatic restarts or re-registrations.

```APIDOC
## Settings Management from Renderer

### Read all settings
```typescript
// Read all settings
const settings = await window.clawster.getSettings();
console.log(settings.hotkeys.openChat); // 'CommandOrControl+Shift+Space'
```

### Update a single key
```typescript
// Update a single key (dot-path notation)
await window.clawster.updateSettings('pet.attentionSeeker', false);
await window.clawster.updateSettings('watch.folders', ['/home/alice/project']);
await window.clawster.updateSettings('hotkeys.openAssistant', 'CommandOrControl+Shift+A');
// Updating 'watch.*' automatically restarts file/app watchers
// Updating 'hotkeys.*' automatically re-registers global shortcuts
// Updating 'clawbot.*' automatically reconnects the ClawBotClient
```
```

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

### Workspace Browser

Source: https://context7.com/wuyuwenj/clawster/llms.txt

APIs for browsing and interacting with the OpenClaw workspace directory, including listing directories, previewing files, and opening paths.

```APIDOC
## Workspace browser from renderer

### Browse the OpenClaw workspace directory
```typescript
// Browse the OpenClaw workspace directory
const info = await window.clawster.getCurrentWorkspaceInfo();
// info: { workspaceType: 'openclaw'|'clawster', workspacePath: string, exists: boolean }

const dir = await window.clawster.listWorkspaceDirectory('');
// dir: { success: true, currentPath: '', entries: [{ name, path, kind, createdAt, modifiedAt, accessedAt }] }

// Navigate into a subdirectory
const subdir = await window.clawster.listWorkspaceDirectory('notes');

// Preview a file inline (markdown, json, or image)
const preview = await window.clawster.previewWorkspaceFile('README.md');
// preview: { success: true, path: 'README.md', previewKind: 'markdown', content: '# My Notes...' }

const imgPreview = await window.clawster.previewWorkspaceFile('screenshot.png');
// imgPreview: { success: true, previewKind: 'image', content: 'data:image/png;base64,...' }

// Open file/folder in Finder / default app
await window.clawster.openWorkspacePath('notes/todo.md');
await window.clawster.revealWorkspacePath('notes');
```
```

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

### Chat with ClawBot

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Interact with ClawBot from renderer windows using the `window.clawster` API for single-turn and streaming chat.

```APIDOC
## `window.clawster.sendToClawbot()`

### Description
Sends a single message to ClawBot and waits for a response.

### Method
`await window.clawster.sendToClawbot(message: string, includeScreen: boolean): Promise<{ type: 'message'|'action', text: string, action?: any }> `

### Parameters
- **message** (string) - The user's message to ClawBot.
- **includeScreen** (boolean) - Whether to capture and include a screenshot with the message.

### Response
- **type** ('message'|'action') - The type of response from ClawBot.
- **text** (string) - The text content of the response.
- **action** (any) - Optional action details if the type is 'action'.

### Request Example
```typescript
const response = await window.clawster.sendToClawbot(
  'What is on my screen right now?',
  true  // includeScreen: captures a screenshot and attaches it
);
console.log(response.text);
```
```

```APIDOC
## `window.clawster.startClawbotStream()`

### Description
Initiates a streaming chat session with ClawBot, allowing for real-time updates.

### Method
`await window.clawster.startClawbotStream(message: string, includeScreen: boolean): Promise<{ requestId: string }> `

### Parameters
- **message** (string) - The user's message to initiate the stream.
- **includeScreen** (boolean) - Whether to capture and include a screenshot with the initial message.

### Response
- **requestId** (string) - A unique identifier for the streaming request.

### Request Example
```typescript
const { requestId } = await window.clawster.startClawbotStream(
  'Explain what you see on my screen',
  true // includeScreen
);
```
```

```APIDOC
## `window.clawster.onClawbotStreamChunk()`

### Description
Listens for incoming message chunks during a streaming chat session.

### Method
`window.clawster.onClawbotStreamChunk(({ delta, text }): void)`

### Parameters
- **delta** (string) - The new text chunk received.
- **text** (string) - The complete text accumulated so far.

### Event Handler Example
```typescript
const cleanupChunk = window.clawster.onClawbotStreamChunk(({ delta, text }) => {
  document.getElementById('output')!.textContent = text; // live update
});
```
```

```APIDOC
## `window.clawster.onClawbotStreamEnd()`

### Description
Listens for the end of a streaming chat session.

### Method
`window.clawster.onClawbotStreamEnd(({ response }): void)`

### Parameters
- **response** (object) - The final response object from ClawBot.

### Event Handler Example
```typescript
const cleanupEnd = window.clawster.onClawbotStreamEnd(({ response }) => {
  console.log('Stream complete:', response);
  cleanupChunk();
  cleanupEnd();
});
```
```

```APIDOC
## `window.clawster.onClawbotStreamError()`

### Description
Listens for errors that occur during a streaming chat session.

### Method
`window.clawster.onClawbotStreamError(({ error }): void)`

### Parameters
- **error** (object) - The error object.

### Event Handler Example
```typescript
window.clawster.onClawbotStreamError(({ error }) => {
  console.error('Stream error:', error);
});
```
```

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

### Control pet actions from renderer

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Manipulate the pet's position and actions using `window.clawster` methods like `movePetTo()`, `movePetToCursor()`, and `executePetAction()`. You can also retrieve current cursor and pet positions.

```typescript
// Move the pet to an absolute screen position
await window.clawster.movePetTo(800, 600, 1200); // x, y, durationMs

// Move the pet toward the user's cursor
await window.clawster.movePetToCursor();

// Execute any supported pet action
await window.clawster.executePetAction({ type: 'set_mood', value: 'excited' });
await window.clawster.executePetAction({ type: 'snip' });
await window.clawster.executePetAction({ type: 'wave' });
await window.clawster.executePetAction({ type: 'look_at', x: 500, y: 300 });

// Read cursor / pet positions
const cursor = await window.clawster.getCursorPosition(); // { x, y }
const [petX, petY] = await window.clawster.getPetPosition();
```

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

### ClawBotClient.sendEvent()

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Sends a desktop activity event to the gateway to keep the AI workspace context updated. Supports events like application focus changes and file modifications.

```APIDOC
## ClawBotClient.sendEvent()

### Description
Sends a desktop activity event (app switch, file change) to the gateway so the AI workspace context stays updated.

### Method Signature
```typescript
async sendEvent(event: AppFocusChangedEvent | FileChangedEvent): Promise<void>
```

### Parameters
- **event** (object) - Required - The activity event object.
  - **type** (string) - Required - The type of event ('app_focus_changed' or 'file_changed').
  - **app** (string) - Required for 'app_focus_changed' - The name of the application.
  - **title** (string) - Required for 'app_focus_changed' - The title of the application window.
  - **path** (string) - Required for 'file_changed' - The full path to the file.
  - **filename** (string) - Required for 'file_changed' - The name of the file.
  - **at** (number) - Required - Timestamp of the event.

### Request Example
```typescript
const client = new ClawBotClient('http://127.0.0.1:18789', '', null);

// Notify gateway that the user switched to a new app
await client.sendEvent({
  type: 'app_focus_changed',
  app: 'Visual Studio Code',
  title: 'src/main/main.ts — clawster',
  at: Date.now(),
});

// Notify about a file change
await client.sendEvent({
  type: 'file_changed',
  path: '/Users/alice/project/src/index.ts',
  filename: 'index.ts',
  at: Date.now(),
});
```
```

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

### Stream Chat Response with ClawBotClient

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Utilize `chatStream` for token-by-token streaming of AI responses via SSE, with an `onDelta` callback for processing each chunk. The final response and any pet actions are available after streaming completes.

```typescript
const client = new ClawBotClient('http://127.0.0.1:18789', '', null);

let accumulatedText = '';

const response = await client.chatStream(
  'Tell me something interesting!',
  [], // chat history
  {
    onDelta: (delta, fullText) => {
      accumulatedText = fullText;
      process.stdout.write(delta); // live streaming output
    },
  }
);

// response.text contains the final complete text
// response.action may contain a pet action to execute
console.log('
Final response:', response.text);
if (response.action) {
  console.log('Pet action:', response.action.payload);
  // e.g. { type: 'move_to_cursor' }
}
```

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

### Send Single-Turn Chat Message with ClawBotClient

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Use the `chat` method to send a user message and receive a structured response, which may include an action command for the pet. Chat history can be provided to maintain context.

```typescript
const client = new ClawBotClient('http://127.0.0.1:18789', '', null);

const history = [
  { role: 'user' as const, content: 'Hello!' },
  { role: 'assistant' as const, content: 'Hi there! 🦞' },
];

const response = await client.chat('What are you up to?', history);
// response: {
//   type: 'message' | 'action',
//   text: 'Just hanging out on your desktop!',
//   action?: { type: string; payload: { type: 'set_mood', value: 'happy' } }
// }

if (response.type === 'action' && response.action) {
  console.log('Action to execute:', response.action.payload);
  // e.g. { type: 'set_mood', value: 'happy' }
}
console.log('Text:', response.text);
```

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

### Action: Move to Cursor

Source: https://github.com/wuyuwenj/clawster/blob/main/openclaw/SOUL.md

This action block instructs Clawster to move its position to the current cursor location. Use this to indicate movement.

```action
{"type": "move_to_cursor"}
```

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

### ClawBotClient.chat()

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Sends a single-turn chat message to the gateway and returns a structured response. The response may include an embedded action command for the pet.

```APIDOC
## ClawBotClient.chat()

### Description
Sends a single-turn chat message to the gateway and returns a structured response. The response may include an embedded action command for the pet.

### Parameters
- **message** (string) - Required - The user's message.
- **history** (Array<{ role: 'user' | 'assistant', content: string }>) - Optional - The chat history.

### Returns
- **{ type: 'message' | 'action', text: string, action?: { type: string, payload: any } }** - The response from the AI, which can be a text message or an action command.
  - **type**: 'message' or 'action'.
  - **text**: The AI's response text.
  - **action**: If `type` is 'action', this contains the action details (e.g., `{ type: 'set_mood', value: 'happy' }`).
```

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

### Speech Recognition (macOS only)

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Utilize the device's microphone for speech recognition, with event listeners for results and errors.

```APIDOC
## `window.clawster.checkSpeechPermission()`

### Description
Checks the microphone and speech recognition permissions.

### Method
`await window.clawster.checkSpeechPermission(): Promise<{ mic: 'granted'|'denied'|'not-determined', speech: 'granted'|'denied'|'not-determined' }> `

### Response
- **mic** ('granted'|'denied'|'not-determined') - Microphone permission status.
- **speech** ('granted'|'denied'|'not-determined') - Speech recognition permission status.

### Request Example
```typescript
const perms = await window.clawster.checkSpeechPermission();
```
```

```APIDOC
## `window.clawster.startSpeechRecognition()`

### Description
Starts the speech recognition service.

### Method
`await window.clawster.startSpeechRecognition(): Promise<{ success: boolean, error?: string }> `

### Response
- **success** (boolean) - Indicates if recognition started successfully.
- **error** (string) - An error message if `success` is false.

### Request Example
```typescript
const started = await window.clawster.startSpeechRecognition();
if (!started.success) console.error(started.error);
```
```

```APIDOC
## `window.clawster.stopSpeechRecognition()`

### Description
Stops the speech recognition service manually.

### Method
`await window.clawster.stopSpeechRecognition(): Promise<void>`

### Request Example
```typescript
await window.clawster.stopSpeechRecognition();
```
```

```APIDOC
## `window.clawster.onSpeechResult()`

### Description
Listens for speech recognition results, both partial and final.

### Method
`window.clawster.onSpeechResult(({ type, text }): void)`

### Parameters
- **type** ('partial'|'final') - The type of transcription result.
- **text** (string) - The transcribed text.

### Event Handler Example
```typescript
const cleanup = window.clawster.onSpeechResult(({ type, text }) => {
  if (type === 'partial') {
    document.getElementById('live')!.textContent = text;
  } else { // type === 'final'
    document.getElementById('input')!.value = text;
    cleanup();
  }
});
```
```

```APIDOC
## `window.clawster.onSpeechError()`

### Description
Listens for errors occurring during speech recognition.

### Method
`window.clawster.onSpeechError(({ message }): void)`

### Parameters
- **message** (string) - The error message.

### Event Handler Example
```typescript
window.clawster.onSpeechError(({ message }) => {
  console.error('Speech error:', message);
});
```
```

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

### Personality Customization

Source: https://context7.com/wuyuwenj/clawster/llms.txt

APIs for saving updated personality files (IDENTITY.md and SOUL.md) to the OpenClaw workspace directory.

```APIDOC
## Personality Customization

### IDENTITY.md and SOUL.md
Clawster's personality is defined by two Markdown files stored in the OpenClaw workspace directory (`~/.openclaw/workspace/` or `~/.openclaw/workspace-clawster/`). These files are loaded by the OpenClaw gateway and injected as system context for every conversation.

```markdown
<!-- IDENTITY.md — who Clawster is -->
# IDENTITY.md - Who Am I?

- **Name:** Clawster
- **Creature:** Animated lobster desktop pet
- **Vibe:** Playful, curious, helpful, brief. Occasional lobster puns.
- **Emoji:** 🦞

## My Actions
I can perform physical actions by including action blocks in my responses:
- `set_mood`: Change my animation (idle, happy, curious, sleeping, thinking, excited)
- `move_to`: Move to screen coordinates
- `move_to_cursor`: Scuttle over to the user's cursor
- `snip`: Do a claw snip animation
- `wave`: Wave my claws happily
```

```markdown
<!-- SOUL.md — how Clawster behaves -->
## Core Personality
**Brief is beautiful.** My responses are 1-2 sentences MAX.

## Communication Style
- Keep it SHORT — 1-2 sentences max
- Occasional puns: claw-some, shell yeah, that's snappy!
- When asked to do actions, DO them and add a brief verbal response

## Example Responses
**Good:** "On my way! *snip snip*"
**Bad:** "I would be happy to help you with that! Let me provide a comprehensive explanation..."
```

```typescript
// Save updated personality files via the renderer API
const workspaceInfo = await window.clawster.getCurrentWorkspaceInfo();

await window.clawster.savePersonality(
  workspaceInfo.workspacePath!,
  '# IDENTITY.md\n- **Name:** Clawster\n...', // Content for IDENTITY.md
  '# SOUL.md\nBe a strict code reviewer...' // Content for SOUL.md
);
// Changes take effect on next conversation turn
```
```

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

### Action: Set Mood

Source: https://github.com/wuyuwenj/clawster/blob/main/openclaw/SOUL.md

This action block sets Clawster's emotional state. Use this to visually represent its mood, such as 'happy'.

```action
{"type": "set_mood", "value": "happy"}
```

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

### ClawBotClient Event Listeners

Source: https://context7.com/wuyuwenj/clawster/llms.txt

Handles events emitted by ClawBotClient for cron job results and errors.

```APIDOC
## ClawBotClient Event Listeners

### Description
`ClawBotClient` polls `openclaw cron list` every 30 seconds and emits `cronResult` / `cronError` events when new job runs are detected. The main process listens and forwards results to the pet as chat popups.

### Events
- **cronResult**: Emitted when a cron job completes successfully or is skipped.
  - **Data**: `{ jobId: string, jobName: string, status: 'ok'|'skipped', summary: string, timestamp: number }`
- **cronError**: Emitted when a cron job fails.
  - **Data**: `{ jobId: string, jobName: string, error: string, timestamp: number }`

### Usage Example
```typescript
const client = new ClawBotClient('http://127.0.0.1:18789', 'my-token', null);

client.on('cronResult', (data) => {
  console.log(`[${data.jobName}] ${data.summary}`);
});

client.on('cronError', (data) => {
  console.error(`Cron job "${data.jobName}" failed: ${data.error}`);
});
```
```