feat: add interactive TUI for browsing Claude Code sessions

Adds  (alias: ) command with ratatui-based terminal
interface for browsing and reading Claude Code session history.

Two-screen architecture:
- Session list: date, ID, message counts, title with ▸ selection
- Chat view: scrollable conversation with role headers, tool badges,
  word wrapping, and keyboard navigation

Dependencies: ratatui 0.29, crossterm 0.28
Includes workaround for rustc 1.95 ICE in check_mod_deathness.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Shahinyanm

Cargo.lock

@@ -36,6 +36,8 @@ tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 
 ureq = { version = "2", features = ["json"] }
+ratatui = "0.29"
+crossterm = "0.28"
 
 # Test deps
 assert_fs = "1"

Cargo.toml

@@ -25,6 +25,8 @@ serde_json = { workspace = true }
 ulid = { workspace = true }
 rusqlite = { workspace = true }
 chrono = { workspace = true }
+ratatui = { workspace = true }
+crossterm = { workspace = true }
 
 [dev-dependencies]
 assert_fs = { workspace = true }

crates/tj-cli/Cargo.toml

@@ -1,6 +1,8 @@
 use anyhow::Result;
 use clap::{Parser, Subcommand};
 
+mod tui;
+
 #[derive(Parser)]
 #[command(name = "task-journal", version, about = "Task Journal CLI", long_about = None)]
 struct Cli {
@@ -86,6 +88,13 @@ enum Commands {
     },
     /// Show local classifier and journal statistics.
     Stats,
+    /// Interactive TUI: browse sessions and read chats.
+    #[command(alias = "tui")]
+    Ui {
+        /// Project path override (default: current directory).
+        #[arg(long)]
+        project: Option<String>,
+    },
     /// Import task-journal events from existing Claude Code session history.
     /// Parses JSONL session files and creates tasks retroactively.
     Backfill {
@@ -573,6 +582,18 @@ fn main() -> Result<()> {
                 }
             }
         }
+        Commands::Ui { project } => {
+            let project_path = match project {
+                Some(p) => std::path::PathBuf::from(p),
+                None => std::env::current_dir()?,
+            };
+            let mut app = tui::app::App::new(&project_path)?;
+            if app.session_list.sessions.is_empty() {
+                eprintln!("No Claude Code sessions found for: {}", project_path.display());
+                return Ok(());
+            }
+            app.run()?;
+        }
         Commands::Backfill {
             dry_run,
             limit,

crates/tj-cli/src/main.rs

@@ -0,0 +1,181 @@
+//! Main TUI application — manages screens and terminal lifecycle.
+
+use anyhow::Result;
+use crossterm::{
+    event::{self, Event, KeyCode, KeyModifiers},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{backend::CrosstermBackend, Terminal};
+use std::io;
+use std::path::Path;
+use tj_core::session::{discovery, parser};
+
+use super::chat_view::ChatView;
+use super::session_list::SessionList;
+
+pub enum Screen {
+    List,
+    Chat,
+}
+
+pub struct App {
+    pub screen: Screen,
+    pub session_list: SessionList,
+    pub chat_view: Option<ChatView>,
+    pub should_quit: bool,
+}
+
+impl App {
+    pub fn new(project_path: &Path) -> Result<Self> {
+        let proj_dir = discovery::find_project_dir(project_path)?;
+        let sessions = match proj_dir {
+            Some(ref d) => discovery::list_sessions(d)?,
+            None => vec![],
+        };
+
+        // Parse session metadata (lightweight — just first user msg + timestamps).
+        let mut items = Vec::new();
+        for path in &sessions {
+            match parser::parse_session(path) {
+                Ok(parsed) => items.push(parsed),
+                Err(_) => continue,
+            }
+        }
+
+        Ok(App {
+            screen: Screen::List,
+            session_list: SessionList::new(items),
+            chat_view: None,
+            should_quit: false,
+        })
+    }
+
+    pub fn run(&mut self) -> Result<()> {
+        enable_raw_mode()?;
+        let mut stdout = io::stdout();
+        execute!(stdout, EnterAlternateScreen)?;
+        let backend = CrosstermBackend::new(stdout);
+        let mut terminal = Terminal::new(backend)?;
+
+        let result = self.main_loop(&mut terminal);
+
+        disable_raw_mode()?;
+        execute!(terminal.backend_mut(), LeaveAlternateScreen)?;
+        terminal.show_cursor()?;
+
+        result
+    }
+
+    fn main_loop(&mut self, terminal: &mut Terminal<CrosstermBackend<io::Stdout>>) -> Result<()> {
+        loop {
+            terminal.draw(|frame| {
+                match &self.screen {
+                    Screen::List => self.session_list.render(frame),
+                    Screen::Chat => {
+                        if let Some(ref cv) = self.chat_view {
+                            cv.render(frame);
+                        }
+                    }
+                }
+            })?;
+
+            if event::poll(std::time::Duration::from_millis(100))? {
+                if let Event::Key(key) = event::read()? {
+                    // Global: Ctrl+C or q quits.
+                    if key.modifiers.contains(KeyModifiers::CONTROL) && key.code == KeyCode::Char('c') {
+                        self.should_quit = true;
+                    }
+
+                    match &self.screen {
+                        Screen::List => self.handle_list_input(key.code),
+                        Screen::Chat => self.handle_chat_input(key.code),
+                    }
+                }
+            }
+
+            if self.should_quit {
+                break;
+            }
+        }
+        Ok(())
+    }
+
+    fn handle_list_input(&mut self, key: KeyCode) {
+        match key {
+            KeyCode::Char('q') | KeyCode::Esc => {
+                self.should_quit = true;
+            }
+            KeyCode::Up | KeyCode::Char('k') => {
+                self.session_list.previous();
+            }
+            KeyCode::Down | KeyCode::Char('j') => {
+                self.session_list.next();
+            }
+            KeyCode::Home => {
+                self.session_list.first();
+            }
+            KeyCode::End => {
+                self.session_list.last();
+            }
+            KeyCode::PageUp => {
+                for _ in 0..10 {
+                    self.session_list.previous();
+                }
+            }
+            KeyCode::PageDown => {
+                for _ in 0..10 {
+                    self.session_list.next();
+                }
+            }
+            KeyCode::Enter => {
+                if let Some(idx) = self.session_list.selected {
+                    let session = &self.session_list.sessions[idx];
+                    self.chat_view = Some(ChatView::from_session(session));
+                    self.screen = Screen::Chat;
+                }
+            }
+            _ => {}
+        }
+    }
+
+    fn handle_chat_input(&mut self, key: KeyCode) {
+        match key {
+            KeyCode::Char('q') | KeyCode::Esc | KeyCode::Backspace => {
+                self.screen = Screen::List;
+                self.chat_view = None;
+            }
+            KeyCode::Up | KeyCode::Char('k') => {
+                if let Some(ref mut cv) = self.chat_view {
+                    cv.scroll_up(1);
+                }
+            }
+            KeyCode::Down | KeyCode::Char('j') => {
+                if let Some(ref mut cv) = self.chat_view {
+                    cv.scroll_down(1);
+                }
+            }
+            KeyCode::PageUp => {
+                if let Some(ref mut cv) = self.chat_view {
+                    cv.scroll_up(20);
+                }
+            }
+            KeyCode::PageDown => {
+                if let Some(ref mut cv) = self.chat_view {
+                    cv.scroll_down(20);
+                }
+            }
+            KeyCode::Home => {
+                if let Some(ref mut cv) = self.chat_view {
+                    cv.scroll_top();
+                }
+            }
+            KeyCode::End => {
+                if let Some(ref mut cv) = self.chat_view {
+                    cv.scroll_bottom();
+                }
+            }
+            _ => {}
+        }
+    }
+}