UI_UX_NOTES.md

CodexU UI/UX Notes

This file describes the current UX intent so future work does not accidentally undo the design.

Product framing

CodexU is a remote control plane for Codex, not a different Codex engine.

That means:

• it should surface state clearly
• it should reduce operational friction
• it should not overtake Codex with wrapper-specific policy hacks

Conversation area

Chat and Commands split

The conversation view is intentionally split into:

• Chat
• Commands

Why:

• command cards were visually noisy
• long shells and outputs drowned out the actual conversation
• users still need access to command detail, but not by default

Keep:

• Chat as the default
• Commands as the explicit inspection view
• Running commands: N visible from chat

Thinking feedback

The app must not look frozen during long tool or context-compaction work.

Keep:

• Thinking · Ns
• reconnecting/working indicators
• compact visible progress instead of silent waiting

Plan visibility

Plan activity should not steal focus from the main conversation.

Keep:

• Plan as a separate tab for full planning output
• the current tab stable while plan responses arrive
• a short plan summary card in Chat with an explicit Open Plan action

Skills UX

Native-first principle

Selected skills should be sent as native skill attachments.

Do not reintroduce:

• long wrapper policy text
• global skill forcing paragraphs in user prompts
• auto-discovery/install behavior hidden from the user

Skill review

Skill review exists to offer help before execution without hijacking the prompt.

Desired behavior:

• only recommend already-installed skills
• ask before adding them
• allow one-thread snooze
• do not silently mutate project defaults

Skills Hub vs Presets

These are intentionally separate.

• Skills Hub: discover, install, update, repair, disable, uninstall
• Presets: compose reusable skill packs for projects and sessions

Do not merge them back into one overloaded screen unless there is a much stronger information architecture.

Project/session state

Header badges

Top badges are a status strip, not duplicate composer clutter.

They should summarize:

• current preset
• active attached skills
• skill review state
• context usage

Why:

• users need to understand the project state while reading the thread
• status belongs near the thread, not buried in the composer

Context usage

Context usage is thread-local and not the same thing as account quota.

Keep:

• Context {percent}% based on model_auto_compact_token_limit when available
• fallback to modelContextWindow only when the compact threshold is unavailable
• explicit wording that distinguishes context usage from account quota
• a manual Compact context action near the context details

Current operating decision:

• model_auto_compact_token_limit = 225000 on local and VPS runtimes
• treat that threshold as the 100% point for the usage chip

Composer

The composer should remain input-first.

Do not bring back heavyweight duplicated controls into the desktop composer if the same state is already represented and editable through dedicated UI.

Mobile

Mobile favors compact sheets and large touch targets.

Keep:

• compact composer controls
• sheet-style configuration and review UI
• better line-wrapping for paths and commands
• side drawer behavior optimized for thread switching

Locale

The current EN/KO locale system is intentionally lightweight.

Keep in mind:

• only the high-traffic screens were translated
• this is not a full i18n framework
• extend the existing mechanism; do not replace it casually unless the whole app is being internationalized

Design rule for future changes

Prefer:

• clearer state visibility
• fewer duplicated controls
• smaller, more explicit confirmations
• native Codex behavior where possible

Avoid:

• forcing behavior through prompt scaffolding
• combining management screens that serve different jobs
• hiding long-running activity without visible status