to-toon

name	to-toon
description	Converts structured data (JSON, XML, YAML) to compact TOON format (Token-Oriented Object Notation) with 30-60% token savings. Use when compressing API responses, Figma MCP output, config files, or any structured data for token efficiency.

Universal TOON Converter

Purpose

Convert any structured data (JSON, XML, YAML) to compact TOON format for efficient LLM processing.

Quick Start

JSON → TOON (use official CLI)

# Direct conversion
npx @toon-format/cli input.json -o output.toon

# From stdin
echo '{"name": "Ada", "age": 30}' | npx @toon-format/cli

# With token savings stats
npx @toon-format/cli data.json --stats

TOON → JSON (decode)

npx @toon-format/cli data.toon -o output.json

XML → TOON (via JSON)

# Use included script for XML (e.g., Figma MCP output)
${CLAUDE_PLUGIN_ROOT}/scripts/xml-to-toon.sh input.xml

# Or manual: XML → JSON → TOON
cat input.xml | node ${CLAUDE_PLUGIN_ROOT}/scripts/xml-to-json.mjs | npx @toon-format/cli

CLI Reference

# Encode JSON to TOON (auto-detected by extension)
npx @toon-format/cli input.json -o output.toon

# Decode TOON to JSON (auto-detected)
npx @toon-format/cli data.toon -o output.json

# Pipe from stdin
cat data.json | npx @toon-format/cli
echo '{"name": "Ada"}' | npx @toon-format/cli

# Output to stdout
npx @toon-format/cli input.json

# Show token savings
npx @toon-format/cli data.json --stats

TOON Format Overview

TOON combines YAML-like syntax with CSV-style tabular arrays:

# Key-value pairs
name: Ada
age: 30

# Nested objects
address:
  city: Berlin
  zip: 10115

# Uniform arrays (most compact!)
users[3]{id,name,email}:
 1,Alice,[e-mail]
 2,Bob,[e-mail]
 3,Carol,[e-mail]

Token Savings Examples

Input Format	JSON Tokens	TOON Tokens	Savings
Simple object	50	30	40%
Array of 10 objects	500	200	60%
Nested config	1000	450	55%
Figma design context	10000	4000	60%

Common Use Cases

1. API Response Compression

curl -s https://api.example.com/users | npx @toon-format/cli --stats

2. Config File Compression

npx @toon-format/cli package.json --stats
npx @toon-format/cli tsconfig.json -o tsconfig.toon

3. Figma MCP Data

After get_design_context call:

${CLAUDE_PLUGIN_ROOT}/scripts/xml-to-toon.sh figma-output.xml --stats

4. Database Export

cat users.json | npx @toon-format/cli > users.toon

Included Scripts

xml-to-toon.sh

Full pipeline for XML data (Figma, HTML, SVG, etc.):

# Basic usage
${CLAUDE_PLUGIN_ROOT}/scripts/xml-to-toon.sh input.xml

# With output file
${CLAUDE_PLUGIN_ROOT}/scripts/xml-to-toon.sh input.xml -o output.toon

# Show stats
${CLAUDE_PLUGIN_ROOT}/scripts/xml-to-toon.sh input.xml --stats

# JSON only (skip TOON step)
${CLAUDE_PLUGIN_ROOT}/scripts/xml-to-toon.sh input.xml --json-only

xml-to-json.mjs

Convert XML to JSON (Node.js):

cat input.xml | node ${CLAUDE_PLUGIN_ROOT}/scripts/xml-to-json.mjs

Integration Tips

In Claude Code

When you receive structured data, consider:

1. JSON data → Use npx @toon-format/cli directly
2. XML data → Use xml-to-json.mjs then CLI
3. YAML data → Convert to JSON first, then CLI

Alias (optional)

# Add to ~/.zshrc or ~/.bashrc
alias toon='npx @toon-format/cli'
alias xml2toon='${CLAUDE_PLUGIN_ROOT}/scripts/xml-to-toon.sh'

When NOT to Use TOON

• Very small data (< 100 tokens) - overhead not worth it
• Deeply nested non-uniform structures - JSON may be clearer
• When exact JSON format is required downstream

@read reference.md for detailed format specification and edge cases.