# CLI UI Polish Roadmap

A phased plan to bring Anteroom's CLI from "functional" to "refined" --- matching the fit-and-finish of tools like Claude Code, OpenCode, and Codex.

## Why This Matters

The CLI is the developer power tool. Every interaction --- sending a message, waiting for a response, reading tool output, recovering from an error --- either builds or erodes confidence that the tool is worth using. "Refined" isn't about aesthetics; it's about **information density, responsiveness, and predictability**.

The gap today isn't features. Anteroom's CLI has more capability than most competitors. The gap is *feel*: how tokens arrive on screen, how tool calls communicate progress, how errors guide recovery, how the tool responds to cancel. These are the details that separate "I tolerate this" from "I prefer this."

---

## Phase 1: Perception of Speed

**Goal:** The CLI feels fast and responsive, even when the LLM is slow.

These changes affect what the user sees *before and between* content. They're high-impact because they address the most common anxiety: "is it stuck?"

| Issue | Title | Impact |
|-------|-------|--------|
| [#1366](https://github.com/troylar/anteroom/issues/1366) | Context-aware thinking indicators | Eliminates "is it stuck?" --- the #1 UX complaint |
| [#1372](https://github.com/troylar/anteroom/issues/1372) | Instant cancel responsiveness | Cancel feels instant, not "please wait" |
| [#1371](https://github.com/troylar/anteroom/issues/1371) | Startup time optimization | Sub-200ms to prompt --- first impression matters |

**Dependencies:** None. These are independent and can be worked in parallel.

**Milestone:** Users never wonder if the CLI is frozen. Every state transition has immediate visual feedback.

---

## Phase 2: Output Quality

**Goal:** What the AI produces looks great on screen --- streaming feels smooth, code blocks are crisp, output is scannable.

This is what users stare at most. Streaming quality is the most visible differentiator between AI CLI tools.

| Issue | Title | Impact |
|-------|-------|--------|
| [#1365](https://github.com/troylar/anteroom/issues/1365) | Smooth streaming with live markdown | The single most visible quality signal |
| [#1370](https://github.com/troylar/anteroom/issues/1370) | Visual hierarchy between message types | Scannability --- instantly distinguish prose from code from tools |

**Dependencies:** #1370 informs the visual container that #1365 streams into. Work #1370 first (define the visual lanes), then #1365 (stream content into them).

**Milestone:** Scrolling back through a conversation, you can instantly orient yourself. Streaming feels like watching someone type, not watching a buffer flush.

---

## Phase 3: Tool Call UX

**Goal:** Tool execution is informative but not noisy. The user sees what matters, can dig deeper on demand.

Tool calls are the most frequent non-prose output. Getting them right makes the AI feel like a capable assistant rather than a verbose script.

| Issue | Title | Impact |
|-------|-------|--------|
| [#1364](https://github.com/troylar/anteroom/issues/1364) | Compact tool call rendering | Spinner to one-line summary to expandable detail |
| [#1367](https://github.com/troylar/anteroom/issues/1367) | Smart output density | Collapsible results, compact diffs, smart truncation |

**Dependencies:** #1364 defines the tool call lifecycle; #1367 extends it to tool *results*. Work #1364 first.

**Milestone:** A 10-tool-call sequence reads as 10 clean lines, not 50 lines of output. Users control verbosity, not the tool.

---

## Phase 4: Input and Error Polish

**Goal:** The input experience matches the output quality. Errors guide rather than punish.

These are the finishing touches that make the difference between "good" and "delightful."

| Issue | Title | Impact |
|-------|-------|--------|
| [#1368](https://github.com/troylar/anteroom/issues/1368) | Refined error presentation | One-line actionable errors, no tracebacks |
| [#1369](https://github.com/troylar/anteroom/issues/1369) | Input polish | Smart paste, fuzzy autocomplete, keybinding hints |

**Dependencies:** #1369 overlaps with existing issues #1088 (large input), #1089 (paste undo grouping). Coordinate to avoid duplication.

**Milestone:** New users feel guided. Experienced users feel fast. Errors are speed bumps, not walls.

---

## Phase Ordering Rationale

```
Phase 1 (Speed Perception)     Phase 2 (Output Quality)
  #1366 thinking indicators       #1370 visual hierarchy
  #1372 instant cancel            #1365 smooth streaming
  #1371 startup time                  |
        |                             v
        v                      Phase 3 (Tool Call UX)
  Phase 4 (Input/Error)          #1364 compact tool calls
    #1368 error presentation      #1367 output density
    #1369 input polish
```

**Why this order:**

1. **Phase 1 first** because perceived speed is the most common complaint and the easiest to fix. These are mostly state machine and timing changes, not rendering overhauls.
2. **Phase 2 before Phase 3** because the visual hierarchy (#1370) establishes the container system that tool calls (#1364) and streaming (#1365) render into. Doing tool calls first without visual lanes means redoing the styling later.
3. **Phase 3 before Phase 4** because tool call rendering is seen more often than error messages. Higher frequency = higher impact.
4. **Phase 4 last** because input and error polish are refinements on top of a foundation that already works. They make a good CLI great, but they don't fix a bad one.

---

## Success Criteria

After all four phases, a blind test between Anteroom's CLI and Claude Code / OpenCode should produce responses like:

- "Both feel about the same" (parity)
- "I like Anteroom's [specific feature] better" (differentiation)

Not:

- "Anteroom feels clunky compared to X" (the current gap)

## Measuring Progress

For each issue, the PR should include:

1. **Before/after demo GIF** (VHS tape in `demos/`) showing the specific improvement
2. **Benchmark** where applicable (startup time, cancel latency, streaming smoothness)
3. **User testing note** --- at minimum, the implementer's subjective assessment of "does this feel better?"
