aimx: Instructions file for Claude Code

CLAUDE.md

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

What is aimx

Self-hosted email for AI agents. One binary, one setup command. Built-in SMTP server handles inbound. Direct SMTP delivery for outbound. aimx handles everything: ingest to Markdown, DKIM signing, MCP server, hooks (on_receive / after_send). aimx serve is the SMTP daemon. All other commands are short-lived processes.

Build and test commands

# Build
cargo build
cargo build --release

# Install locally
cargo build --release && sudo cp target/release/aimx /usr/local/bin/

# Tests (all unit + integration)
cargo test

# Single test
cargo test test_name
cargo test -- --exact module::tests::test_name

# Lint
cargo clippy -- -D warnings
cargo fmt -- --check

# Format
cargo fmt

Verifier service (separate Rust crate)

cd services/verifier
cargo build
cargo test
cargo clippy -- -D warnings
cargo fmt -- --check

CI runs both crates independently (.github/workflows/ci.yml).

Test environment escape hatches

A handful of CLI gating points refuse to run as non-root in production. The test suite injects an opt-in to keep the post-gate code paths exercised under a non-root cargo test runner. Set this only from the test harness:

• AIMX_TEST_SKIP_AUTHZ_CHECK=1 — bypasses the authorize() call (gating Action::HookCrud) in aimx hooks --cmd raw-shell paths so the rest of the command (config writes, fallback hints, error formatting) stays reachable without sudo. Read by src/hooks.rs only — mailbox CRUD authz is enforced server-side over UDS and never consults this env var. Production callers must never set this — it neutralizes the authz predicate by design.

Other test-only env vars are documented next to their read sites: AIMX_SANDBOX_FORCE_FALLBACK (force the non-systemd-run hook executor), AIMX_CONFIG_DIR / AIMX_DATA_DIR (redirect config + storage paths), AIMX_TEST_MAIL_DROP (use the file-drop transport instead of MX delivery), AIMX_INTEGRATION_SUDO=1 (opt the integration suite into the root-only MAILBOX-CRUD branch when the test runner has sudo).