If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/pimalaya/himalaya shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 12 active contributors
• MIT licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 88% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live pimalaya/himalaya repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pimalaya/himalaya.

What it runs against: a local clone of pimalaya/himalaya — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in pimalaya/himalaya | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pimalaya/himalaya. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pimalaya/himalaya.git
#   cd himalaya
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of pimalaya/himalaya and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "pimalaya/himalaya(\\.git)?\\b" \\
  && ok "origin remote is pimalaya/himalaya" \\
  || miss "origin remote is not pimalaya/himalaya (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/cli.rs" \\
  && ok "src/cli.rs" \\
  || miss "missing critical file: src/cli.rs"
test -f "src/config.rs" \\
  && ok "src/config.rs" \\
  || miss "missing critical file: src/config.rs"
test -f "src/account/config.rs" \\
  && ok "src/account/config.rs" \\
  || miss "missing critical file: src/account/config.rs"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/pimalaya/himalaya"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Himalaya is a Rust-based CLI tool for managing emails across multiple accounts via IMAP, Maildir, Notmuch backends, with SMTP/Sendmail sending, OAuth2 auth, PGP encryption, and JSON output. It solves the problem of managing email entirely from the terminal with native support for modern protocols and multi-backend flexibility. Modular feature-gated architecture: src/account/ handles multi-account config and CLI args; src/email/ organizes envelope operations (list, thread, flags); src/cli.rs is the clap-based command router; src/config.rs manages TOML-based config loading; feature flags in Cargo.toml gate backends (imap, maildir, notmuch, smtp, sendmail, oauth2, pgp-*) and delegation to external -lib crates (email-lib, mml-lib, pimalaya-tui).

Linux/Unix power users and sysadmins who prefer CLI-based email management without GUI overhead; developers integrating email workflows into terminal environments; users of privacy-focused or self-hosted mail servers wanting scriptable, headless email access.

Actively developed with v1.2.0 released, comprehensive feature set (imap, maildir, smtp, oauth2, pgp, wizard, sendmail), CI/CD via GitHub Actions (.github/workflows/releases.yml, release-on-demand.yml), and multi-platform distribution (Arch, Homebrew, Fedora, Nix). Production-ready for advanced users; widely packaged via Repology.

Single primary maintainer risk (Clément DOUIN listed as primary author). Heavy feature flag dependency (9+ conditional features in Cargo.toml) means incomplete testing of all combinations. Depends on email-lib, mml-lib, pimalaya-tui which are external crates that could introduce breaking changes. No visible test directory in top 60 files suggests test coverage may be sparse.

v1.2.0 is current; CI configured for on-demand and scheduled releases. Config wizard and multi-backend support are stable. OAuth2, PGP (via commands and native), and Notmuch are feature-complete. No specific branch/PR data visible, but .github/workflows suggest active release pipeline and likely ongoing maintenance.

git clone https://github.com/pimalaya/himalaya.git && cd himalaya && cargo build --release. Install via curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | sh. See config.sample.toml for setup; Nix users can use flake.nix or shell.nix; default Cargo features (imap, maildir, smtp, sendmail, wizard, pgp-commands) include most backends.

Daily commands: cargo run -- envelope list --account <name> (after config setup). CLI is command-driven: himalaya envelope list/thread, himalaya envelope flag add/remove, himalaya account list/doctor/configure (requires wizard feature for configure). Dev: cargo build for debug, cargo test for tests (if present), cargo build --release for optimized binary.

• src/main.rs — Entry point for the CLI application; defines the main command structure and orchestrates top-level argument parsing.
• src/cli.rs — Core CLI command definitions using a framework (likely clap); all commands and subcommands are defined here.
• src/config.rs — Configuration loading and management; handles account profiles and global settings that all commands depend on.
• src/account/config.rs — Account-level configuration schema; defines how mail backends (IMAP, maildir, SMTP) are configured.
• Cargo.toml — Project manifest with feature flags for optional backends (imap, maildir, smtp, sendmail, oauth2, pgp); critical for understanding build matrix.
• src/email/mod.rs — Root module for email operations; exports envelope and message submodules that handle the core email workflow.
• src/folder/mod.rs — Folder management operations (list, add, delete, expunge, purge); abstracts backend-specific folder handling.

• CLI Parser (src/cli.rs) (clap) — Validates and routes user input to appropriate command handlers
  • Failure mode: Invalid arguments → error message; missing required args → help text
• Config Manager (src/config.rs) (TOML, serde) — Loads and parses user configuration; validates account profiles
  • Failure mode: Missing config file → defaults or error; parse error → validation error with line number
• Account Manager (src/account/mod.rs) (email-lib (backend abstraction)) — Selects and initializes the appropriate backend (IMAP, maildir, etc.) for a given account
  • Failure mode: Invalid backend config → connection error; missing credentials → auth failure
• Envelope Handler (src/email/envelope/command/) (IMAP UID/FETCH, maildir metadata, notmuch queries) — Lists, threads, filters, and displays email headers and metadata
  • Failure mode: Backend unavailable → connection error; folder missing → not-found error
• Message Handler (src/email/message/command/) (email-lib message API, SMTP, template rendering) — Core business logic: read, compose, send, reply, forward, delete, move emails
  • Failure mode: Send fails → SMTP error; move fails → backend error; edit aborted → no-op
• Folder Manager (src/folder/command/) (IMAP CREATEFOLDER/DELETEFOLDER, maildir directory ops) — CRUD operations on folders (list, create, delete, expunge, purge)
  • Failure mode: Folder exists → duplicate error; insufficient perms → auth error

• User Shell → CLI Parser — Command-line arguments (account name, command, flags)
• CLI Parser → Config Manager — Account name to resolve credentials and backend type
• undefined → undefined — undefined

Add a new email message command

1. Define command struct with clap attributes in src/email/message/command/<command_name>.rs (src/email/message/command/<command_name>.rs)
2. Add command variant to the enum and import in src/email/message/command/mod.rs (src/email/message/command/mod.rs)
3. Wire command into CLI routing in src/cli.rs under email message subcommand (src/cli.rs)
4. Implement backend-specific logic using account context to call email-lib operations (src/email/message/command/<command_name>.rs)

Add support for a new email backend

1. Add feature flag and dependency to Cargo.toml (e.g., 'mybackend' feature) (Cargo.toml)
2. Define backend-specific account config fields in src/account/config.rs (src/account/config.rs)
3. Update account initialization logic to instantiate the new backend when selected (src/account/mod.rs)
4. Sample configuration in config.sample.toml documenting the new backend options (config.sample.toml)

Add a new folder command

1. Create command struct with clap attributes in src/folder/command/<command_name>.rs (src/folder/command/<command_name>.rs)
2. Add command variant to enum and export from src/folder/command/mod.rs (src/folder/command/mod.rs)
3. Add subcommand routing in src/cli.rs under the folder command branch (src/cli.rs)
4. Implement command logic using account backend's folder operations (src/folder/command/<command_name>.rs)

• Rust + clap for CLI — Type-safe, performant CLI with minimal dependencies; clap provides declarative argument parsing
• Modular backend features (IMAP, maildir, notmuch) — Users choose only needed backends at compile time; reduces binary size and dependencies
• TOML configuration files — Human-readable account and backend configuration; single source of truth for credentials and settings
• email-lib and pimalaya-tui as dependencies — Abstraction layer for backend-agnostic email operations; code reuse across CLI and TUI clients

• Compile-time feature flags for backends instead of runtime plugins

  • Why: Simpler implementation, type safety, zero-cost abstraction at runtime
  • Consequence: Users must recompile to add backends; cannot load arbitrary backends at runtime

• Single-threaded command execution per invocation

  • Why: CLI is stateless; each command is independent and short-lived
  • Consequence: Cannot maintain persistent connections; each command pays connection setup cost

• Account selection via --account flag rather than persistent state

  • Why: Stateless design; works well in scripting and piping
  • Consequence: Must specify account for every command; no 'current account' session state

• Real-time push notifications or background sync (is CLI, not daemon)
• Interactive GUI (separate TUI project; this is command-line only)
• Platform-specific backends (Windows-only or macOS-only features not prioritized)
• End-to-end encryption enforcement (PGP support optional via feature flag; not required)
• Distributed/cloud account aggregation (focuses on local multi-account management)

Feature flag combinations: not all feature subsets are tested; enabling non-default pgp backends (pgp-gpg, pgp-native) without pgp-commands may cause unintended behavior. Config file location: defaults to ~/.config/himalaya/config.toml on Linux; users must set up accounts before commands work, or commands fail silently. IMAP/Maildir/Notmuch are mutually exclusive per account in config but all feature-flags can coexist in binary. OAuth2 feature requires keyring feature, which depends on system keyring availability (can fail on headless servers). Email composition relies on $EDITOR env var; if unset or misconfigured, message composition fails. Async runtime: uses tokio; blocking operations in custom backends may deadlock.

• IMAP (Internet Message Access Protocol) — Himalaya's primary remote backend; understanding IMAP folder structure, flags, and envelope metadata is essential for implementing envelope operations.
• Maildir (mail directory format) — Native local email storage format supported by himalaya; critical for users self-hosting or using local-first workflows without IMAP servers.
• OAuth 2.0 Authorization Code Flow — Himalaya supports OAuth2 for services like Gmail and Outlook instead of storing passwords; understanding this flow is key for maintaining secure auth integrations.
• Cargo feature flags (conditional compilation) — Himalaya's entire architecture is built on feature gates (imap, maildir, smtp, pgp-*, etc.); understanding #[cfg(feature)] and dependency features is fundamental to modifying backends.
• Clap derive macros for CLI parsing — All commands and arguments use clap's derive API; critical for adding new CLI subcommands or modifying argument handling.
• MIME and SMTP protocol — Himalaya sends mail via SMTP and composes MIME messages; understanding these standards is necessary for email composition and sending features.
• PGP/GPG encryption and key management — Himalaya supports three PGP backends (shell commands, GPG bindings, native); understanding key ID formats and encryption workflows is essential for PGP feature development.

• pimalaya/pimalaya-tui — Companion TUI (terminal UI) implementation using same email-lib backend; users wanting interactive UI instead of pure CLI use this.
• pimalaya/email-lib — Core email abstraction library shared by both himalaya CLI and pimalaya-tui; all backend implementations (IMAP, Maildir, SMTP) live here.
• pimalaya/mml-lib — MIME/MML message composition and interpretation library used by himalaya for building and parsing emails.
• pimalaya/secret-lib — Secret/keyring management library optionally used by himalaya for OAuth2 credential storage.
• neomutt/neomutt — Alternative terminal-based email client with GUI; direct competitor solving similar email management problem but with a different UX paradigm (modal UI vs CLI commands).

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for email envelope commands (list, thread, flag operations)

The repo has comprehensive command implementations in src/email/envelope/command/ (list.rs, thread.rs) and src/email/envelope/flag/command/ (add.rs, remove.rs, set.rs) but no visible test files. Given this is a CLI tool managing critical email operations, integration tests would prevent regressions and validate the flag manipulation logic, especially since flags have add/remove/set variants that could have edge cases.

• [ ] Create tests/integration/envelope_commands.rs for envelope list and thread operations
• [ ] Create tests/integration/envelope_flags.rs testing flag add/remove/set operations with mock maildir/IMAP backends
• [ ] Add test fixtures in tests/fixtures/ for sample email envelopes
• [ ] Update Cargo.toml with [[test]] entries and ensure email-lib test features are enabled
• [ ] Reference existing src/email/envelope/command/ implementations to validate behavior

Add GitHub Actions workflow for cross-platform binary releases with feature matrix

The repo has release-on-demand.yml and releases.yml but they appear incomplete. Given the feature-rich Cargo.toml with optional features (imap, maildir, notmuch, oauth2, pgp-commands, pgp-native, etc.), there's no visible CI workflow that tests and builds all feature combinations. This would catch feature-gating bugs and provide users with pre-built binaries for different configurations.

• [ ] Audit existing .github/workflows/releases.yml to identify gaps in feature coverage
• [ ] Create .github/workflows/feature-matrix.yml with matrix build for [imap, maildir, smtp, oauth2, pgp-commands, pgp-native] on Linux/macOS/Windows
• [ ] Add workflow step to test: cargo test --no-default-features --features "<feature-combo>" for critical combinations
• [ ] Add artifact upload step to attach binaries to releases with feature flags in filename
• [ ] Document in CONTRIBUTING.md which feature combinations are officially tested

Implement argument validation and add unit tests for src/email/message/arg/ parsing modules

The src/email/message/arg/ directory has body.rs, header.rs, reply.rs and src/email/envelope/arg/ has ids.rs - these parse user input that could be malformed. No test files are visible for these arg modules. Adding validation tests would prevent parsing panics and ensure flags like --reply-to and --body handle edge cases (empty strings, special characters, malformed IDs).

• [ ] Create tests/unit/message_args.rs with test cases for src/email/message/arg/body.rs (empty body, unicode, very long bodies)
• [ ] Create tests/unit/envelope_args.rs with test cases for src/email/envelope/arg/ids.rs (invalid ID formats, range parsing)
• [ ] Add test cases for src/email/message/arg/reply.rs (verify reply-to address parsing)
• [ ] Add test cases for src/email/message/arg/header.rs (multiline headers, special characters)
• [ ] Update src/email/message/arg/mod.rs to expose internal parsing functions if they're currently private

• Add unit tests for src/account/config.rs account deserialization—currently no visible test files; test each backend (IMAP, Maildir, SMTP, Sendmail) config parsing with valid and invalid TOML.
• Document feature flag interactions in README.md—create a table showing which backends require which flags (e.g., oauth2 requires keyring) and which combinations are tested; currently users must infer from Cargo.toml.
• Implement envelope search/filter command in src/email/envelope/command/—currently only list, thread, and flag operations exist; add a search subcommand that accepts query patterns and filters by sender/subject/date.

The Himalaya email CLI project shows a generally sound security posture with proper use of Rust (memory-safety), no obvious hardcoded secrets, and structured dependency management. However, there are moderate concerns: an incomplete dependency declaration that needs verification, missing automated dependency vulnerability scanning in CI/CD, and the inclusion of a sample config file that requires careful review. The default feature set is broad, increasing attack surface. Low-priority issues include lack of documented security policy and missing transitive license verification. Recommended actions: complete the Cargo.toml configuration, integrate cargo-audit into workflows, audit config.sample.toml contents, and create a SECURITY.md policy file.

• Medium · Incomplete Dependency Configuration in Cargo.toml — Cargo.toml - [dependencies] section. The pimalaya-tui dependency declaration in the [dependencies] section appears to be truncated/incomplete (cut off mid-line). This could lead to unintended default features being enabled or disabled, potentially pulling in unvetted transitive dependencies or missing security-critical features. Fix: Complete the pimalaya-tui dependency declaration with explicit feature flags and version specification. Verify all transitive dependencies are audited.
• Medium · Missing Dependency Audit Configuration — .github/workflows/ (all files). No evidence of dependency auditing mechanisms (cargo-audit, cargo-deny) in the CI/CD pipeline or build configuration. The project handles sensitive email data but lacks automated vulnerability scanning for dependencies. Fix: Integrate 'cargo audit' or 'cargo-deny' into CI/CD pipeline. Add deny.toml configuration to explicitly audit and restrict dependencies.
• Medium · Sample Configuration File Included — config.sample.toml. The config.sample.toml file is distributed with the repository. While a sample config is useful, ensure it doesn't contain example credentials or sensitive information that could be misused or copied directly to production. Fix: Review config.sample.toml to ensure no example credentials, API keys, or sensitive defaults are included. Add prominent warnings in README about changing defaults before use.
• Low · No Security Policy Documented — Repository root. No visible SECURITY.md or security policy file for reporting vulnerabilities. Important for a security-sensitive application handling user emails. Fix: Create SECURITY.md with vulnerability disclosure policy, contact methods, and responsible disclosure guidelines.
• Low · Unrestricted Feature Compilation — Cargo.toml - [features] section. Multiple optional features (oauth2, pgp-commands, pgp-native, keyring) are enabled by default. This increases attack surface and dependency footprint. Users may not need all features. Fix: Consider reducing default feature set to minimal viable functionality. Document why each default feature is included. Allow users to opt-in to advanced features.
• Low · Missing SPDX License Verification — Cargo.toml - license field. While MIT license is specified, there's no verification mechanism for transitive dependency licenses. Could inadvertently include GPL or other copyleft licenses. Fix: Add license checking to CI/CD using tools like cargo-license or cargo-deny to ensure all transitive dependencies use compatible licenses.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.