qwen-code/docs/design/compact-mode/compact-mode-design.md

Compact Mode Design: Competitive Analysis & Optimization

Ctrl+O compact/verbose mode toggle — competitive analysis with Claude Code, current implementation review, and optimization recommendations.

User documentation: Settings — ui.compactMode.

1. Executive Summary

Qwen Code and Claude Code both provide a Ctrl+O shortcut for toggling between compact and detailed tool output views, but the design philosophy, default state, and interaction model differ fundamentally. This document provides a deep source-level comparison, identifies UX gaps, and proposes optimizations for Qwen Code.

Dimension	Claude Code	Qwen Code
Default mode	Compact (verbose=false)	Verbose (compactMode=false)
Toggle semantics	Temporary peek at details	Persistent preference switch
Persistence	Session-only, resets on restart	Persisted to settings.json
Scope	Global screen switch (prompt ↔ transcript)	Per-component rendering toggle
Frozen snapshot	None (no concept)	None (removed)
Per-tool expand hint	Yes ("ctrl+o to expand")	Yes ("Press Ctrl+O to show full tool output")

2. Claude Code Implementation Analysis

2.1 Architecture

Claude Code uses a screen-based approach rather than a component-level rendering toggle:

┌──────────────────────────────────┐
│         AppState (Zustand)       │
│  verbose: boolean (default: false)│
│  screen: 'prompt' | 'transcript' │
└──────────┬───────────────────────┘
           │
     ┌─────┴──────┐
     │  Ctrl+O    │  toggles screen mode
     │  Handler    │  NOT a rendering flag
     └─────┬──────┘
           │
     ┌─────▼──────────────┐
     │    REPL.tsx         │
     │  screen='prompt'  → compact view (default)
     │  screen='transcript'→ detailed view
     └────────────────────┘

2.2 Key Source Files

Component	File	Key Logic
Toggle handler	src/hooks/useGlobalKeybindings.tsx:90-132	Switches screen between 'prompt' and 'transcript'
Keybinding	src/keybindings/defaultBindings.ts:44	app:toggleTranscript
State definition	src/state/AppStateStore.ts:472	verbose: false (session-only)
Expand hint	src/components/CtrlOToExpand.tsx:29-46	Per-tool "(ctrl+o to expand)" text
Message filter	src/components/Messages.tsx:93-151	filterForBriefTool() for compact view
Permission	src/components/permissions/PermissionRequest.tsx	Rendered in overlay layer, never hidden

2.3 Design Decisions

1. Compact is the default. Users see a clean interface out of the box; detail is opt-in.
2. Session-scoped. verbose resets to false on every new session — Claude Code assumes users generally prefer the compact view and only need details temporarily.
3. Screen-level toggle. Ctrl+O doesn't change how components render; it switches the entire display between a "prompt" screen (compact) and a "transcript" screen (detailed).
4. No frozen snapshot. There is no snapshot freezing concept. When toggling, the display updates immediately with current state.
5. Permission dialogs are separate. Tool approvals are rendered in a dedicated overlay layer that is never affected by the verbose/compact toggle.
6. Per-tool hint. CtrlOToExpand component shows a contextual hint on individual tools when they produce large output, suppressed in sub-agents.

2.4 User Flow

Session start → compact mode (default)
     │
     ├─ Tool outputs are summarized in a single line
     ├─ Large tool output shows "(ctrl+o to expand)" hint
     │
     ├─ User presses Ctrl+O
     │     └─→ Screen switches to transcript (detailed view)
     │         └─ User sees all tool output, thinking, etc.
     │
     ├─ User presses Ctrl+O again
     │     └─→ Screen switches back to prompt (compact)
     │
     └─ Session ends → verbose resets to false

3. Qwen Code Implementation Analysis

3.1 Architecture

Qwen Code uses a component-level rendering flag that each UI component reads from context:

┌─────────────────────────────────────┐
│      CompactModeContext             │
│  compactMode: boolean (default: false)│
│  setCompactMode: (v) => void        │
└──────────┬──────────────────────────┘
           │
     ┌─────┴──────┐
     │  Ctrl+O    │  toggles compactMode
     │  Handler    │  persists to settings
     └─────┬──────┘
           │
     ┌─────▼──────────────────┐
     │  Each component reads  │
     │  compactMode and       │
     │  decides how to render │
     └────────────────────────┘
           │
     ┌─────▼──────────────────────────────┐
     │  ToolGroupMessage                   │
     │    showCompact = compactMode        │
     │      && !hasConfirmingTool          │
     │      && !hasErrorTool               │
     │      && !isEmbeddedShellFocused     │
     │      && !isUserInitiated            │
     └────────────────────────────────────┘

3.2 Key Source Files

Component	File	Key Logic
Toggle handler	AppContainer.tsx:1684-1690	Toggles compactMode, persists to settings
Context	CompactModeContext.tsx	compactMode, setCompactMode
Tool group	ToolGroupMessage.tsx:105-110	showCompact with 4 force-expand conditions
Tool message	ToolMessage.tsx:346-350	Hides displayRenderer in compact mode
Compact display	CompactToolGroupDisplay.tsx:49-108	Single-line summary with status + hint
Confirmation	ToolConfirmationMessage.tsx:113-147	Simplified 3-option compact approval
Tips	Tips.tsx:14-29	Startup tip rotation includes compact mode hint
Settings sync	SettingsDialog.tsx:189-193	Syncs with CompactModeContext + refreshStatic
MainContent	MainContent.tsx:60-76	Renders live pendingHistoryItems
Thinking	HistoryItemDisplay.tsx:123-133	Hides gemini_thought in compact mode

3.3 Design Decisions

1. Verbose is the default. Users see all tool output and thinking by default.
2. Persistent preference. compactMode is saved to settings.json and survives across sessions.
3. Component-level rendering. Each component reads compactMode from context and adjusts its own rendering.
4. Force-expand protection. Four conditions override compact mode to ensure critical UI elements are always visible (confirmations, errors, shell, user-initiated).
5. No snapshot freezing. The toggle always shows live output — no frozen snapshots.
6. Settings dialog sync. Toggling compact mode from Settings updates React state immediately via setCompactMode.
7. Non-intrusive discoverability. Compact mode is introduced via the startup Tips rotation rather than a persistent footer indicator, avoiding UI clutter.

3.4 User Flow

Session start → verbose mode (default)
     │
     ├─ All tool outputs, thinking, details visible
     │
     ├─ User presses Ctrl+O (or toggles in Settings)
     │     └─→ compactMode = true, persisted
     │         ├─ Tool groups show single-line summary
     │         ├─ Thinking/thought content hidden
     │         └─ Confirmations, errors, shell still expanded
     │
     ├─ User presses Ctrl+O again
     │     └─→ compactMode = false, persisted
     │         └─ All details visible again
     │
     └─ Next session → same mode as last session

4. Key Differences Deep Dive

4.1 Default Mode Philosophy

Aspect	Claude Code (compact default)	Qwen Code (verbose default)
First impression	Clean, minimal — professional feel	Information-rich — full transparency
Learning curve	User must learn Ctrl+O to see details	User can immediately see everything
Target audience	Experienced users who trust the tool	Users who want to understand what's happening
Information overload	Avoided by default	Possible for new users
Discoverability	Per-tool "(ctrl+o to expand)" hints	Startup Tips rotation + ? shortcuts + /help

Analysis: Claude Code's compact default works because its user base is generally experienced developers who trust the tool and don't need to see every tool invocation. Qwen Code's verbose default is appropriate for its earlier stage where building user trust through transparency is important.

4.2 Persistence Model

Aspect	Claude Code	Qwen Code
Persisted?	No — session-only	Yes — to settings.json
Rationale	Verbose is temporary peek	Mode is user preference
Restart behavior	Always starts compact	Starts with last-used mode

Analysis: Claude Code treats detail viewing as a momentary need — you look, then go back. Qwen Code treats it as a stable preference — some users always want details, others always want compact. Both are valid; Qwen Code's approach is more flexible.

4.3 Confirmation Protection

Aspect	Claude Code	Qwen Code
Mechanism	Overlay/modal layer (structurally separate)	Force-expand conditions in showCompact
Coverage	Complete — approvals can never be hidden	Complete — 4 conditions cover all interactive states
Compact confirmation UI	N/A (overlay is always full)	Simplified 3-option RadioButtonSelect

Analysis: Claude Code's architectural separation (overlay layer) is more robust. Qwen Code's force-expand approach is effective but requires each new interactive state to be explicitly added to the condition list.

4.4 Rendering Approach

Aspect	Claude Code	Qwen Code
Toggle scope	Screen-level (prompt ↔ transcript)	Component-level (each component decides)
Granularity	All-or-nothing	Fine-grained per component
Flexibility	Low — global switch	High — components can override
Consistency	Guaranteed	Depends on each component's implementation

Analysis: Qwen Code's component-level approach is more flexible (e.g., force-expand for specific conditions) but requires more discipline to maintain consistency. Claude Code's screen-level approach is simpler and guarantees consistent behavior.

5. Optimization Recommendations

5.1 [P0] Keep Verbose as Default — No Change Needed

Qwen Code's verbose default is the right choice for its current stage. Users who are new to the tool need transparency to build trust. As the product matures, consider making compact the default (like Claude Code).

5.2 [P1] Per-Tool Expansion for Large Outputs

Claude Code shows "(ctrl+o to expand)" on individual tools that produce large output. Qwen Code currently only has a global toggle. Consider:

• When a single tool produces output exceeding N lines, show a per-tool "expand" hint in compact mode.
• Scope: future enhancement, not current priority.

5.3 [P2] Consider Session-Scoped Override

Some users may want compact mode as their default but occasionally need verbose for a specific session. Consider supporting both:

• settings.json → persistent default (current behavior)
• Ctrl+O during session → temporary override for current session only (Claude Code behavior)
• On session restart → revert to settings.json value

This gives users the best of both worlds. Implementation would require separating "settings default" from "session override" state.

5.4 [P2] Structural Separation for Confirmations

Currently, confirmation protection relies on showCompact conditions in ToolGroupMessage. Consider a more robust approach:

• Render confirmations in a separate layer (like Claude Code's overlay approach).
• This would make it architecturally impossible for compact mode to affect confirmations.
• Lower priority since the current force-expand approach works correctly.

6. Current Implementation Status

After the feat/compact-mode-optimization branch changes:

Feature	Status	Notes
Startup Tips hint	Done	Compact mode tip in Tips rotation (non-intrusive)
Ctrl+O in keyboard shortcuts (?)	Done	Added to KeyboardShortcuts component
Ctrl+O in /help	Done	Added to Help component
Settings dialog sync	Done	Syncs compactMode with CompactModeContext
No snapshot freezing	Done	Toggle always shows live output
Confirmation protection	Done	Force-expand + WaitingForConfirmation guard
Shell protection	Done	!isEmbeddedShellFocused force-expand
Error protection	Done	!hasErrorTool force-expand
User docs updated	Done	settings.md, keyboard-shortcuts.md

7. File Reference

Qwen Code

File	Purpose
packages/cli/src/ui/AppContainer.tsx	Toggle handler, state initialization, context provider
packages/cli/src/ui/contexts/CompactModeContext.tsx	Context definition
packages/cli/src/ui/components/messages/ToolGroupMessage.tsx	Force-expand logic
packages/cli/src/ui/components/messages/ToolMessage.tsx	Per-tool output hiding
packages/cli/src/ui/components/messages/CompactToolGroupDisplay.tsx	Compact view rendering
packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx	Compact confirmation UI
packages/cli/src/ui/components/MainContent.tsx	Pending history items rendering
packages/cli/src/ui/components/Tips.tsx	Startup tip with compact mode hint
packages/cli/src/ui/components/Help.tsx	/help shortcut entry
packages/cli/src/ui/components/KeyboardShortcuts.tsx	? shortcut entry
packages/cli/src/ui/components/SettingsDialog.tsx	Settings sync
packages/cli/src/ui/components/HistoryItemDisplay.tsx	Thinking content hiding
packages/cli/src/config/settingsSchema.ts	Setting definition
packages/cli/src/config/keyBindings.ts	Ctrl+O binding

Claude Code (Reference)

File	Purpose
src/hooks/useGlobalKeybindings.tsx	Toggle handler
src/state/AppStateStore.ts	State definition (verbose: false)
src/components/CtrlOToExpand.tsx	Per-tool expand hint
src/components/Messages.tsx	Brief message filter
src/screens/REPL.tsx	Screen-level mode switching
src/components/permissions/PermissionRequest.tsx	Overlay-based confirmation