Research: /compact Command UI/UX Mapping

Research – /compact Command UI/UX Mapping

Date: 2026-02-22 Owner: claude Phase: Research git_commit: 050ebe24f3918159f2de53544a3eb2e445a94922

Goal

Map the complete UI/UX flow of the /compact command, identify pain points, and catalog the feedback mechanisms available to the user during compaction.

Findings

Data Flow: Controller → Callback → UI

CompactCommand.execute()
  ├─ controller.set_status_callback(app._update_compaction_status)     # compact.py:53
  ├─ controller.force_compact(...)                                      # compact.py:58
  │    └─ _compact()                                                    # controller.py:210
  │         ├─ _announce_compaction_start() → callback(True)            # controller.py:236
  │         ├─ summarizer.summarize()                                   # controller.py:238
  │         └─ finally: _announce_compaction_end() → callback(False)    # controller.py:264
  ├─ finally: controller.set_status_callback(None)                      # compact.py:64
  ├─ finally: app._update_compaction_status(False)                      # compact.py:65
  └─ finally: app._update_resource_bar()                                # compact.py:66

Relevant Files

Current User Feedback During Compaction

Ctrl+E Interaction (The Spaz Bug Context)

The ResourceBar and context panel are mutually exclusive via CSS display: none:

# app.py:419-428
def _set_context_panel_visibility(self, *, visible: bool) -> None:
    if visible:
        context_rail.remove_class("hidden")      # show panel
        self.resource_bar.add_class("hidden")     # HIDE resource bar
    else:
        context_rail.add_class("hidden")          # hide panel
        self.resource_bar.remove_class("hidden")  # SHOW resource bar

When context panel is open: ResourceBar has display: none, so "Compacting..." is invisible. The callback still mutates internal state on a hidden widget.

Comparison with Agent Request UX

Comparison with /update Command UX

/update writes progress directly to the chat container:

app.chat_container.write("Checking for updates...")
app.chat_container.write(f"Installing with {pkg_mgr}...")

/compact writes nothing to the chat container. All feedback is either the ResourceBar label or toast notifications.

Key Patterns / Solutions Found

• Mutual exclusion pattern: ResourceBar ↔ context panel via CSS hidden class creates blind spots for any status rendered only in the ResourceBar
• Status callback: Simple Callable[[bool], None] — only signals start/end, no progress granularity
• No viewport state class: Agent requests use #viewport.streaming for visual feedback; /compact has no equivalent
• No chat container output: Unlike /update, compaction writes nothing to the conversation area
• No explicit pre-flight indicator: The command relies on the controller calling callback(True) — there's no immediate visual change when the user types /compact

Knowledge Gaps

1. Exact timing: How long does a typical compaction take? (Depends on context size + LLM latency)
2. Error UX: If force_compact() raises an exception, the finally block clears the status but no error toast is shown to the user
3. Concurrent safety: What happens if a user submits a message while /compact is running? The event handler awaits, so it queues, but no UI indication of this
4. Context panel compaction display: The context panel shows tokens/model/cost/files but has zero compaction-related information

UX Issues Identified

P0: No feedback when context panel is open

• Problem: "Compacting..." renders only in ResourceBar which is display: none when context panel is visible
• Impact: User sees nothing happening during a potentially long operation
• Fix: Add compaction status to context panel OR write to chat container

P1: No immediate visual response

• Problem: After typing /compact, nothing visible happens until the controller fires callback(True) — could be delayed by token estimation and threshold checks
• Fix: Show feedback immediately in CompactCommand.execute() before awaiting force_compact()

P2: No error feedback on exception

• Problem: If force_compact() throws, the finally block clears status but no toast/notification is shown
• Fix: Add except Exception with app.notify(str(e), severity="error")

P3: No chat container record

• Problem: Compaction leaves no trace in the conversation. User can't scroll back and see that compaction happened or what it did
• Fix: Write a brief compaction summary to chat_container (matching /update pattern)

P4: No viewport state feedback

• Problem: During agent requests, the viewport gets a .streaming class (visual bevel inversion). /compact has no equivalent, so the UI looks idle during a long operation
• Fix: Add #viewport.compacting CSS class or reuse .streaming

P5: Toast notifications are ephemeral

• Problem: Completion/skip/error toasts auto-dismiss and are never logged to the conversation
• Impact: User misses results if they look away

References

• src/tunacode/ui/commands/compact.py — command implementation
• src/tunacode/core/compaction/controller.py — controller with callback mechanism
• src/tunacode/ui/widgets/resource_bar.py — "Compacting..." display
• src/tunacode/ui/app.py — toggle logic (L419-438), status bridge (L531-556)
• src/tunacode/ui/styles/layout.tcss — ResourceBar.hidden CSS
• memory-bank/research/2026-02-12_issue-382_manual-compact-boundary-map.md — prior research on manual compact boundaries
• memory-bank/research/2026-02-10_21-29-05_compaction-system-mapping.md — prior compaction system mapping