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

> Discover what telemetry data the ClosedClaw agent collects, including run counts, latency, and error logs. Learn how this data is stored within *.claws* script files in JSON format.

- Repository: [aSafeLobotomy/closedclaw](https://github.com/asafelobotomy/closedclaw)
- Tags: telemetry-data-collection
- Published: 2026-02-25

---

**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`](https://github.com/asafelobotomy/closedclaw/blob/main/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`](https://github.com/asafelobotomy/closedclaw/blob/main/claws-parser.ts) (lines 7-14), this block maintains version control alongside the script logic.

```yaml
---
/* 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`](https://github.com/asafelobotomy/closedclaw/blob/main/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`](https://github.com/asafelobotomy/closedclaw/blob/main/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`](https://github.com/asafelobotomy/closedclaw/blob/main/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

```typescript
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

```typescript
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

```typescript
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`](https://github.com/asafelobotomy/closedclaw/blob/main/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`](https://github.com/asafelobotomy/closedclaw/blob/main/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`](https://github.com/asafelobotomy/closedclaw/blob/main/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`](https://github.com/asafelobotomy/closedclaw/blob/main/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.