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.

Operations

# 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

Always use unique IDs — Each widget needs a distinct id
Keep options concise — Button labels should be short
Use widgets for structured input — Better than "type 1, 2, or 3"
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:

# 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:

/* 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:

{
  "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

Visual indicators matter — Add floating symbols (❓❤️💡❗💤⭐) that appear per-state
Body language is key — Each state needs distinct posture, movement speed, and energy level
Eyes tell the story — Big/small, open/closed, squinty/wide, pupil direction
Movement rhythm varies — Fast/bouncy for happy, slow/gentle for sleeping, shaky for error
Props add clarity — Laptop for working, floating Z's for sleeping, confetti for celebrating
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 for common issues.

ClawTime

Description