Shautvast 8826f3bc95 Add USAGE.md user documentation and link from CLAUDE.md

Covers setup (config.toml, provider settings, Gmail app passwords),
the split-pane UI, full keyboard reference, compose/reply workflow,
auto-refresh behaviour, and a config field reference.

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

2026-02-24 18:33:50 +01:00

2.5 KiB

Raw Blame History

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 connects to IMAP servers (including Gmail) and 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
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

2.5 KiB Raw Blame History