# 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 command discovery works, 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 and Turn Flow

**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?" and whether a turn feels like one coherent interaction.

| Issue | Title | Impact | Status |
|-------|-------|--------|--------|
| [#1366](https://github.com/troylar/anteroom/issues/1366) | Context-aware thinking indicators | Eliminates "is it stuck?" --- the #1 UX complaint | Shipped |
| [#1372](https://github.com/troylar/anteroom/issues/1372) | Instant cancel responsiveness | Cancel feels instant, not "please wait" | Shipped |
| [#1371](https://github.com/troylar/anteroom/issues/1371) | Startup time optimization | Sub-200ms to prompt --- first impression matters | Shipped |
| [#1428](https://github.com/troylar/anteroom/issues/1428) | Unify live turn status into one ambient status line | Makes thinking, tool activity, retry, cancel, and done feel like one choreographed timeline | Shipped |

**Dependencies:** `#1428` builds on the state work from `#1366` and `#1372`. Phase 1 is complete.

**Milestone:** Users never wonder if the CLI is frozen. Every state transition has immediate visual feedback and the turn lifecycle feels like one intentional system. *Achieved with `#1428`.*

---

## 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 live tool-call lifecycle in REPL | Running tool activity settles into concise per-call summaries instead of log-like breadcrumbs |
| [#1367](https://github.com/troylar/anteroom/issues/1367) | Smart output density | Collapsible results, compact diffs, smart truncation |

**Dependencies:** `#1364` defines the live lifecycle; `#1367` extends that to result density.

**Milestone:** A 10-tool-call sequence reads as a compact, inspectable execution trace instead of 50 lines of noise. Users control verbosity, not the tool.

---

## Phase 4: Command Entry, 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." This phase covers how users discover commands, edit complex input, and recover from problems without friction.

| 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 --- paste handling, path completion, keybinding hints | Makes the input surface feel premium without overloading `/` discovery |
| [#1429](https://github.com/troylar/anteroom/issues/1429) | Turn `/` into an action-oriented command palette | Makes command discovery fluent instead of `/help`-driven |

**Dependencies:** `#1369` overlaps with `#1088` / `#1089` / `#1090` / `#1091` and should stay focused on input feel, not the slash-command palette. `#1429` owns `/` browsing, ranking, and insertion scaffolding.

**Milestone:** New users feel guided. Experienced users feel fast. Commands are easy to acquire, and errors are speed bumps, not walls.

---

## Phase Ordering Rationale

```
Phase 1 (Speed + Turn Flow)    Phase 2 (Output Quality)
  #1366 thinking indicators       #1370 visual hierarchy
  #1372 instant cancel            #1365 smooth streaming
  #1371 startup time                  |
  #1428 ambient status line          |
        |                             v
        v                      Phase 3 (Tool Call UX)
  Phase 4 (Command/Input/Error)  #1364 live tool lifecycle
    #1368 error presentation      #1367 output density
    #1369 input polish
    #1429 command palette
```

**Why this order:**

1. **Phase 1 first** because perceived speed and turn confidence are the most common complaints. These are mostly state-machine and timing changes, not heavy rendering overhauls.
2. **Phase 2 before Phase 3** because the visual hierarchy (`#1370`) establishes the container system that tool UX (`#1364`) and streaming (`#1365`) render into. Doing tool execution polish first without visual lanes means redoing styling later.
3. **Phase 3 before Phase 4** because tool execution is seen more often than command browsing or error recovery. Higher frequency = higher impact.
4. **Phase 4 last** because command entry, input polish, and error polish are refinements on top of a runtime that already feels calm and legible. They make a good CLI great, but they do not fix a chaotic 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?"
