What Is the ClawDense Compression Protocol and How Does It Achieve 60% Token Reduction?

ClawDense is a dictionary-based compression protocol that rewrites verbose CT/1 header parameters into single-character aliases, reducing token usage by approximately 60% while preserving full message integrity.

The ClawDense compression protocol serves as the token-efficient wire format for internal agent-to-kernel communication within the ClosedClaw repository. By compressing planning message headers before they enter the LLM context window, agents can fit roughly three times more tool calls into the same context limit, dramatically increasing operational throughput.

How ClawDense Compression Works

At its core, ClawDense operates as a static dictionary substitution layer that targets the repetitive parameter names common in CT/1 (ClawTalk 1.0) headers. The protocol uses versioned dictionaries to ensure forward compatibility while minimizing wire size.

Dictionary Definition and Versioning

The compression system relies on COMPRESSION_DICTIONARY_V1, defined in src/agents/clawtalk/compression.ts at lines 10-20, which maps verbose CT/1 keys to single-character symbols:

• filter → f
• limit → l
• since → s
• offset → o

This static map is paired with REVERSE_V1 (lines 22-30), a reverse lookup table used during decompression to restore the original keys. The versioned approach allows the kernel to evolve the dictionary without breaking existing agents.

The Compression Pipeline

The compressWire function (lines 59-86 in src/agents/clawtalk/compression.ts) executes the compression through four discrete steps:

1. Header Isolation – Splits the message at the --- delimiter to separate metadata from payload.
2. Key Replacement – Invokes replaceKeys (lines 36-44), which uses boundary-aware regex to substitute full parameter names with their aliases.
3. Version Tagging – Returns a version field (currently 1) only if substitutions occurred; otherwise returns the original wire unchanged.
4. Reassembly – Concatenates the compressed header back with the payload.

The decompressWire function (lines 92-112) performs the inverse operation using the version number to select the correct reverse map, ensuring lossless restoration of the original header.

Token Reduction Performance

Empirical benchmarks documented in docs/experiments/proposals/clawdense-notation.md demonstrate consistent 60% token savings across realistic workloads:

Concrete Examples:

• File search operations drop from 12 tokens to 6 tokens (50% reduction)
• Authorization checks compress from 15 tokens to 5 tokens (67% reduction)
• Average across workloads falls from 12.4 tokens per operation to 4.8 tokens, achieving a 61% token reduction

These savings compound significantly in multi-step planning scenarios where agents exchange dozens of CT/1 messages within a single context window.

Implementing ClawDense in Your Agent System

The ClosedClaw implementation exposes two primary functions for wire format transformation:

Compressing Outbound Messages

Use compressWire to minimize tokens before sending to the kernel:

import { compressWire } from "./src/agents/clawtalk/compression";

const wire = `
filter=10 limit=20 since=2026-01-01
--- 
payload goes here
`;

const { wire: compressed, version } = compressWire(wire);
// compressed: "f=10 l=20 s=2026-01-01---\npayload goes here"
console.log(version); // 1 (indicates dictionary V1 was applied)

The function trims whitespace, isolates the header section, applies the dictionary substitution, and reattaches the payload only if changes occurred.

Decompressing Inbound Messages

The kernel restores original parameter names using decompressWire:

import { decompressWire } from "./src/agents/clawtalk/compression";

const compressed = "f=10 l=20 s=2026-01-01\n---\npayload goes here";
const original = decompressWire(compressed, 1);
// original: "filter=10 limit=20 since=2026-01-01\n---\npayload goes here"

Passing the correct version number ensures the reverse mapping from REVERSE_V1 accurately reconstructs the full CT/1 header expected by downstream processors.

Summary

• ClawDense reduces LLM token usage by approximately 60% through dictionary-based compression of CT/1 headers.
• The protocol uses versioned dictionaries (COMPRESSION_DICTIONARY_V1) to map verbose keys to single-character aliases while maintaining forward compatibility.
• Lossless compression is achieved via compressWire and decompressWire functions in src/agents/clawtalk/compression.ts, with negligible runtime overhead.
• Empirical results show 12.4 → 4.8 tokens per operation on average, enabling 3× more tool calls within the same context window.

Frequently Asked Questions

How does ClawDense differ from general-purpose compression like gzip?

ClawDense is semantic compression, not bitwise compression. While gzip reduces byte size, ClawDense specifically targets token count by shortening the parameter names that LLM tokenizers split into discrete units. According to the ClosedClaw source code, substituting filter (1 token) with f (1 token) doesn't reduce bytes significantly, but when multiplied across dozens of parameters in a header, the savings compound. The protocol also remains human-readable, unlike gzip binary output.

What happens if an agent uses a different dictionary version than the kernel?

Version mismatch triggers graceful degradation. The compressWire function explicitly returns the dictionary version used (e.g., version: 1). If the kernel receives a version it doesn't recognize, it can reject the message with a specific error rather than misinterpreting the compressed keys. This deterministic versioning allows the compression.ts implementation to support multiple dictionary versions simultaneously during rolling upgrades.

Is ClawDense compression lossless or does it discard metadata?

ClawDense is strictly lossless. The replaceKeys function uses word boundary regex patterns to ensure it only matches complete parameter names, preventing partial substitutions that could corrupt values. The decompressWire function restores the exact original string, verified by unit tests in src/agents/clawtalk/compression.test.ts that confirm perfect round-trip fidelity for all supported CT/1 header formats.

Can I implement ClawDense in a non-TypeScript agent?

Yes, the protocol is language-agnostic. The COMPRESSION_DICTIONARY_V1 structure is a simple static map that can be ported to any language. The critical requirements are: (1) boundary-aware regex substitution to isolate keys from values, (2) the --- delimiter to separate headers from payloads, and (3) version negotiation between compression and decompression endpoints. The docs/experiments/proposals/clawdense-notation.md document provides the canonical reference independent of the TypeScript implementation.

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