Overview

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 | TOON Spec v1.3

When to Use TOON

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

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

When NOT to Use TOON

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

{
  "user": {
    "profile": {
      "settings": { "theme": "dark" }
    }
  },
  "items": [1, { "a": 1 }, "x"]
}

This mixed structure should use JSON, not TOON.

Syntax Guidelines

Basic Rules

2-space indentation - Standard for nested structures
Tabular format - For uniform object arrays (use when possible)
List format - For mixed/non-uniform data
Length markers - Array headers show count: items[2]
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

Using TOON in Claude Code

For Input (Sending Data to Claude)

Wrap in fenced code block - Use ```toon label for clarity
Structure is self-documenting - The format syntax is usually sufficient
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:

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

## Advanced Options

### 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


## Decision Tree

1. **Is the data uniform arrays of objects with same fields?**
   - ✅ YES → Use TOON tabular format
   - ❌ NO → Continue

2. **Is the data mixed types or varying structures?**
   - ✅ YES → Use JSON
   - ❌ NO → Continue

3. **Is token efficiency important?**
   - ✅ YES → Use TOON list format for simple arrays
   - ❌ NO → Use JSON

4. **Is this for API or storage?**
   - ✅ YES → Use JSON
   - ❌ NO → Consider TOON if uniform

## Implementation Notes

- **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

Memory Protocol (MANDATORY)

Before starting:

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.

toon-format

Toon Format Skill

TOON Format Rules for Claude Code