ClawTime

Operate ClawTime — webchat widgets, task panel, and avatar creation.

Security Scan

The skill's instructions and resource references are consistent with its stated purpose (operating a webchat widget/task panel/avatar system); it requires no credentials or external installs, but it does expect read/write access to your home dir and ability to run user systemd/journalctl commands.

Purpose & Capability

Name/description (webchat widgets, task panel, avatars) matches the instructions: widget markup, task file format at ~/.clawtime/tasks.json, and avatar JS templates are all directly relevant. The skill does not request unrelated credentials or binaries.

Instruction Scope

Instructions tell the agent to run user-systemd commands (systemctl --user, journalctl --user -u clawtime[-tunnel]) and to read/write files under ~/.clawtime (tasks.json, avatars/*.js). That is coherent for operating ClawTime, but it grants the agent scope to read systemd logs and user files — make sure you expect the agent to have that level of system access. The SKILL.md refers to an INSTALL.md for setup, but INSTALL.md is not present in the package (missing dependency).

Install Mechanism

No install spec and no code files are included; this is instruction-only so nothing will be downloaded or written by an installer step. Lower install risk but runtime instructions assume existing services and files.

Credentials

No environment variables, credentials, or external service tokens are requested. The only resources accessed are user-level systemd logs and files under the user's home directory, which align with the skill's operational purpose.

Persistence & Privilege

always is false and the skill does not request persistent platform privileges. It also does not declare any behavior that would modify other skills or global agent settings.

Assessment

This skill appears to be a coherent operator's guide for ClawTime. Before installing or enabling it, consider: (1) it expects the agent to be able to read/write files in ~/.clawtime and run user-systemd commands (systemctl --user, journalctl) — only enable if you trust the agent with that access; (2) INSTALL.md referenced by SKILL.md is missing from this package, so setup instructions are incomplete here — obtain and review installation docs before following them; (3) avatar templates are JavaScript files that may execute in a web context; review any avatar JS you create or load to avoid running untrusted code in your browser context; (4) back up ~/.clawtime/tasks.json before letting the skill modify it; and (5) if you want tighter control, run the service and file operations yourself rather than granting the agent autonomous system-level access.

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

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

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 for common issues.