> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caveman.so/llms.txt
> Use this file to discover all available pages before exploring further.

# TOON and Pixel Context Encodings for Caveman

> Learn how Caveman's TOON and pixel context encodings compress structured data and dense text into model-readable formats. Includes CLI commands, selection rules, and model compatibility guidance.

Caveman offers two optional context encodings that reshape what a model sees: TOON (Token-Oriented Object Notation) compresses structured data into compact text, and pixel converts dense text into PNG images for vision-capable models. Neither is byte-safe, so use them only when their input shape and the receiving model are suitable.

## TOON

TOON re-encodes structured data into a compact text form. It is strongest on uniform tabular JSON, such as an array whose objects share field names.

For example, this JSON array:

```json theme={"dark"}
[
  {"name":"Ada","role":"engineer"},
  {"name":"Lin","role":"designer"}
]
```

TOON can move repeated keys into a shared header and keep row values compact. Exact syntax is defined by implementation and its test fixtures; callers should use the encoder and decoder instead of constructing TOON by hand.

### Selection rules

TOON runs only when explicitly requested or enabled through a feature gate. It is not selected by Engine's general `Detect` function. Result must be smaller than original representation.

TOON is not used for tool-call arguments. Changing tool arguments can alter program behavior even when data appears structurally similar.

### CLI

```bash theme={"dark"}
caveman tools toon encode < data.json
caveman tools toon decode < data.toon
```

Decoder rejects malformed input rather than inventing missing structure.

### Suitable inputs

Use TOON for:

* Uniform arrays of objects
* Repeated field names
* Scalar cell values
* Data consumed as context rather than executable arguments

Avoid TOON for irregular nested objects, already compact data, inputs where key order or byte representation matters, and tool-call arguments.

## Pixel context

Pixel converts text into a PNG image that a vision-capable model can read. It can reduce text-token input for dense source material, but introduces optical recognition and visual-layout risk.

Enable for one session:

```bash theme={"dark"}
caveman wrap --pixel <agent>
```

Pixel requires explicit model allowlisting:

```json theme={"dark"}
{
  "think": {
    "pixel": {
      "models": ["model-name"],
      "density": "balanced"
    }
  }
}
```

Supported density values are `conservative`, `balanced`, and `max`. Higher density places more text into an image and can make small characters harder for a model to read.

### Model compatibility

Vision capability alone is insufficient because image dimensions, detail settings, provider token accounting, and text-reading quality differ. Caveman does not infer support from model name.

### Recovery

Original text is stored through CCR (Context Compression and Recovery) before pixel output is emitted. If recovery storage fails, original text remains in request. Image context should include a clear recovery reference so tools can fetch exact source when character-level detail matters.

## Evidence boundary

Smaller local representation does not establish lower provider cost because providers count image and structured-text inputs differently. A valid claim needs provider usage or documented benchmark for exact model; quality equivalence also needs task evaluation beyond recovery availability.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.