Operate ClawTime — webchat widgets, task panel, and avatar creation.
---
name: clawtime
description: Operate ClawTime — webchat widgets, task panel, and avatar creation.
---
# ClawTime Skill
Operational reference for ClawTime — webchat interface for OpenClaw.
## Installation
For first-time setup (clone, configure, deploy), see **[INSTALL.md](./INSTALL.md)**.
---
## Operations
```bash
# Status & logs
systemctl --user status clawtime
journalctl --user -u clawtime -f
# Restart after config changes
systemctl --user restart clawtime
# Get current tunnel URL
journalctl --user -u clawtime-tunnel | grep trycloudflare | tail -1
```
## Widgets
ClawTime supports interactive widgets for richer user interactions. Include widget markup in your response and it renders as a UI component.
### Widget Syntax
```
[[WIDGET:{"widget":"TYPE","id":"UNIQUE_ID",...properties}]]
```
The markup is stripped from the displayed message and rendered as interactive UI.
### Available Widgets
#### Buttons
```
[[WIDGET:{"widget":"buttons","id":"choice1","label":"Pick a color:","options":["Red","Green","Blue"]}]]
```
- `label` — Prompt text above buttons
- `options` — Array of button labels
#### Confirm
```
[[WIDGET:{"widget":"confirm","id":"delete1","title":"Delete file?","message":"This cannot be undone."}]]
```
- `title` — Bold header text
- `message` — Description text
- Renders Cancel and Confirm buttons
#### Progress
```
[[WIDGET:{"widget":"progress","id":"upload1","label":"Uploading...","value":65}]]
```
- `label` — Description text
- `value` — Progress percentage (0-100)
#### Code
```
[[WIDGET:{"widget":"code","id":"snippet1","filename":"example.py","code":"print('Hello')","language":"python"}]]
```
- `filename` — File name in header
- `code` — The code content
- `language` — Syntax highlighting hint
- Includes a Copy button
#### Form
```
[[WIDGET:{"widget":"form","id":"survey1","label":"Quick Survey","fields":[{"name":"email","label":"Email","type":"text"},{"name":"rating","label":"Rating","type":"text"}]}]]
```
- `label` — Form title
- `fields` — Array of `{name, label, type}`
#### Datepicker
```
[[WIDGET:{"widget":"datepicker","id":"date1","label":"Select date:"}]]
```
- `label` — Prompt text
### Widget Responses
When user interacts with a widget:
```
[WIDGET_RESPONSE:{"id":"choice1","widget":"buttons","value":"Red","action":"submit"}]
```
### Best Practices
1. **Always use unique IDs** — Each widget needs a distinct `id`
2. **Keep options concise** — Button labels should be short
3. **Use widgets for structured input** — Better than "type 1, 2, or 3"
4. **Acknowledge responses** — Confirm what the user selected
## Task Panel
ClawTime includes a task panel for tracking work. **Use this as your canonical task list.**
### File Format
Tasks stored at `~/.clawtime/tasks.json` in markdown format:
```markdown
# Tasks
## Active
- 🟡 Task you're working on right now
## Blocked
- ⏳ Task waiting on someone else
## Backlog
- Task to do later
## Done
- ✅ Completed task
```
### Section Meanings
| Section | Meaning |
|---------|---------|
| **Active** | Currently working on — doing NOW |
| **Blocked** | Waiting for input/dependency |
| **Backlog** | Will work on later |
| **Done** | Completed (hidden in UI) |
### Task Icons
| Icon | Meaning |
|------|---------|
| 🟡 | Active/pending |
| ⏳ | Blocked/waiting |
| ✅ | Completed |
| `- [x]` | Also marks done |
## Avatar Creation
ClawTime uses **Three.js voxel avatars** — 3D characters built from simple shapes that animate based on state.
### Avatar Template
Create at `~/.clawtime/avatars/<name>.js`:
```javascript
/* AVATAR_META {"name":"MyAgent","emoji":"🤖","description":"Custom 3D avatar","color":"4f46e5"} */
(function() {
'use strict';
var scene, camera, renderer, character;
var head, leftEye, rightEye, mouth;
var clock = new THREE.Clock();
var currentState = 'idle';
var isInitialized = false;
// ─── Required: Initialize the 3D scene ───
window.initAvatarScene = function() {
if (isInitialized) return;
var container = document.getElementById('avatarCanvas');
if (!container) return;
scene = new THREE.Scene();
scene.background = new THREE.Color(0x0f1318);
var w = container.clientWidth, h = container.clientHeight;
camera = new THREE.PerspectiveCamera(40, w / h, 0.1, 100);
camera.position.set(0, 2, 8);
camera.lookAt(0, 0, 0);
renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(w, h);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
container.appendChild(renderer.domElement);
// Lighting
scene.add(new THREE.AmbientLight(0x606080, 1.5));
var light = new THREE.DirectionalLight(0xffffff, 2.0);
light.position.set(4, 10, 6);
scene.add(light);
// Build your character
character = new THREE.Group();
buildCharacter();
scene.add(character);
isInitialized = true;
animate();
};
function buildCharacter() {
var bodyMat = new THREE.MeshLambertMaterial({ color: 0x4f46e5 });
var body = new THREE.Mesh(new THREE.BoxGeometry(1.5, 2, 1), bodyMat);
body.position.y = 0;
character.add(body);
var headMat = new THREE.MeshLambertMaterial({ color: 0x4f46e5 });
head = new THREE.Mesh(new THREE.BoxGeometry(1.2, 1.2, 1), headMat);
head.position.y = 1.8;
character.add(head);
var eyeMat = new THREE.MeshBasicMaterial({ color: 0xffffff });
leftEye = new THREE.Mesh(new THREE.SphereGeometry(0.15), eyeMat);
leftEye.position.set(-0.25, 1.9, 0.5);
character.add(leftEye);
rightEye = new THREE.Mesh(new THREE.SphereGeometry(0.15), eyeMat);
rightEye.position.set(0.25, 1.9, 0.5);
character.add(rightEye);
var pupilMat = new THREE.MeshBasicMaterial({ color: 0x000000 });
mouth = new THREE.Mesh(new THREE.BoxGeometry(0.4, 0.1, 0.1), pupilMat);
mouth.position.set(0, 1.5, 0.5);
character.add(mouth);
}
function animate() {
requestAnimationFrame(animate);
var t = clock.getElapsedTime();
if (character) {
character.position.y = Math.sin(t * 2) * 0.05;
}
if (currentState === 'thinking') {
head.rotation.z = Math.sin(t * 3) * 0.1;
} else if (currentState === 'talking') {
mouth.scale.y = 1 + Math.sin(t * 15) * 0.5;
} else {
head.rotation.z = 0;
mouth.scale.y = 1;
}
renderer.render(scene, camera);
}
// ─── Required: Handle state changes ───
window.setAvatarState = function(state) {
currentState = state;
};
// ─── Required: Handle connection state ───
window.setConnectionState = function(state) {
// state: 'online', 'connecting', 'offline'
};
// ─── Required: Handle resize ───
window.adjustAvatarCamera = function() {
if (!renderer) return;
var container = document.getElementById('avatarCanvas');
var w = container.clientWidth, h = container.clientHeight;
camera.aspect = w / h;
camera.updateProjectionMatrix();
renderer.setSize(w, h);
};
})();
```
### Set as Default
Create/update `~/.clawtime/config.json`:
```json
{
"selectedAvatar": "<name>"
}
```
### Avatar States
Each state should be **visually distinct** with unique activities and indicators. Users should immediately recognize which state the avatar is in.
| State | Purpose | Design Ideas |
|-------|---------|--------------|
| `idle` | Default, waiting | Breathing, looking around, show-off poses, occasional blink |
| `thinking` | Processing request | Head tilt, eyes up, thought bubble (❓), tapping foot/wing |
| `talking` | Delivering response | Mouth animation, speech bubble, music notes (🎵), gesturing |
| `listening` | User is speaking | Leaning forward, BIG attentive eyes, ears/crest perked |
| `working` | Extended task | Laptop/tools visible, typing motion, focused squint |
| `happy` | Positive outcome | Bouncing, hearts (❤️), squinty smile eyes (^_^), wagging |
| `celebrating` | Major success | Jumping, spinning, confetti (⭐), maximum energy |
| `sleeping` | Inactive/idle timeout | Eyes closed, Z's floating (💤), curled up, slow breathing |
| `error` | Something went wrong | Shaking, exclamation (❗), ruffled, sweat drop, red tint |
| `reflecting` | Thoughtful moment | Light bulb (💡), gazing upward, calm pose, one hand raised |
### State Design Principles
1. **Visual indicators matter** — Add floating symbols (❓❤️💡❗💤⭐) that appear per-state
2. **Body language is key** — Each state needs distinct posture, movement speed, and energy level
3. **Eyes tell the story** — Big/small, open/closed, squinty/wide, pupil direction
4. **Movement rhythm varies** — Fast/bouncy for happy, slow/gentle for sleeping, shaky for error
5. **Props add clarity** — Laptop for working, floating Z's for sleeping, confetti for celebrating
6. **Think like a character animator** — What would a Pixar character do in this state?
### Creative Examples
**Parrot avatar:**
- `thinking` → Scratches head with foot, question mark floats
- `talking` → Beak opens/closes, music notes float up
- `error` → Feathers fly off, squawking pose, wings spread in alarm
- `celebrating` → Full party parrot spin, confetti everywhere
**Salamander avatar:**
- `thinking` → Flames pulse brighter, one foot taps
- `sleeping` → Flames become tiny embers, curled up
- `error` → Flames turn red, whole body shakes
- `reflecting` → Light bulb appears, one paw raised thoughtfully
### Avatar Design Tips
- Study `~/.clawtime/avatars/` for full-featured examples with all states
- Use voxel style (boxes, spheres) — matches ClawTime aesthetic
- Implement **all** states with distinct visuals — don't make states look similar
- Add connection status indicator (ring/glow on platform)
- Test on desktop and mobile
- Keep polygon count reasonable for mobile performance
- Hide/show indicator objects per-state (don't create/destroy every frame)
## Key Files
| Path | Purpose |
|------|---------|
| `~/.clawtime/.env` | Secrets & config |
| `~/.clawtime/config.json` | Avatar selection, preferences |
| `~/.clawtime/credentials.json` | Passkey data |
| `~/.clawtime/sessions.json` | Active sessions |
| `~/.clawtime/avatars/` | Custom avatars |
| `~/.clawtime/tasks.json` | Task list |
## Troubleshooting
See **[INSTALL.md → Troubleshooting](./INSTALL.md#troubleshooting)** for common issues.
don't have the plugin yet? install it then click "run inline in claude" again.