toon-format

Token-Oriented Object Notation (TOON) is a compact, human-readable serialization format designed for LLM prompts. TOON provides approximately 50% token savings compared to JSON for uniform tabular data.

Reference: [TOON GitHub](https://github.com/toon-format/toon) | [TOON Spec v1.3](https://github.com/toon-format/toon/blob/main/SPEC.md)

Use TOON format when:

• Uniform arrays of objects - Same fields, primitive values only
• Large datasets with consistent structure
• Token efficiency is a priority (LLM input/output)
• Data is consumed by LLMs (not APIs or storage)

Example: Good TOON Use Case

```toon

users[3]{id,name,role,lastLogin}:

1,Alice,admin,2025-01-15T10:30:00Z

2,Bob,user,2025-01-14T15:22:00Z

3,Charlie,user,2025-01-13T09:45:00Z

```

Token savings: ~50% vs equivalent JSON

Do NOT use TOON when:

• Non-uniform data structures - Mixed types, varying fields
• Deeply nested objects - Complex hierarchies
• API responses - Standard JSON expected
• Storage formats - JSON compatibility required
• Objects with varying field sets - Each object has different keys

Example: JSON is Better Here

```json

{

"user": {

"profile": {

"settings": { "theme": "dark" }

}

},

"items": [1, { "a": 1 }, "x"]

}

```

This mixed structure should use JSON, not TOON.

Basic Rules

1. 2-space indentation - Standard for nested structures
2. Tabular format - For uniform object arrays (use when possible)
3. List format - For mixed/non-uniform data
4. Length markers - Array headers show count: items[2]
5. Field headers - Tabular arrays include field names: items[2]{id,qty,price}:

Format Examples

Object:

```

id: 1

name: Ada

```

Primitive array (inline):

```

tags[2]: reading,gaming

```

Tabular array (uniform objects):

```

items[2]{sku,qty,price}:

A1,2,9.99

B2,1,14.50

```

List format (non-uniform):

```

items[3]:

- 1

- a: 1

- x

```

For Input (Sending Data to Claude)

1. Wrap in fenced code block - Use `toon label for clarity
2. Structure is self-documenting - The format syntax is usually sufficient
3. Explicit length markers - Help Claude track structure, especially for large tables

Example:

````

Here's the user data:

```toon

users[3]{id,name,role}:

1,Alice,admin

2,Bob,user

3,Charlie,user

````

Please analyze the user roles.

```

For Output (Claude Generating TOON)

When requesting Claude to generate TOON:

1. Show the expected header format - users[N]{id,name,role}:
2. State the rules explicitly - 2-space indent, [N] matches row count
3. Provide a template - Show what format you expect

Example:

```

Return the filtered users in TOON format:

```toon

users[N]{id,name,role}:

[rows here]

```

Rules: 2-space indent, [N] matches actual row count, no trailing spaces.

```

Integration with Claude Projects and Artifacts

• Artifacts: TOON can be used in artifact specifications for structured data
• Subagents: Reference TOON rules when subagents process tabular data
• Hooks: Use TOON format in hook data if passing structured data between hooks

Custom Delimiters

For large uniform tables, consider tab delimiters:

```

items[2|]{sku|name|qty}:

A1|Widget|2

B2|Gadget|1

```

Tabs (\t) can provide additional token savings but may have display issues in some editors.

Length Marker

Optional hash prefix for clarity:

```

tags[#3]: reading,gaming,coding

items[#2]{sku,qty}: A1,2 B2,1

```

1. Is the data uniform arrays of objects with same fields?

- ✅ YES → Use TOON tabular format

- ❌ NO → Continue

1. Is the data mixed types or varying structures?

- ✅ YES → Use JSON

- ❌ NO → Continue

1. Is token efficiency important?

- ✅ YES → Use TOON list format for simple arrays

- ❌ NO → Use JSON

1. Is this for API or storage?

- ✅ YES → Use JSON

- ❌ NO → Consider TOON if uniform

• Show format, don't describe - The TOON structure is self-documenting
• Link to spec - Reference TOON spec for edge cases and full syntax
• Token counts vary - Benchmarks use GPT-style tokenizers; actual savings may differ
• Not a drop-in replacement - TOON is for LLM prompts, not general-purpose JSON replacement

```

Example usage:

```

User: "Review this code for toon format compliance"

Agent: [Analyzes code against guidelines and provides specific feedback]

```

Before starting:

```bash

cat .claude/context/memory/learnings.md

```

After completing: Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.