Dex TUI - Planning Session Interface

[dcramer]

Plan: Dex TUI - Planning Session Interface

Summary

Build a terminal-based UI (dex-tui) that provides a persistent interface for managing dex tasks and spawning Claude Code planning sessions. The TUI allows users to maintain a backlog while agents work, easily firing off read-only research sessions that result in new dex tasks or plans.

Problem Statement

When working with Claude Code agents on complex projects, users need to:

1. Quickly capture ideas for new features, refactors, or bug fixes without interrupting their main workflow
2. Spawn read-only "planning" sessions that research the codebase and generate structured task plans
3. Maintain visibility into a growing backlog while agents execute
4. Convert planning session outputs directly into dex tasks

Currently, this requires manual context-switching between the terminal, dex CLI, and Claude Code sessions.

Solution Overview

A terminal TUI (built with Ink for React-based rendering) that:

• Shows the current dex task backlog in real-time
• Provides quick actions to create tasks manually
• Spawns Claude Code SDK planning sessions in the background
• Captures planning session results and converts them to dex tasks
• Runs alongside active Claude Code sessions without interference

Architecture

Project Structure

packages/
├── dex/                    # Existing dex package (unchanged)
└── dex-tui/                # New TUI package
    ├── package.json
    ├── tsconfig.json
    └── src/
        ├── index.tsx       # Entry point
        ├── app.tsx         # Main App component
        ├── components/
        │   ├── TaskList.tsx      # Backlog view
        │   ├── TaskDetail.tsx    # Selected task details
        │   ├── PlanningSession.tsx  # Active session view
        │   ├── SessionList.tsx   # Running sessions sidebar
        │   ├── QuickCreate.tsx   # Fast task input
        │   └── StatusBar.tsx     # Footer with keybindings
        ├── hooks/
        │   ├── useDex.ts         # TaskService integration
        │   ├── useSessions.ts    # Claude session management
        │   └── useKeyboard.ts    # Keybinding handler
        ├── services/
        │   ├── claude-bridge.ts  # Claude Agent SDK wrapper
        │   └── session-store.ts  # Session state persistence
        └── types.ts

Technology Choices

Component	Choice	Rationale
UI Framework	Ink (React for CLI)	Declarative, familiar React patterns, active ecosystem
State	Zustand	Lightweight, works well with React, persistent middleware
Claude Integration	@anthropic-ai/claude-agent-sdk	Official SDK, supports plan mode, session resume
Task Backend	dex core	Reuse existing TaskService, storage, validation

Key Design Decisions

1. Monorepo with shared packages: dex-tui imports from dex core, ensuring consistency
2. Background sessions: Planning sessions run asynchronously, results streamed to UI
3. Session persistence: Active sessions survive TUI restart via session IDs
4. Read-only by default: Planning sessions use permissionMode: "plan" for safety

Features

Phase 1: Core TUI

1.1 Task Backlog View

• Tree view of pending tasks (like dex status but interactive)
• Navigate with j/k or arrow keys
• Enter to view task details
• Filter by: all, ready, blocked, search query

1.2 Quick Task Creation

• Press c to open quick-create modal
• Minimal input: name only (description optional)
• Press C (shift) for full create with parent, blockers, etc.

1.3 Task Actions

• e - Edit selected task
• d - Delete (with confirmation)
• x - Mark complete
• p - Set parent
• b - Add blocker

1.4 Status Bar

• Show keybindings for current context
• Display pending session count
• Show last sync time (if GitHub sync enabled)

Phase 2: Planning Sessions

2.1 Spawn Planning Session

• Press n (new) to start planning session
• Prompt input: "What do you want to research/plan?"
• Session spawns in background with read-only tools

2.2 Session Configuration

interface PlanningSessionConfig {
  prompt: string;
  cwd: string;               // Default: current project
  model: "claude-sonnet-4" | "claude-opus-4"; // Default: sonnet for speed
  allowedTools: string[];    // Default: ["Read", "Glob", "Grep", "WebSearch"]
  maxTurns?: number;         // Optional limit
}

2.3 Session Sidebar

• List of active/completed sessions
• Status indicators: spinning, complete, error
• Press number key (1-9) to focus session
• Press Tab to toggle between backlog and sessions

2.4 Session Results

• When session completes, show result in detail pane
• Parse result for task structure (if plan-like)
• Offer actions:
  • t - Create single task from result
  • P - Run /dex-plan to create full task hierarchy
  • r - Re-run session with follow-up
  • s - Save raw result to file

Phase 3: Advanced Features

3.1 Session Templates
Pre-configured session types:

• "Research": Explore codebase for specific topic
• "Bug Analysis": Investigate bug with read-only access
• "Feature Plan": Generate implementation plan for feature
• "Refactor Scope": Identify refactoring boundaries

3.2 Batch Operations

• Select multiple tasks with Space
• Bulk complete, delete, or re-parent

3.3 Session Resume

• List previous sessions
• Resume with additional context
• Fork session for alternative exploration

3.4 Live Cost Tracking

• Show token usage per session
• Running total for current TUI session
• Configurable budget alerts

User Interface

Main Layout

┌─────────────────────────────────────────────────────────────────────┐
│  DEX TUI                                            Sessions: 2 ⟳  │
├─────────────────────────────────────┬───────────────────────────────┤
│  BACKLOG (12 tasks)                 │  SESSION OUTPUT              │
│                                     │                               │
│  [ ] abc123 Add user auth           │  Planning: "How does auth... │
│    [ ] def456 Create user model     │                               │
│    [ ] ghi789 Add JWT middleware    │  > Reading src/auth/...       │
│  [B] jkl012 Refactor database       │  > Found 3 auth-related files │
│  [ ] mno345 Fix login bug           │  > Analyzing patterns...      │
│  ▸ [ ] pqr678 Update docs           │                               │
│                                     │  [Streaming...]               │
│                                     │                               │
│                                     │                               │
│                                     │                               │
├─────────────────────────────────────┴───────────────────────────────┤
│  [c]reate [n]ew session [e]dit [x]complete [d]elete | [Tab] switch  │
└─────────────────────────────────────────────────────────────────────┘

Quick Create Modal

┌──────────────────────────────────────────┐
│  Quick Create Task                       │
│                                          │
│  Name: Fix authentication timeout bug_   │
│                                          │
│  [Enter] Create  [Esc] Cancel            │
└──────────────────────────────────────────┘

Session Detail View

┌─────────────────────────────────────────────────────────────────────┐
│  SESSION: Research authentication patterns                          │
│  Status: Complete ✓  |  Tokens: 12.4k  |  Cost: $0.02               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ## Summary                                                         │
│                                                                     │
│  The codebase uses JWT-based authentication with the following      │
│  structure:                                                         │
│                                                                     │
│  1. `src/auth/jwt.ts` - Token generation and validation             │
│  2. `src/middleware/auth.ts` - Express middleware                   │
│  3. `src/routes/auth.ts` - Login/logout endpoints                   │
│                                                                     │
│  ## Suggested Tasks                                                 │
│                                                                     │
│  - Add refresh token support                                        │
│  - Implement token revocation                                       │
│  - Add rate limiting to auth endpoints                              │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│  [t] Create task  [P] Create plan  [r] Follow-up  [Esc] Back        │
└─────────────────────────────────────────────────────────────────────┘

Implementation Details

Claude Agent SDK Integration

// services/claude-bridge.ts
import { query, type SDKResultMessage } from "@anthropic-ai/claude-agent-sdk";

interface PlanningSession {
  id: string;
  prompt: string;
  status: "running" | "complete" | "error";
  messages: SDKMessage[];
  result?: SDKResultMessage;
  sessionId?: string;  // Claude session ID for resume
}

async function* runPlanningSession(
  config: PlanningSessionConfig
): AsyncGenerator<SDKMessage, PlanningSession> {
  const session: PlanningSession = {
    id: nanoid(8),
    prompt: config.prompt,
    status: "running",
    messages: [],
  };

  try {
    for await (const message of query({
      prompt: config.prompt,
      options: {
        cwd: config.cwd,
        model: config.model ?? "claude-sonnet-4",
        permissionMode: "plan",  // Read-only
        allowedTools: config.allowedTools ?? [
          "Read", "Glob", "Grep", "WebSearch", "WebFetch"
        ],
        maxTurns: config.maxTurns,
      },
    })) {
      session.messages.push(message);

      // Capture session ID for resume
      if (message.type === "system" && message.subtype === "init") {
        session.sessionId = message.session_id;
      }

      yield message;

      // Capture final result
      if (message.type === "result") {
        session.result = message;
        session.status = message.is_error ? "error" : "complete";
      }
    }
  } catch (error) {
    session.status = "error";
    throw error;
  }

  return session;
}

Dex Integration

// hooks/useDex.ts
import { TaskService } from "@zeeg/dex/core/task-service";
import { JsonlStorage } from "@zeeg/dex/core/storage/jsonl-storage";
import { getStoragePath } from "@zeeg/dex/core/storage/paths";

function useDex() {
  const [tasks, setTasks] = useState<Task[]>([]);
  const serviceRef = useRef<TaskService>();

  useEffect(() => {
    const storage = new JsonlStorage(getStoragePath());
    serviceRef.current = new TaskService(storage);
    refresh();
  }, []);

  const refresh = async () => {
    const allTasks = await serviceRef.current!.list({});
    setTasks(allTasks);
  };

  const createTask = async (input: CreateTaskInput) => {
    await serviceRef.current!.create(input);
    await refresh();
  };

  // ... other operations

  return { tasks, createTask, refresh, /* ... */ };
}

Session to Task Conversion

// Converting session result to dex task
async function sessionToTask(
  session: PlanningSession,
  service: TaskService
): Promise<Task> {
  const result = session.result!;

  return service.create({
    name: `Research: ${session.prompt.slice(0, 40)}...`,
    description: result.result,  // Full session output as context
    metadata: {
      claude_session: {
        sessionId: session.sessionId,
        prompt: session.prompt,
        tokens: result.usage,
        cost: result.total_cost_usd,
      },
    },
  });
}

// For structured plans, parse and create hierarchy
async function sessionToPlan(
  session: PlanningSession,
  service: TaskService
): Promise<Task> {
  // Write result to temp file
  const tempPath = `/tmp/dex-plan-${session.id}.md`;
  await writeFile(tempPath, `# Plan: ${session.prompt}\n\n${session.result!.result}`);

  // Use existing dex plan command logic
  // (or call dex plan CLI directly)
}

Subtasks

Phase 1: Foundation

1. Set up dex-tui package - Create package structure, configure build, add to workspace
2. Implement basic Ink app - Main layout with task list and detail panes
3. Add dex integration - Hook up TaskService, implement refresh loop
4. Implement keyboard navigation - j/k navigation, enter for details, filters
5. Add quick task creation - Modal for fast task input
6. Implement task actions - Edit, delete, complete, set parent/blocker

Phase 2: Planning Sessions

7. Create Claude bridge service - Wrap SDK, manage session lifecycle
8. Add session spawning UI - Prompt input, session start
9. Implement session streaming - Real-time output display
10. Add session sidebar - List active/completed sessions
11. Implement result actions - Create task, create plan from result
12. Add session persistence - Save/restore across TUI restarts

Phase 3: Polish

13. Add session templates - Pre-configured session types
14. Implement batch operations - Multi-select, bulk actions
15. Add cost tracking - Token usage display, budget alerts
16. Add session resume - Continue or fork previous sessions
17. Write documentation - Usage guide, keybinding reference

Configuration

# ~/.config/dex/dex.toml additions

[tui]
# Default model for planning sessions
default_model = "claude-sonnet-4"

# Auto-refresh interval (seconds)
refresh_interval = 5

# Maximum concurrent sessions
max_sessions = 3

[tui.keybindings]
# Customizable keybindings (defaults shown)
create = "c"
create_full = "C"
new_session = "n"
edit = "e"
delete = "d"
complete = "x"
toggle_pane = "Tab"

[tui.sessions]
# Default allowed tools for planning sessions
allowed_tools = ["Read", "Glob", "Grep", "WebSearch", "WebFetch"]

# Save session history
persist_sessions = true
session_history_limit = 50

Dependencies

{
  "dependencies": {
    "@zeeg/dex": "workspace:*",
    "@anthropic-ai/claude-agent-sdk": "^0.1.0",
    "ink": "^5.0.0",
    "ink-text-input": "^6.0.0",
    "react": "^18.0.0",
    "zustand": "^4.5.0",
    "nanoid": "^5.0.0"
  },
  "devDependencies": {
    "@types/react": "^18.0.0",
    "typescript": "^5.5.0"
  }
}

Open Questions

1. Web UI alternative? - Ink TUI is portable across terminals but a web UI would allow richer interactions. Could support both via shared state layer?

2. Session isolation - Should each planning session get its own working directory snapshot, or operate on live codebase?

3. Integration with main Claude Code session - Should TUI be able to observe/interact with the user's primary Claude Code session, or stay completely separate?

4. Notification system - When a background session completes, how to notify user without disrupting current focus? Sound? Flash? Status bar indicator?

Success Criteria

• User can view and manage dex backlog without leaving TUI
• User can spawn planning sessions with single keypress
• Sessions run in background while user continues other work
• Session results can be converted to dex tasks with one action
• TUI handles 10+ concurrent sessions without degradation
• Session state persists across TUI restart
• Total latency from keypress to visible response < 100ms

Task Tree

• Phase 3: Polish & Advanced Features 12azrz12
  • Add session templates 2lw2h1ov
  • Add cost tracking evsy5jvl
  • Implement session resume vndoc3if
  • Implement batch operations x2ihl7ug
  • Write documentation zp4sde9p
• Phase 2: Planning Sessions i8855dwx
  • Implement result actions 3jhepxak
  • Add session sidebar 9fk93vx6
  • Create Claude bridge service dse1q78b
  • Add session spawning UI f84c4mo3
  • Add session persistence il9uf6mr
  • Implement session streaming kcromkay
• Phase 1: Foundation zxw01uwg
  • Implement task actions 0czib63v
  • Add dex TaskService integration 3r32r2hb
  • Implement keyboard navigation 8uu695ws
  • Set up dex-tui package dac0b3nh
  • Add quick task creation i5vbce3u
  • Implement basic Ink app kgirg52i

Task Details

[ ] Phase 3: Polish & Advanced Features 12azrz12

Description

Add session templates, batch operations, cost tracking, session resume/fork capabilities, and comprehensive documentation.

[ ] ↳ Add session templates 2lw2h1ov

Description

Create pre-configured session types: Research (explore topic), Bug Analysis (investigate issue), Feature Plan (implementation plan), Refactor Scope (identify boundaries).

[ ] ↳ Add cost tracking evsy5jvl

Description

Display token usage per session, running total for TUI session, configurable budget alerts in status bar.

[ ] ↳ Implement session resume vndoc3if

Description

List previous sessions, resume with additional context, fork session for alternative exploration paths.

[ ] ↳ Implement batch operations x2ihl7ug

Description

Add Space key for multi-select, bulk complete/delete/re-parent operations on selected tasks.

[ ] ↳ Write documentation zp4sde9p

Description

Create usage guide, keybinding reference, configuration options, integration examples with dex workflow.

[ ] Phase 2: Planning Sessions i8855dwx

Description

Implement Claude Agent SDK integration for spawning read-only planning sessions, real-time streaming output, session management sidebar, and result-to-task conversion.

[ ] ↳ Implement result actions 3jhepxak

Description

Add 't' to create single task from result, 'P' to create full plan hierarchy, 'r' to re-run with follow-up, 's' to save to file.

[ ] ↳ Add session sidebar 9fk93vx6

Description

Create SessionList component showing active/completed sessions with status indicators, number key shortcuts (1-9), Tab to toggle focus.

[ ] ↳ Create Claude bridge service dse1q78b

Description

Wrap @anthropic-ai/claude-agent-sdk, implement runPlanningSession generator, manage session lifecycle and state.

[ ] ↳ Add session spawning UI f84c4mo3

Description

Implement 'n' key to open session prompt input, configure allowed tools (Read, Glob, Grep, WebSearch), spawn session in background.

[ ] ↳ Add session persistence il9uf6mr

Description

Implement session-store.ts to save/restore session state across TUI restarts using Claude session IDs for resume capability.

[ ] ↳ Implement session streaming kcromkay

Description

Display real-time output from planning sessions in detail pane, show progress indicators, handle errors gracefully.

[ ] Phase 1: Foundation zxw01uwg

Description

Set up the core TUI infrastructure including package structure, basic Ink app, dex integration, keyboard navigation, and task CRUD operations.

[ ] ↳ Implement task actions 0czib63v

Description

Add edit (e), delete with confirmation (d), mark complete (x), set parent (p), add blocker (b) actions on selected task.

[ ] ↳ Add dex TaskService integration 3r32r2hb

Description

Create useDex hook that wraps TaskService, implements refresh loop, provides CRUD operations for tasks.

[ ] ↳ Implement keyboard navigation 8uu695ws

Description

Add j/k arrow navigation, enter for details, filter shortcuts, useKeyboard hook for keybinding management.

[ ] ↳ Set up dex-tui package dac0b3nh

Description

Create package structure in packages/dex-tui, configure TypeScript build, add Ink and React dependencies, integrate into pnpm workspace.

[ ] ↳ Add quick task creation i5vbce3u

Description

Implement QuickCreate modal component with minimal input (c key), full create form (C key), ink-text-input integration.

[ ] ↳ Implement basic Ink app kgirg52i

Description

Create main App component with split-pane layout (task list + detail/session pane), StatusBar footer, and basic rendering loop.

[dcramer]

im gonna axe this