# 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

```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