tuimail/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Skim is a TUI email client built with Rust and Ratatui. It connects to IMAP servers (including Gmail) and displays inbox messages with a split-pane interface: email list on top, message preview on the bottom.

Build and Run Commands

# Build the project
cargo build

# Run the application
cargo run

# Build optimized release version
cargo build --release

# Check code without building
cargo check

# Format code
cargo fmt

# Run clippy linter
cargo clippy

Test Mail Server

A Docker-based IMAP mail server is available for testing:

# Start the mail server
docker-compose up -d

# Create a test user
docker exec -it mailserver setup email add test@example.com password123

# Stop the mail server
docker-compose down

Connection details: localhost:143 (IMAP) or localhost:993 (IMAPS). See MAIL_SERVER_SETUP.md for detailed usage including Gmail configuration.

Architecture

• src/main.rs — Terminal setup/teardown, delegates to lib::main
• src/lib.rs — Main event loop, UI rendering, worker thread coordination
• src/inbox.rs — IMAP inbox operations (refresh, fetch older, fetch body)
• src/connect.rs — IMAP connection handling (plain TCP and TLS)
• src/config.rs — Configuration loading from config.toml

Key patterns

• IMAP operations run in a background worker thread communicating via mpsc channels, keeping the UI responsive
• Emails are loaded in batches of 50, with lazy loading when scrolling past the end
• Tab switches focus between inbox list and preview pane
• Selection is preserved across refreshes by matching IMAP sequence numbers

Key Dependencies

• ratatui (0.30): TUI framework providing widgets, layouts, and rendering
• crossterm (0.29): Cross-platform terminal manipulation (raw mode, events, alternate screen)
• imap (2.4): IMAP protocol client
• native-tls (0.2): TLS support for secure IMAP connections (Gmail)
• chrono (0.4): Date parsing and timezone conversion

Development Notes

• Uses Rust edition 2024
• Terminal is set to raw mode to capture individual key presses
• The alternate screen prevents terminal history pollution
• config.toml contains credentials and is gitignored — see config.toml.example for the format