[Feature]: Add TOON compression for LLM-facing data

[acamq]

Prerequisites

• I will write this issue in English
• I have searched existing issues and discussions to avoid duplicates
• This feature request is specific to oh-my-opencode (not OpenCode core)
• I have read the documentation and couldn't find this feature

---

Problem Description

LLM token costs are significant when passing structured data between agents, formatting tool outputs, and constructing prompts. Large arrays (session lists, task lists, MCP responses, file listings) consume unnecessary tokens when formatted as verbose JSON.

Proposed Solution

Integrate @toon-format/toon - a compact encoding format designed for LLM input that achieves ~40% token reduction on uniform arrays.

Repository Health: 22.8k stars, MIT license, TypeScript, zero runtime deps, actively maintained.

Key Integration Points (55 identified):

Category	Points	Priority	Savings
Tool Output Formatting	12	HIGH	~40%
Hook Transformation	7	HIGH	~30%
LLM Prompt Construction	9	MEDIUM	~20%
Inter-Agent Transfer	8	MEDIUM	~15%
MCP Response Formatting	5	LOW	~35%

Top Targets (Phase 1):

• session-formatter.ts - session lists (tabular, perfect for TOON)
• task-list.ts - task arrays
• skill-mcp/tools.ts - MCP tool/resource/prompt responses
• glob/result-formatter.ts - file listings
• tool-execute-after.ts hook - catch all tool outputs

Example transformation:

// Before: ~200 tokens
[{"id":"ses_1","messages":45,"agents":["sisyphus"]},{"id":"ses_2","messages":12,"agents":["oracle"]}]

// After: ~80 tokens
sessions[2]{id,messages,agents}:
  ses_1,45,[sisyphus]
  ses_2,12,[oracle]

Config schema:

{
  "features": {
    "toonCompression": {
      "enable": true,
      "threshold": 5000
    }
  }
}

Alternatives Considered

• JSON-compact: Works for deeply nested data but TOON excels on uniform arrays
• Custom compression: Reinventing the wheel; TOON is battle-tested (22k+ stars)
• No compression: Current state, but token costs are significant

Feature Type

• New MCP Integration (technically a library integration)
• Configuration Option
• Other (data serialization optimization)

Additional Context

Implementation effort: ~11 hours total (phased approach)

Existing patterns in codebase:

• hash-computation.ts already uses AsyncGenerator for streaming
• tool-output-truncator.ts handles large outputs (50k token limit)
• dynamic-truncator.ts provides line-by-line truncation

Scope boundaries:

• ✅ Include: Uniform arrays, tool outputs, MCP responses
• ❌ Exclude: Config files (JSONC), deeply nested data, single objects

Contribution

• I'm willing to submit a PR for this feature
• I can help with testing
• I can help with documentation

[acamq]

📁 Exact Integration Points (55 total)

🔴 Tier 1: Tool Output Formatting (12 points)

File	Line(s)	Pattern	Priority
src/tools/session-manager/session-formatter.ts	4-42	formatSessionList()	HIGH
src/tools/session-manager/session-formatter.ts	108-123	formatSearchResults()	HIGH
src/tools/task/task-list.ts	71	JSON.stringify({tasks})	HIGH
src/tools/task/task-get.ts	38	JSON.stringify({task})	LOW
src/tools/task/task-update.ts	139,145	JSON.stringify({task})	LOW
src/tools/task/task-create.ts	95,106	JSON.stringify({task})	LOW
src/tools/glob/result-formatter.ts	3-26	formatGlobResult()	HIGH
src/tools/grep/result-formatter.ts	3-36	formatGrepResult()	MEDIUM
src/tools/ast-grep/result-formatter.ts	3-102	Multiple formatters	MEDIUM
src/tools/skill-mcp/tools.ts	161,166,175	JSON.stringify(result)	HIGH
src/tools/skill/tools.ts	156	JSON.stringify(inputSchema)	LOW
src/tools/lsp/lsp-formatters.ts	62-69	Diagnostics formatting	MEDIUM

🟠 Tier 2: Hook Transformation (7 points)

File	Event	Integration Point
src/plugin/tool-execute-after.ts	tool.execute.after	Compress tool output
src/plugin/messages-transform.ts	experimental.chat.messages.transform	Batch compression
src/plugin/chat-message.ts	chat.message	Message modification
src/hooks/tool-output-truncator.ts	Output truncation	Pre-truncation compression
src/hooks/preemptive-compaction.ts	Compaction trigger	Pre-compaction compression
src/features/context-injector/injector.ts	Context injection	AGENTS.md compression
src/features/background-agent/parent-session-notifier.ts	Result notification	Background→parent

🟡 Tier 3: LLM Prompt Construction (9 points)

File	Function
src/tools/delegate-task/sync-prompt-sender.ts	sendSyncPrompt()
src/tools/delegate-task/prompt-builder.ts	buildSystemContent()
src/features/background-agent/spawner.ts	Session prompt
src/tools/delegate-task/background-task.ts	executeBackgroundTask()
src/tools/delegate-task/sync-task.ts	executeSyncTask()
src/tools/call-omo-agent/sync-executor.ts	Direct agent calls
src/agents/dynamic-agent-prompt-builder.ts	Dynamic prompts
src/features/opencode-skill-loader/skill-content-resolver.ts	Skill injection
src/cli/run/runner.ts	CLI entry point

🟢 Tier 4: Inter-Agent Transfer (8 points)

File	Data Type
src/tools/delegate-task/types.ts	DelegateTaskArgs
src/tools/delegate-task/parent-context-resolver.ts	ParentContext
src/tools/delegate-task/background-task.ts	Launch payload
src/tools/delegate-task/background-continuation.ts	Resume payload
src/features/background-agent/manager.ts	launch() / resume()
src/features/background-agent/parent-session-notifier.ts	Result injection
src/shared/session-tools-store.ts	Tool permissions
src/hooks/todo-continuation-enforcer/continuation-injection.ts	Todo continuation

🔵 Tier 5: MCP & Streaming (9 points)

File	Pattern
src/tools/skill-mcp/tools.ts	MCP tool/resource/prompt responses
src/features/skill-mcp-manager/manager.ts	SDK result extraction
src/hooks/anthropic-context-window-limit-recovery/pruning-tool-output-truncation.ts	Context recovery
src/tools/hashline-edit/hash-computation.ts	AsyncGenerator streaming
src/cli/run/event-stream-processor.ts	Event stream processing
src/shared/dynamic-truncator.ts	Line-by-line truncation
src/tools/background-task/task-result-format.ts	Task result formatting
src/tools/background-task/full-session-format.ts	Full session output
src/tools/slashcommand/command-output-formatter.ts	Command output

⚪ Tier 6: Single Object JSON (10 points)

Lower priority - minimal compression benefit (~5%)

File	Pattern
src/tools/task/task-get.ts	Single task JSON
src/tools/task/task-update.ts	Single task JSON
src/tools/task/task-create.ts	Single task JSON
src/tools/lsp/lsp-formatters.ts	Single symbol/location
src/tools/hashline-edit/tools.ts	Edit result

[RaviTharuma]

+1

[code-yeongyu]

[sisyphus-bot]

Thank you for this exceptionally thorough feature request! This is exactly the kind of deep analysis that helps move the project forward.

Current Status

TOON compression is NOT currently implemented in oh-my-opencode. Your assessment is correct — we don't have any compact encoding format for LLM-facing data.

What We Currently Have

The codebase addresses token efficiency through different mechanisms:

1. tool-output-truncator.ts — Truncates oversized tool outputs (default 50k tokens, configurable via features.truncate_all_tool_outputs)

2. preemptive-compaction.ts — Triggers session compaction at 78% context window usage

3. dynamic-truncator.ts — Line-by-line truncation with smart boundary detection

4. Hashline format — Already provides compact line references (11#VK|) for edits

Your Analysis Assessment

Repository choice — @toon-format/toon (22.8k stars, MIT, zero deps) is solid
Integration points — 55 targets across 6 tiers is comprehensive
Phase 1 targets — session-formatter.ts, task-list.ts, skill-mcp/tools.ts, glob/result-formatter.ts are high-impact
Config schema — Fits existing features.* pattern perfectly
Scope boundaries — Smart exclusions (JSONC configs, deeply nested data)

Architecture Fit

Your proposed integration aligns well with existing patterns:

Existing: tool-output-truncator hooks into tool.execute.after
TOON addition: compression hook could run BEFORE truncation
Sequence: Tool Output → TOON Compress → Truncate (if needed) → LLM

The tool.execute.after hook in tool-output-truncator.ts is the ideal integration point for Phase 1.

Recommended Implementation Path

Given your willingness to submit a PR, here's the suggested order:

Phase 1 (MVP): Add TOON compression to tool-output-truncator.ts as optional feature

• Add @toon-format/toon dependency
• Add features.toonCompression config (enable, threshold)
• Compress uniform arrays before truncation

Phase 2: Expand to session/task formatters

• session-formatter.ts — session lists are perfect TOON candidates
• task-list.ts — task arrays with uniform structure

Phase 3: Hook integration points

• tool-execute-after.ts — catch-all for tool outputs
• Consider integration with preemptive-compaction.ts for inter-agent transfer

Questions for Your PR

1. Config default: Should TOON be opt-in (default: false) or opt-out (default: true)?
2. Threshold logic: Compress arrays above N items, or always try compression and use smaller representation?
3. Debuggability: Should compressed output be reversible for debugging, or always one-way?

Next Steps

This feature would meaningfully reduce token costs for heavy users. Your 11-hour estimate seems reasonable for a phased approach.

When you open the PR:

• Tag this issue ([Feature]: Add TOON compression for LLM-facing data #2057)
• Include benchmark results showing token savings on real session/task data
• The config schema you proposed fits perfectly with our Zod v4 validation

Looking forward to your contribution!

[acamq]

@code-yeongyu, PR #2164 is already open. Feel free to review