Feature Request: Add TOON (Token-Oriented Object Notation) Support

Feature Request: Add TOON (Token-Oriented Object Notation) Support

Summary

Add native support for TOON files as an alternative to JSON for plugin configurations, settings, and other structured data in Claude Code.

Motivation

TOON (Token-Oriented Object Notation) is a format specifically designed for LLM applications that reduces token usage by 30-60% compared to JSON while maintaining full compatibility with the JSON data model. Since Claude Code processes these configuration files during every session, adopting TOON would:

• Reduce API costs - Fewer tokens consumed when reading configurations
• Increase effective context windows - More room for actual code and prompts
• Maintain compatibility - Lossless conversion between JSON and TOON
• Improve readability - Cleaner syntax similar to YAML

Proof of Concept

We converted known_marketplaces.json to TOON format:

Results:

• Original JSON: 1061 bytes
• TOON format: 874 bytes
• Savings: 187 bytes (17.6% reduction)

Example Comparison

JSON:

{
  "claude-code-marketplace": {
    "source": {
      "source": "git",
      "url": "https://github.com/DustyWalker/claude-code-marketplace.git"
    },
    "installLocation": "/home/nick/.claude/plugins/marketplaces/claude-code-marketplace",
    "lastUpdated": "2025-11-08T00:02:14.483Z"
  }
}

TOON:

claude-code-marketplace:
  source:
    source: git
    url: "https://github.com/DustyWalker/claude-code-marketplace.git"
  installLocation: /home/nick/.claude/plugins/marketplaces/claude-code-marketplace
  lastUpdated: "2025-11-08T00:02:14.483Z"

Proposed Implementation

Phase 1: Dual Format Support

1. Add TOON parser to Claude Code (TypeScript implementation available at https://github.com/toon-format/toon)
2. Support both .json and .toon file extensions
3. Prioritize .toon if both exist, fall back to .json

Phase 2: Migration Tools

1. Add claude convert-to-toon command to convert existing configs
2. Update plugin templates to generate .toon files
3. Maintain backward compatibility with existing .json files

Affected Files

Files that would benefit most from TOON format:

Core Configuration:

• settings.json → settings.toon
• settings.local.json → settings.local.toon

Plugin System:

• plugin.json → plugin.toon
• hooks.json → hooks.toon
• known_marketplaces.json → known_marketplaces.toon
• installed_plugins.json → installed_plugins.toon
• .mcp.json → .mcp.toon

Marketplace Metadata:

• marketplace.json → marketplace.toon

Benefits

For Users

• Lower API costs due to reduced token consumption
• Cleaner, more readable configuration files
• Better use of context windows

For Plugin Developers

• More efficient plugin metadata
• Easier to maintain tabular data (arrays of objects)
• Modern format designed for AI-first workflows

For Anthropic

• Demonstrates leadership in AI-optimized data formats
• Potential competitive advantage in token efficiency
• Better utilization of Claude's context window

Technical Considerations

Compatibility

• TOON is lossless with respect to JSON data model
• Deterministic round-trips ensure no data loss
• Existing .json files continue working

Dependencies

• TOON TypeScript parser: https://www.npmjs.com/package/@toon-format/toon
• Specification: https://github.com/toon-format/spec
• Current version: 3.0 (2025-11-24)

Edge Cases

• Mixed environments: Some plugins use .json, others use .toon
• Migration period: Support both formats simultaneously
• Validation: TOON has strict mode for schema enforcement

Alternatives Considered

1. Stay with JSON - Familiar but token-inefficient
2. Use YAML - More readable but not optimized for LLMs
3. Custom format - Reinventing the wheel when TOON exists

Resources

• TOON GitHub: https://github.com/toon-format/toon
• TOON Specification: https://github.com/toon-format/spec
• TOON vs JSON Article: https://dev.to/akki907/toon-vs-json-the-new-format-designed-for-ai-nk5
• FreeCodeCamp Article: https://www.freecodecamp.org/news/what-is-toon-how-token-oriented-object-notation-could-change-how-ai-sees-data/

Open Questions

1. Should TOON be required, optional, or recommended for new plugins?
2. Should there be a migration timeline for existing plugins?
3. Would this be a breaking change requiring a major version bump?
4. Should the conversion be automatic during plugin installation?

Conclusion

TOON support would make Claude Code more efficient, reduce costs for users, and position Anthropic as a leader in adopting AI-optimized formats. The implementation is straightforward with existing libraries, and backward compatibility can be maintained throughout the transition.

---

Environment:

• Claude Code version: v2.0.70
• Test case: known_marketplaces.json (1061 bytes → 874 bytes)
• Savings demonstrated: 17.6%