cortex/docs/milestones/11-tui-dashboard.md

Milestone 11: TUI Dashboard

Overview

Interactive terminal user interface for browsing, searching, and managing the knowledge graph without leaving the terminal.

Motivation

• CLI commands require knowing what to type
• Visual browsing aids discovery
• Power users prefer staying in terminal
• Real-time feedback on graph state

Features

11.1 Main Dashboard

# Launch interactive TUI
cortex tui
cortex ui  # Alias

Layout:

┌─────────────────────────────────────────────────────────────────┐
│  CORTEX                                              Graph: work│
├────────────────────┬────────────────────────────────────────────┤
│  📚 Recent (5)     │  🔍 Search: ________________________      │
│  ├─ Auth flow...   │                                            │
│  ├─ API design...  │  ┌─────────────────────────────────────┐  │
│  └─ DB schema...   │  │ Auth flow design                     │  │
│                    │  │ ─────────────────────                │  │
│  📋 Tasks (3)      │  │ OAuth2 PKCE flow for SPA            │  │
│  ├─ Fix login bug  │  │                                      │  │
│  └─ Update docs    │  │ Tags: auth, security, oauth          │  │
│                    │  │ Status: active                        │  │
│  🔗 Components (8) │  │                                      │  │
│  ├─ UserService    │  │ ── Connections ──                    │  │
│  └─ AuthService    │  │ → implements: OAuth2 spec            │  │
│                    │  │ → contains: Token refresh logic      │  │
│  🎯 Decisions (4)  │  └─────────────────────────────────────┘  │
│  └─ Use JWT...     │                                            │
├────────────────────┴────────────────────────────────────────────┤
│  [/]Search [n]New [e]Edit [d]Delete [l]Link [q]Quit            │
└─────────────────────────────────────────────────────────────────┘

11.2 Navigation

• Arrow keys / vim keys (hjkl) to navigate
• Enter to select/expand
• Tab to switch panels
• / to search
• ? for help

11.3 Quick Actions

Key	Action
n	New node
e	Edit selected
d	Delete selected
l	Link to another node
t	Add tags
s	Change status
/	Search
g	Graph view (ASCII)
q	Quit

11.4 Search Mode

Real-time search as you type:

┌─────────────────────────────────────────────────────────────────┐
│  🔍 Search: auth_                                               │
├─────────────────────────────────────────────────────────────────┤
│  1. [component] AuthService (0.95)                              │
│  2. [decision] Use JWT tokens (0.87)                            │
│  3. [memory] Auth flow design (0.82)                            │
│  4. [task] Fix auth bug (0.75)                                  │
└─────────────────────────────────────────────────────────────────┘

11.5 Graph View Mode

ASCII visualization of connections:

┌─────────────────────────────────────────────────────────────────┐
│  Graph View: AuthService                                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│                    ┌──────────────┐                             │
│        depends_on  │ UserService  │                             │
│           ┌───────►│              │                             │
│           │        └──────────────┘                             │
│  ┌────────┴─────┐                                               │
│  │ AuthService  │                                               │
│  │              │──────────┐                                    │
│  └──────────────┘          │ implements                         │
│           │                ▼                                    │
│           │        ┌──────────────┐                             │
│   contains│        │ OAuth2 spec  │                             │
│           ▼        └──────────────┘                             │
│  ┌──────────────┐                                               │
│  │Token refresh │                                               │
│  └──────────────┘                                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

11.6 Edit Mode

Inline editing with validation:

┌─────────────────────────────────────────────────────────────────┐
│  Edit: AuthService                                              │
├─────────────────────────────────────────────────────────────────┤
│  Title:   [AuthService                                    ]     │
│  Kind:    [component ▼]                                         │
│  Status:  [active    ▼]                                         │
│  Tags:    [backend, auth, service                         ]     │
│                                                                 │
│  Content:                                                       │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Handles all authentication operations including:         │   │
│  │ - Login/logout                                           │   │
│  │ - Token management                                       │   │
│  │ - Session handling                                       │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  [Tab]Next field  [Ctrl+S]Save  [Esc]Cancel                    │
└─────────────────────────────────────────────────────────────────┘

Implementation

Technology Choice

Use Ink (React for CLI) or blessed-contrib:

// Using Ink
import React from 'react';
import { render, Box, Text, useInput } from 'ink';
import { useState, useEffect } from 'react';

const Dashboard: React.FC = () => {
  const [nodes, setNodes] = useState<Node[]>([]);
  const [selected, setSelected] = useState(0);
  const [mode, setMode] = useState<'browse' | 'search' | 'edit'>('browse');

  useInput((input, key) => {
    if (key.upArrow || input === 'k') setSelected(s => Math.max(0, s - 1));
    if (key.downArrow || input === 'j') setSelected(s => Math.min(nodes.length - 1, s + 1));
    if (input === '/') setMode('search');
    if (input === 'q') process.exit(0);
  });

  return (
    <Box flexDirection="column">
      <Header graph={activeGraph} />
      <Box flexDirection="row">
        <Sidebar nodes={nodes} selected={selected} />
        <DetailPanel node={nodes[selected]} />
      </Box>
      <StatusBar mode={mode} />
    </Box>
  );
};

Component Structure

src/tui/
├── index.tsx           # Entry point
├── components/
│   ├── Dashboard.tsx   # Main layout
│   ├── Sidebar.tsx     # Node list
│   ├── DetailPanel.tsx # Node details
│   ├── SearchBox.tsx   # Search input
│   ├── GraphView.tsx   # ASCII graph
│   ├── EditForm.tsx    # Edit mode
│   └── StatusBar.tsx   # Bottom bar
├── hooks/
│   ├── useNodes.ts     # Node data fetching
│   ├── useSearch.ts    # Search state
│   └── useKeyboard.ts  # Key handling
└── utils/
    └── ascii-graph.ts  # ASCII graph renderer

ASCII Graph Renderer

// src/tui/utils/ascii-graph.ts
export function renderAsciiGraph(rootId: string, depth: number = 3): string[] {
  const lines: string[] = [];
  const node = getNode(rootId);
  if (!node) return lines;

  const connections = getConnections(rootId);

  lines.push(`┌${'─'.repeat(node.title.length + 4)}┐`);
  lines.push(`│ ${node.title} │`);
  lines.push(`└${'─'.repeat(node.title.length + 4)}┘`);

  for (const conn of connections.outgoing) {
    lines.push(`    │ ${conn.type}`);
    lines.push(`    ▼`);
    lines.push(`┌${'─'.repeat(conn.node.title.length + 4)}┐`);
    lines.push(`│ ${conn.node.title} │`);
    lines.push(`└${'─'.repeat(conn.node.title.length + 4)}┘`);
  }

  return lines;
}

CLI Commands

Command	Description
cortex tui	Launch interactive TUI
cortex ui	Alias

Testing

• Navigation works smoothly
• Search updates in real-time
• Edit mode saves correctly
• Graph view renders correctly
• Handles large node lists
• Vim keybindings work
• Color scheme readable

Acceptance Criteria

• Can browse all nodes visually
• Search is responsive (<100ms)
• Edit/create nodes without leaving TUI
• Graph view shows connections
• Keyboard-only navigation
• Works in standard terminals

Estimated Effort

• Ink/blessed setup: 3 hours
• Sidebar component: 3 hours
• Detail panel: 3 hours
• Search component: 3 hours
• Edit form: 4 hours
• Graph view: 4 hours
• Polish/testing: 4 hours
• Total: ~24 hours

Dependencies

• ink or blessed-contrib
• react (for Ink)

References

• Ink - React for CLI
• blessed-contrib
• Lazygit TUI for inspiration