8826f3bc95
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>
78 lines
2.5 KiB
Markdown
78 lines
2.5 KiB
Markdown
# 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`](USAGE.md) for setup instructions, keyboard shortcuts, and configuration reference.
|
|
|
|
## Build and Run Commands
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|