Tidbyt Status - Scout Display

Complete integration for displaying Scout's status on Tidbyt 64x32 LED displays.

Components

• Status API Server (scripts/status_server.py) - Exposes Scout's status as JSON
• Tidbyt App (scout_status.star) - Starlark app for rendering on Tidbyt

Quick Start

1. Start the Status API Server

cd ~/.openclaw/workspace/skills/tidbyt-status
python3 scripts/status_server.py

API available at http://localhost:8765/status

2. Install Pixlet (Tidbyt Development Tool)

macOS:

brew install tidbyt/tidbyt/pixlet

Linux: Download from GitHub releases

3. Test Locally

Update the IP address in scout_status.star (line 10):

DEFAULT_API_URL = "http://YOUR-LOCAL-IP:8765/status"

Render and serve:

pixlet serve scout_status.star

Visit http://localhost:8080 to preview.

4. Push to Your Tidbyt

First, login and get your device ID:

pixlet login
pixlet devices

Render the app:

pixlet render scout_status.star

Push to your Tidbyt:

pixlet push --installation-id Scout <YOUR-DEVICE-ID> scout_status.webp

Display Features

• Agent name + emoji (🦅) at top with animated face
• Status-specific faces:
• CHAT (green) - Casual chatting, eyes moving
• WORK (yellow) - Working hard, yellow face with purple focused eyes
• THINK (blue) - Thinking/processing, eyes blinking
• SLEEP (gray) - Idle/sleeping, closed eyes
• Task count - Number of concurrent sub-agent tasks
• Recent activity - Scrolling text showing current activity

API Response Format

The status server returns JSON:

{
  "agent": "Scout",
  "emoji": "🦅",
  "status": "chatting|working|thinking|sleeping",
  "timestamp": "2026-02-06T14:30:00",
  "active_tasks": 0,
  "last_activity": "2026-02-06T14:25:00",
  "recent_activity": "Chatting with user..."
}

Status Types:

• chatting - Main session active, no background tasks
• working - Sub-agent sessions running (processing tasks)
• thinking - Some activity but unclear
• sleeping - No activity for >1 hour

Configuration

Custom API Port

PORT=9000 python3 scripts/status_server.py

Custom API URL in Tidbyt App

When pushing to Tidbyt, configure via the mobile app:

• Tap the Scout installation
• Settings → API URL
• Enter your full URL

Running the API Server as a Service

systemd (Linux)

Create /etc/systemd/system/scout-status.service:

[Unit]
Description=Scout Status API for Tidbyt
After=network.target

[Service]
Type=simple
User=<username>
WorkingDirectory=/home/<username>/.openclaw/workspace/skills/tidbyt-status
ExecStart=/usr/bin/python3 scripts/status_server.py
Restart=always
Environment="PORT=8765"

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable scout-status
sudo systemctl start scout-status

Manual Background

nohup python3 scripts/status_server.py > /tmp/scout-status.log 2>&1 &

Network Configuration

For Tidbyt to access the API:

• Find your local IP:

hostname -I | awk '{print $1}'

• Update firewall (if needed):

sudo ufw allow 8765/tcp

• Test from another machine:

curl http://YOUR-IP:8765/status

Status Detection Logic

The server monitors ~/.openclaw/agents/main/sessions/*.jsonl:

• Active: Any session modified within last 5 minutes
• Idle: No recent activity
• Active tasks: Count of sub-agent sessions (excludes main session)
• Recent activity: Shows time since last activity when idle

Customization

Change the Emoji

Edit scripts/status_server.py line 16:

"emoji": "🦅",  # Change to any emoji

Adjust Activity Threshold

Edit scripts/status_server.py line 34 (default 300 seconds):

if age_seconds < 300:  # Change threshold here

Modify Display Colors

Edit scout_status.star lines 39-40:

status_color = "#00FF00" if status == "active" else "#888888"

Troubleshooting

API returns error:

• Check if OpenClaw is running
• Verify ~/.openclaw/agents/main/sessions/ exists

• Verify API URL is accessible from Tidbyt's network
• Check firewall settings
• Test with: curl http://YOUR-IP:8765/status

• Tidbyt apps refresh every ~30 seconds (see ttl_seconds in code)
• Check if the status API server is still running

Files

• SKILL.md - This documentation
• scripts/status_server.py - HTTP API server
• scout_status.star - Tidbyt Starlark app
• tidbyt-status.skill - Packaged skill file