agent-desktop/docs/brainstorms/2026-03-01-electron-tree-compaction-brainstorm.md

Electron Tree Compaction Brainstorm

Date: 2026-03-01 Status: Decided Trigger: Electron depth-skip fix (commit a19c1b5) made Slack snapshots work but raised concern about context bloat for AI agents.

Problem Statement

After enabling Electron/web app support via depth-skip for non-semantic AXGroup wrappers, Slack snapshots with -i return 268 nodes / ~6,700 tokens — 4x the cost of Finder's 96 nodes / ~1,625 tokens. 40% of Slack's nodes are structural wrappers carrying no useful info.

The question: should we build a smart architecture (e.g., a standalone Electron-to-AX bridge) to reduce this, or is there a simpler solution?

Data

Mode	Nodes	Refs	Tokens	Notes
Slack -i (current)	268	162	~6,700	40% structural noise
Slack -i + compact	204	162	~5,475	18% savings
Slack full (no -i)	528	162	~12,000	69% structural noise
Finder -i	96	73	~1,625	24% structural (baseline)

Snapshot speed: Slack ~220ms, Finder ~260ms. Speed is not an issue.

What We're Building

Implement --compact flag (already wired in CLI as a no-op) to collapse single-child non-interactive pass-through nodes during tree serialization.

Collapse rule: If a node has no ref_id, no name, no value, and exactly one child — skip it and hoist the child. If it has a name but the child doesn't, promote the name to the child and skip.

This is a tree serialization optimization, not an Electron-specific feature. Benefits all apps.

Why This Approach

1. The flag already exists — --compact is wired through CLI, TreeOptions, and the snapshot pipeline. Just needs implementation.
2. 18% token savings for free — 64 nodes removed from Slack with zero information loss.
3. No separate package needed — The Electron bridge idea (CDP-based, standalone crate) is YAGNI. The actual token cost is dominated by real content (162 interactive elements with descriptive names), not structural noise.
4. Composable with --surface — Agents that need even smaller snapshots should scope to a surface (sheet, menu, alert) rather than us over-pruning the full tree.

Approaches Considered

1. Implement --compact with chain collapsing (CHOSEN)

• Collapse unnamed/valueless single-child non-interactive nodes
• 15-18% token reduction, zero information loss, trivial to implement
• Works for all apps, not Electron-specific

2. Standalone Electron-to-AX bridge package

• Separate crate that connects via CDP, extracts real DOM structure, maps to AX tree
• Would require --remote-debugging-port (invasive), becomes agent-browser territory
• Rejected: YAGNI. Pure AX approach already works. Adds dependency and complexity.

3. Flat interactive-only output (--flat)

• Output just refs as [{ref, role, name, value, path}] — no tree
• Minimal tokens (~2,000 for Slack) but agents lose spatial/hierarchy context
• Deferred: Could add later if compact isn't enough. Not needed now.

Key Decisions

• Chain collapsing preserves tree structure — agents still see hierarchy, just without empty wrapper noise
• Not Electron-specific — universal tree optimization via --compact flag
• No separate bridge package — unnecessary given 220ms speed and ~5,475 post-compact tokens
• Agents control scope via --surface — surface-scoped snapshots are the right lever for smaller output, not tree pruning

Open Questions

None — approach is clear and implementation is straightforward.