What Telemetry Data Does the ClosedClaw Agent Collect and How Is It Stored?

The ClosedClaw agent collects execution metrics including run counts, success rates, latency averages, and error logs, storing this telemetry data directly inside each .claws script file within a dedicated Telemetry block (Block 5) using JSON format.

ClosedClaw is an innovative agent framework that embeds performance telemetry directly into its source files. Understanding what telemetry data the agent collects and how this information is stored helps developers audit script performance and optimize automation workflows without external database dependencies.

Types of Telemetry Data Collected by the Agent

The ClawsTelemetry interface in src/agents/clawtalk/claws-parser.ts (lines 61-70) defines a strict schema for runtime metrics. Each time a .claws script executes, the agent captures:

• executionCount — Integer tracking total script invocations
• successRate — Exponential moving average of successful runs (0.0 to 1.0 scale)
• avgLatencyMs — Exponential moving average of execution latency in milliseconds
• errors — Array of recent error objects, each containing code, msg, and Unix timestamp fields
• lastRefactor — Optional ISO timestamp indicating when the shadow-factory last auto-refactored the script
• refactorReason — Optional string explaining why automatic refactoring occurred
• raw — The raw JSON text as it appears in the file, used for round-tripping during updates

These fields provide a complete performance profile while remaining human-readable within the source file.

Where Telemetry Data Is Stored: The .claws File Format

Unlike traditional agents that persist metrics to external databases or time-series stores, ClosedClaw embeds telemetry data directly inside the same .claws source file using Block 5 (the Telemetry block).

In-File Storage Format

The telemetry block appears as a JSON snippet between YAML-style --- delimiters, preceded by a comment header /* TELEMETRY */. According to the file-format header in claws-parser.ts (lines 7-14), this block maintains version control alongside the script logic.

---
/* TELEMETRY */
{
  "execution_count": 42,
  "success_rate": 0.98,
  "avg_latency_ms": 123,
  "errors": [
    { "code": "TIMEOUT", "msg": "API did not respond", "timestamp": 1708854123 }
  ],
  "last_refactor": "2024-04-12T07:34:21Z",
  "refactor_reason": "Low success rate"
}

Runtime Update Mechanism

After each execution, the updateTelemetry helper function (lines 30-45 in claws-parser.ts) atomically rewrites this block. The core update logic (lines 43-60) performs four operations:

1. Reads the existing telemetry JSON from the file
2. Increments executionCount and adjusts exponential moving averages for successRate and avgLatencyMs
3. Appends new error objects with Unix timestamps when failures occur
4. Serializes the updated JSON and writes it back to the same .claws file, preserving the /* TELEMETRY */ header and --- delimiters

How Telemetry Data Drives Optimization

The shadow-factory agent consumes stored metrics to determine when automatic refactoring is warranted. In src/agents/clawtalk/shadow-factory.ts (lines 5-17), the OptimizationSignal type transforms raw telemetry into optimization decisions:

• successRate maps directly to OptimizationSignal.successRate
• avgLatencyMs feeds into OptimizationSignal.avgLatencyMs
• Custom heuristics combine these values to populate rewriteRecommended when performance thresholds are breached

When telemetry indicates degraded performance—such as success rates dropping below 0.7 or latency exceeding 500ms—the shadow-factory triggers an automatic rewrite to improve script efficiency.

Optional External Diagnostics

While primary storage remains in-file, the diagnostics-otel extension can forward aggregated telemetry data to external OpenTelemetry collectors. This optional pipeline, implemented in extensions/diagnostics-otel/src/service.ts, operates separately from the per-script telemetry embedded in .claws files and requires explicit configuration to enable.

Code Examples

Reading Telemetry Data from a .claws File

import { loadClawsFile } from "./agents/clawtalk/claws-parser.js";

const { telemetry } = await loadClawsFile("./my-tool.claws");
if (telemetry?.successRate < 0.6) {
  console.warn("Low success rate – consider auto-refactor");
}

Updating Telemetry After Execution

import { updateTelemetry } from "./agents/clawtalk/claws-parser.js";

await updateTelemetry("./my-tool.claws", {
  success: true,
  latencyMs: 182,
  // error: { code: "EVAL", msg: "Division by zero" } // optional
});

Converting Telemetry to Optimization Signals

import type { OptimizationSignal } from "./agents/clawtalk/shadow-factory.js";

function createSignal(telemetry: ClawsTelemetry | null): OptimizationSignal {
  const rate = telemetry?.successRate ?? 1.0;
  const latency = telemetry?.avgLatencyMs ?? 0;
  const rewrite = rate < 0.7 || latency > 500;

  return {
    successRate: rate,
    avgLatencyMs: latency,
    rewriteRecommended: rewrite,
    reason: rewrite ? "Performance/Safety threshold exceeded" : "OK",
    correctionRate: 0 // computed elsewhere
  };
}

Summary

• ClosedClaw collects execution counts, success rates, latency metrics, and error logs defined by the ClawsTelemetry interface in claws-parser.ts
• All telemetry persists inside the .claws source file within Block 5 (Telemetry block) as JSON between --- delimiters
• The updateTelemetry function handles atomic read-modify-write cycles after each script execution
• The shadow-factory consumes these metrics via the OptimizationSignal type to trigger automatic refactors when thresholds are exceeded
• Optional OpenTelemetry export is available through the diagnostics extension without affecting the primary in-file storage model

Frequently Asked Questions

Does ClosedClaw store telemetry data in a separate database?

No. According to the source code in src/agents/clawtalk/claws-parser.ts, ClosedClaw stores all telemetry data directly inside the .claws script file within a dedicated Telemetry block (Block 5). This design keeps performance metrics version-controlled alongside the code itself, eliminating external database dependencies for core functionality while ensuring metrics travel with the file through Git commits.

What specific telemetry data fields does the agent track?

The agent tracks six primary fields defined in the ClawsTelemetry interface: executionCount (total runs), successRate (exponential moving average of success), avgLatencyMs (exponential moving average of latency), errors (array of recent failures with timestamps), and optional refactor metadata (lastRefactor, refactorReason). The raw field preserves the literal JSON text for round-trip fidelity during updates.

How does the shadow-factory use telemetry data to optimize scripts?

The shadow-factory reads telemetry through the OptimizationSignal type defined in shadow-factory.ts (lines 5-17). It evaluates successRate and avgLatencyMs against internal thresholds to set the rewriteRecommended boolean. When success rates drop below 0.7 or latency exceeds 500ms, the factory triggers automatic refactoring to improve script performance and reliability.

Can I export ClosedClaw telemetry to external monitoring systems?

Yes. While primary storage remains embedded in .claws files, the optional diagnostics-otel extension in extensions/diagnostics-otel/src/service.ts can forward aggregated telemetry data to OpenTelemetry collectors. This operates as a separate pipeline from the embedded telemetry block and requires explicit configuration to enable external export without altering the in-file storage format.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}