tuimail/CLAUDE.md

CLAUDE.md

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

Project Overview

tui_mail is a TUI email client built with Rust and Ratatui. It supports standard IMAP servers (including Gmail) and ProtonMail (via an in-process bridge). It displays inbox messages with a split-pane interface: email list on top, message preview on the bottom.

User documentation: see USAGE.md for setup instructions, keyboard shortcuts, and configuration reference.

Build and Run Commands

# Build the project (standard IMAP)
cargo build

# Run the application
cargo run

# Build/run with ProtonMail support
cargo build --features proton
cargo run --features proton

# 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

Main app (src/)

• 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, search, delete)
• src/connect.rs — IMAP connection handling (plain TCP and TLS)
• src/config.rs — Configuration loading from config.toml; provider selection (IMAP vs Proton)
• src/credentials.rs — OS keychain access via the keyring crate
• src/smtp.rs — Outgoing mail via SMTP using lettre
• src/setup.rs — First-run interactive setup wizard
• src/store.rs — Local encrypted body cache (AES-256-GCM, key stored in storage.key file)

ProtonMail bridge (proton-bridge/)

A separate workspace crate that runs as an in-process local IMAP/SMTP server.

• proton-bridge/src/lib.rs — Entry point (start()); authenticates with ProtonMail API, binds local ports, spawns async tasks
• proton-bridge/src/imap_server.rs — Local IMAP server (LOGIN, SELECT, FETCH, SEARCH, STORE, EXPUNGE)
• proton-bridge/src/smtp_server.rs — Local SMTP server for outgoing mail
• proton-bridge/src/api.rs — ProtonMail REST API client (message list, fetch, delete, send)
• proton-bridge/src/auth.rs — SRP authentication and session management
• proton-bridge/src/crypto.rs — PGP key derivation and message decryption/encryption
• proton-bridge/src/store.rs — In-memory message metadata store for the bridge
• proton-bridge/src/srp.rs — SRP-6a implementation matching ProtonMail's go-srp

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
• A navigation debounce (150 ms) avoids firing body fetches on every keypress while scrolling
• The worker checks wanted_body_seq (an AtomicU32) to drop stale body requests
• Body cache: fetched message bodies are AES-256-GCM encrypted and written to {data_dir}/tuimail/bodies/{hash}.enc; cache key is the Message-ID header value
• Credentials (IMAP/SMTP/Proton passwords) are stored in the OS keychain via keyring
• The encryption key for the body cache is stored in {data_dir}/tuimail/storage.key (mode 0600) to avoid repeated keychain prompts
• 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
• lettre (0.11): SMTP client for sending mail
• chrono (0.4): Date parsing and timezone conversion
• mailparse (0.15): MIME email parsing for body extraction
• aes-gcm (0.10): AES-256-GCM authenticated encryption for the body cache
• keyring (3): OS keychain access (apple-native / linux-native / windows-native)
• dirs (5): Platform-correct data directory paths

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
• proton-bridge/bridge.toml contains ProtonMail credentials and is gitignored
• The ProtonMail bridge imap_server SELECT response must not include UIDVALIDITY/UIDNEXT lines — imap-proto 0.10 (used by imap 2.4) does not fully consume them, causing tag desync on subsequent commands