clide/docs/tui-ide-spec.md

TUI IDE Specification

Design specification for Clide's terminal user interface. This document describes the layout, interactions, and design decisions.

Design Principles

• Claude-centric — Claude Code is the primary workspace, always visible
• Contextual panels — Editor/Diff/Terminal appear only when needed
• Alt-key shortcuts — Keybindings use Alt to avoid conflicts with Claude Code input
• Responsive — Works on 13" laptops to widescreen monitors
• State preservation — Hiding panels preserves all state (never destroy widgets)

---

Panel Structure

Layout Overview

┌─────────────────┬─────────────────────────┬──────────────────┐
│ panel-sidebar   │ panel-workspace (60%)   │ panel-context    │
│ 20%             │ [Editor][Diff][Terminal]│ 25%              │
│                 │ (hidden when inactive)  │                  │
│ [Files][Git]    ├─────────────────────────┤ [Jira][TODOs]    │
│ [Tree]          │                         │ [Problems]       │
│                 │ panel-claude            │                  │
│ (content area)  │ (40% when workspace     │ (content area)   │
│                 │  visible, else 100%)    │                  │
├─────────────────┤                         ├──────────────────┤
│ branch-status   │                         │                  │
│ ⎇ main ▾       │                         │                  │
│ staged: 2      │                         │                  │
└─────────────────┴─────────────────────────┴──────────────────┘

Panel IDs

PANELS = {
    # Left sidebar
    "sidebar": "panel-sidebar",

    # Center
    "claude": "panel-claude",
    "workspace": "panel-workspace",

    # Right context
    "context": "panel-context",
}

---

Left Sidebar

Tabs

Tab	Content	Purpose
Files	Project file tree	Navigate and open files
Git	Staged/Unstaged changes	Review and manage changes
Tree	Branch graph	Visualize git history

Git Tab

Two collapsible sections showing staged and unstaged changes.

File status indicators:

• + Added
• ~ Modified
• - Deleted
• ? Untracked
• → Renamed

Action buttons:

• Commit — Delegate to Claude with /commit skill
• Stash — Delegate to Claude with /stash skill
• Pull — Delegate to Claude with /pull skill
• Push — Delegate to Claude with /push skill

Tree Tab

Visual git graph using box-drawing characters:

● main: Latest commit message
│
├─● feature: Feature work
│
●─┴ Merge branch 'feature'
◆ Tagged release v1.0

Symbols:

• ● Regular commit
• ◆ Merge commit
• │ Branch line
• ├ Branch point
• ┴ Merge point

Branch Status Bar

Fixed at bottom of sidebar. Shows current branch and git stats.

┌─────────────────────────────────┐
│ ⎇ main ▾    staged: 2 unstaged: 5│
└─────────────────────────────────┘

Click to expand branch selector:

┌─────────────────┐
│ Recent branches │
│ ● main         │
│ ○ feature/xyz  │
│ ○ develop      │
├─────────────────┤
│[Checkout] [New] │
└─────────────────┘

---

Center Column

Claude Panel

The primary workspace. Always visible.

Default state: 100% height of center column With workspace: 40% height (bottom)

Content:

• Full PTY terminal running Claude Code CLI
• Scrollback history (1000 lines)
• Input at bottom

Workspace Panel

Tabbed container for Editor, Diff, and Terminal. Hidden by default.

Visibility principle: Hiding is not closing. All panels retain state:

• Editor: Open file, cursor position, scroll, unsaved changes
• Diff: Current diff content, scroll position
• Terminal: Command history, output buffer

Visibility triggers:

Trigger	Result
Click file in sidebar	Show workspace, focus Editor
Click problem/TODO	Show workspace, focus Editor at line
Press Alt+`	Show workspace, focus Terminal
Close all content	Hide workspace, Claude reclaims space

Editor Tab

Code editor with:

• Syntax highlighting (tree-sitter based)
• Line numbers
• Current line highlighting

Diff Tab

Side-by-side diff viewer for:

• Git changes (staged and unstaged)
• Claude-proposed edits

Terminal Tab

Command execution terminal:

• Working directory tied to project root
• Output preserved when panel hidden

---

Right Context Panel

Tabs

Tab	Badge	Content
Jira	—	Jira issue display
TODOs	Count	TODO/FIXME from code and TODO.md
Problems	Count	Linter errors and warnings

Tab badges update reactively as counts change.

Jira Tab

Displays Jira issues via CLI integration. Manual refresh button.

TODOs Tab

Two sub-tabs:

Project tab: Items from TODO.md (checkbox format) Comments tab: TODO/FIXME/HACK/XXX comments in code

Click any item to jump to source location.

Problems Tab

Linter output showing:

• File path
• Line number
• Severity (error/warning)
• Message

Click to navigate to source.

---

Responsiveness

CSS Strategy

/* Default layout */
#panel-sidebar { width: 20%; min-width: 25; }
#panel-context { width: 25%; min-width: 30; }
#panel-claude { width: 1fr; }

Compact Mode

Toggle with Alt+C. Hides both sidebars:

.compact #panel-sidebar { display: none; }
.compact #panel-context { display: none; }

All panel state preserved when hidden.

---

Keybindings

All shortcuts use Alt modifier to avoid conflicts with Claude Code input.

Panel Navigation

Action	Binding
Toggle left sidebar	Alt+B
Toggle right sidebar	Alt+Shift+B
Toggle terminal	Alt+`
Focus Claude	Alt+1
Focus Editor	Alt+2
Focus Terminal	Alt+3
Toggle compact mode	Alt+C

Application

Action	Binding
Command palette	Alt+P
Quick open file	Alt+O
Select theme	Alt+T
Quit	Alt+Q

Git

Action	Binding
Open Git panel	Alt+G

Editor

Action	Binding
Save	Alt+S
Go to line	Alt+L
Go to problems	Alt+M

---

Panel Communication

File Navigation Flow

Sidebar file click
       │
       ▼
Workspace appears (if hidden)
       │
       ▼
Editor tab focused
       │
       ▼
File loaded in Editor

Problem/TODO Navigation Flow

Click problem/todo item
       │
       ▼
Workspace appears (if hidden)
       │
       ▼
Editor tab focused
       │
       ▼
File opened at specific line
       │
       ▼
Line scrolled into view

Git Action Flow

Click git action button (Commit, Stash, etc.)
       │
       ▼
Ensure skill installed (async, with notification)
       │
       ▼
Send /command to Claude
       │
       ▼
Claude executes git workflow

---

State Management

Reactive Properties

class ClideApp(App):
    workspace_visible: reactive[bool] = reactive(False)
    problem_count: reactive[int] = reactive(0)
    todo_count: reactive[int] = reactive(0)
    current_branch: reactive[str] = reactive("main")
    compact_mode: reactive[bool] = reactive(False)

State Preservation

Panel	Preserved State
Editor	Open file, cursor, scroll, unsaved changes
Diff	Current diff, scroll position
Terminal	Session, history, output buffer
Sidebar tabs	Scroll, expanded sections, selection
Context tabs	Scroll, selected item

---

Themes

22 built-in themes with custom theme support.

Default: summer-night (dark theme)

Theme selection persists in user settings (~/.clide/settings.json).

Custom themes can be added to ~/.clide/themes/ as TOML files.