openclaw-tally

Tokens tell you how much you paid. Tasks tell you what you got. Tally tracks every OpenClaw task from start to finish — cost, complexity, and efficiency score.

Security Scan

openclaw-tally's requested capabilities, files, and runtime instructions are consistent with a local task-level analytics skill that stores metadata in a local SQLite DB and does not request unrelated credentials or network access.

Purpose & Capability

The code, package.json, skill.json, and SKILL.md all implement a local task-detection, ledger, and analytics system. Required binaries (node/npm) and the native sqlite dependency (better-sqlite3) are expected for this purpose. No unexpected credentials, network access, or unrelated binaries are requested.

Instruction Scope

SKILL.md says the skill registers a message-post hook and processes every message's text but stores only metadata. The code contains task detector, ledger, and analytics logic and does not persist raw message bodies. There is a small surface to note: the DB includes intent_summary and outcome_summary fields (strings) — the current detector returns empty summaries, but future changes could populate those fields with snippets. Confirm intent_summary/outcome_summary behavior if you want guarantees that no message text is ever persisted.

Install Mechanism

No install spec in registry, but the package contains package.json and package-lock.json; installation uses standard npm which will fetch dependencies from npmjs.org (including better-sqlite3). This is expected for a Node skill. The SKILL.md explicitly warns about the native build step. No downloads from untrusted URLs or extract-from-arbitrary-host steps were found.

Credentials

The skill requires no environment variables or external credentials. File system access is limited to ~/.openclaw/tally/ (and tests allow /tmp). package.json/repo metadata points to a GitHub repo — not a secret or unrelated service. Overall requested environment access is proportional to the stated purpose.

Persistence & Privilege

The skill is not always-on and does not request elevated privileges. skill.json declares filesystem write/read only under ~/.openclaw/tally/, network: none, and exec: false. The code enforces a hardcoded default DB path within the user homedir and validates custom paths to /tmp; no modifications to other skills or system configs were observed.

Assessment

This skill appears coherent and local-only: it needs node/npm and will run npm install (including a native build for better-sqlite3) and write a SQLite DB at ~/.openclaw/tally/tally.db. Before installing: 1) be prepared to run native builds (Node >=18) or install prebuilt binaries for better-sqlite3 on your platform; 2) if you require absolute assurance that no message content is stored, audit any code paths that might populate intent_summary/outcome_summary (currently detector returns empty summaries); 3) consider running it in a test user account or VM to verify behavior and DB location; and 4) review the GitHub repo (package.json points to https://github.com/JonathanJing/openclaw-tally) if you want source provenance. Minor notes: src/index.js exports VERSION '0.1.0' while package/skill metadata are 0.3.1 (version mismatch only).

Reframes AI usage from token-counting to task-completion economics. Instead of "how many tokens?", answer "how much to get X done, and was it worth it?"

🛠️ Installation

1. Ask OpenClaw (Recommended)

Tell OpenClaw: "Install the openclaw-tally skill." The agent will handle the installation and configuration automatically.

2. Manual Installation (CLI)

If you prefer the terminal, run:

clawhub install openclaw-tally

Security & Privacy Declaration

• Hook: This skill registers a message-post hook and processes every message.
• Local only: All processing is purely local. No data is sent to any external server.
• Message content: The task detector reads message text to identify task boundaries (start/complete/fail signals) using regex pattern matching. No message text is stored — only metadata (token count, model, session_id, complexity score) is persisted to the database.
• Sandboxed storage: SQLite database defaults to ~/.openclaw/tally/tally.db. A custom path can be provided for testing.
• Native dependency: Requires better-sqlite3 (native Node.js addon). Installation runs npm install which triggers a native build step.
• Permissions: No network access. No exec permissions. Filesystem limited to ~/.openclaw/tally/.

What It Does

• Detects tasks automatically from message streams (Layer 1: Task Detector)
• Attributes costs across sessions, sub-agents, and cron triggers (Layer 2: Task Ledger)
• Computes TES (Task Efficiency Score) per task, model, and cron (Layer 3: Analytics Engine)

Commands

• /tasks list — Show recent tasks with status, cost, and TES
• /tasks stats — Summary statistics for a time period
• /tasks this-week — This week's task summary
• /tasks show <task_id> — Show task detail
• /tasks report --dimension model — Model efficiency report
• /tasks cron-health — Cron efficiency and health check

Complexity Levels

• L1 (Reflex): Single-turn, text-only, no tools
• L2 (Routine): Multi-turn or 1–3 tool calls
• L3 (Mission): Multiple tools + file I/O + external APIs
• L4 (Campaign): Sub-agents + cron + cross-session

TES (Task Efficiency Score)

TES = quality_score / (normalized_cost × complexity_weight)

• > 2.0 🟢 Excellent
• 1.0–2.0 🟡 Good
• 0.5–1.0 🟠 Below average
• < 0.5 🔴 Poor
• 0.0 ⚫ Failed

Usage

When the skill is installed, it automatically hooks into message-post. Use the /tasks commands above to query analytics. All data is stored locally in ~/.openclaw/tally/tally.db.

See PRD.md for the full product specification.