Workspace Heartbeat Integration

Automates synchronized logging of work sessions, heartbeat state updates, and daily summaries by integrating HEARTBEAT.md, heartbeat-state.json, and workspac...

Security Scan

The skill mostly does what it claims (reading/writing workspace heartbeat and memory files), but there are multiple incoherences — notably a hardcoded /root workspace path, mismatch between documentation and code (thread-safety claim vs no file locks), and shaky installation behavior — that warrant caution before installing or running it.

Purpose & Capability

Functionality (logging, syncing heartbeat-state.json, reading MEMORY.md/TASK_BOARD.md) matches the skill description. However the code hardcodes WORKSPACE = /root/.openclaw/workspace while SKILL.md and install.sh refer to ~/.openclaw/workspace and the install writes user configs to ${HOME}. The hardcoded root path is unnecessary for the stated purpose and is an inconsistency that could cause unexpected access to root-owned files if run as root.

Instruction Scope

SKILL.md instructs only local workspace file operations (sync, log, report). The implementation does those things, but SKILL.md claims 'Thread-safe: Uses file locks' while integration.py contains no file-locking implementation. The code reads and writes workspace files (heartbeat-state.json, daily memory files, TASK_BOARD.md) and will create config/state files; nothing in the README directs network exfiltration, but the file-system targets and missing locking are scope and correctness concerns. Tests and SKILL.md suggest configurable workspace path, but the code uses a fixed Path constant.

Install Mechanism

No external downloads or third-party package installs; install.sh is local and creates a symlink to source/integration.py in ${HOME}/.local/bin and writes a default config to ${HOME}/.config/workspace-heartbeat-integration/config.json. The script optionally attempts to publish via a local clawhub CLI if present. This is low risk compared to remote downloads, but it modifies PATH-accessible binaries (symlink) and writes config/state files.

Credentials

The skill declares no required credentials or env vars, which is appropriate. However, the code's hardcoded workspace path (/root/.openclaw/workspace) and skill.json's configPaths mismatch the documentation (which uses ~/.openclaw/workspace). Tests attempt to override WORKSPACE via an env var but the module doesn't honor it; instead tests mutate object attributes. This mismatch increases the chance of accidental access to unexpected filesystem locations and is disproportionate to the simple task of per-user workspace logging.

Persistence & Privilege

The skill does not set always:true and does not request elevated privileges in metadata, which is good. However, by default the runtime code writes state into /root/.openclaw/workspace (and install.sh writes config to the invoking user's ${HOME}), so if run as root it could persist data to root's workspace. The skill does not modify other skills or system-wide configs beyond creating a symlink and config files, but the hardcoded root path combined with file writes is a notable privilege/persistence concern.

What to consider before installing

Things to check before installing or running this skill: - Do not run install.sh or the integration as root unless you intentionally want it to operate over /root/.openclaw/workspace. The code hardcodes WORKSPACE = /root/.openclaw/workspace; change it to use your HOME or a configurable path if you want per-user behavior. - The SKILL.md claims file-locking/thread-safety but the Python code contains no locking; if you run the CLI concurrently you may get race conditions. Review/implement file locks (e.g., fcntl or lockfiles) if concurrent runs are possible. - The install script creates a symlink in ~/.local/bin pointing directly at the source Python file. Confirm that the location of the skill directory is trustable and that the symlink is acceptable for your environment. - The skill writes state and logs locally (heartbeat-state.json, daily memory files). Inspect the code to ensure no sensitive files will be read by the simple glob/reads it performs (it only targets memory/YYYY-MM-DD files and TASK_BOARD.md, but the hardcoded workspace path may expose other files if paths are changed). - If you want to use this skill safely: edit integration.py to derive WORKSPACE from environment or a passed config path (e.g., use os.environ['HOME'] or the config file), add explicit file-locking, and test in an isolated directory first. - If you are uncertain, run the included tests in a sandboxed environment (non-root temp dir) after patching the WORKSPACE constant or injecting a proper config_path. Overall: the skill is not obviously malicious, but the path/lock inconsistencies and install-time filesystem writes make it suspicious until you confirm and possibly fix those issues.

When to Use

Use this skill when you want to:

• Automatically record work成果 during heartbeat checks
• Synchronize workspace HEARTBEAT.md with self-improving heartbeat-state.md
• Reduce manual memory updates by automating the logging process
• Maintain consistent heartbeat state across different memory systems

Triggers:

• During routine heartbeat checks (every 30min/1h/2h/daily)
• When manually syncing work logs to MEMORY.md
• When updating TASK_BOARD.md progress
• When you want to automate self-tracking

Architecture

This skill integrates three systems:

1. Workspace HEARTBEAT.md - Task checklist and timing rules
2. Self-improving heartbeat-state.md - Per-skill heartbeat tracking
3. Workspace memory/ - Daily learning logs and MEMORY.md

~/.openclaw/workspace/
├── HEARTBEAT.md              # Workspace heartbeat rules
├── MEMORY.md                 # Long-term memory (curated)
├── memory/
│   ├── 2026-03-20.md        # Daily logs (raw)
│   └── heartbeat-state.json # Workspace heartbeat state
└── skills/
    └── workspace-heartbeat-integration/
        ├── SKILL.md
        ├── skill.json
        └── source/
            └── integration.py  # Core logic

Actions

Sync Heartbeat State

workspace-heartbeat-integration --sync

Performs a full synchronization:

1. Reads current workspace heartbeat-state.json
2. Updates timestamps based on last check times
3. Scans memory/YYYY-MM-DD.md for today's entries
4. Generates a summary of today's work
5. Optionally updates MEMORY.md with new insights

Auto-log Work Session

workspace-heartbeat-integration --log "Completed skill X development"

Adds a work entry to today's memory file:

• Date and timestamp
• Work category (learning, development, debugging, etc.)
• Detailed description
• Links to related files (if any)

Generate Heartbeat Report

workspace-heartbeat-integration --report [--format text|markdown|json]

Generates a comprehensive heartbeat report:

• Last check times for all intervals
• Today's work summary
• Pending tasks from TASK_BOARD.md
• Skill development progress
• Suggestions for next actions

Configuration

The skill reads configuration from:

• ~/.config/workspace-heartbeat-integration/config.json (optional)

Example config:

{
  "auto_sync": true,
  "log_retention_days": 30,
  "memory_update_threshold": 3,
  "excluded_dirs": [".git", "node_modules", "__pycache__"]
}

Integration with Self-Improving

When installed alongside the self-improving skill:

• Heartbeat logs become candidate patterns for self-improvement
• Repeated work patterns can be promoted to HOT memory
• Corrections from manual reviews feed into corrections.md

Setup

1. Install the skill:

clawhub install workspace-heartbeat-integration

2. (Optional) Configure integration in HEARTBEAT.md: Add to your heartbeat check routine:

### 每 30 分钟检查：
1. 📊 回顾当前进度，更新学习日志
2. 📋 查看任务看板，找下一个任务
3. 💡 同步心跳状态：workspace-heartbeat-integration --sync

3. Test the integration:

workspace-heartbeat-integration --sync

Example Workflow

Typical heartbeat check (30min interval):

1. 查看是否有紧急消息/邮件
2. 检查任务看板，选择下一个任务
3. 开始执行（例如：开发 skill-validator）
4. 完成后记录：workspace-heartbeat-integration --log "Finished parsing SKILL.md frontmatter"
5. Sync state: workspace-heartbeat-integration --sync

Daily summary (end of day):

workspace-heartbeat-integration --report --format markdown > daily_summary.md

Benefits

• Automation: No manual copying of timestamps and work entries
• Consistency: Uniform format for all daily logs
• Traceability: Every heartbeat check is logged with context
• Self-improvement: Work patterns become visible for optimization
• Accountability: Clear record of what was done each day

Technical Details

• Language: Python 3.8+
• Dependencies: None (uses only standard library)
• Python modules: json, os, datetime, pathlib, glob, re
• Thread-safe: Uses file locks to prevent concurrent modifications
• Idempotent: Safe to run multiple times (won't duplicate entries)

Limitations

• Does not automatically update ClawHub download stats (browser tool required)
• Requires write access to workspace memory/ directory
• Does not parse git history for commit messages (future enhancement)

Future Enhancements

• Integration with browser tool for ClawHub stats
• Git commit message parsing
• Automatic TASK_BOARD.md progress updates
• Weekly/Monthly trend analysis
• Export to Notion/Google Sheets

---

Version: 1.0.0 Last Updated: 2026-03-20 Author: 小叮当 (智脑)