Clawtime

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

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:

# 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

Task Icons

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

Troubleshooting

See INSTALL.md → Troubleshooting for common issues.