Review and update README documentation by UserAd · Pull Request #24 · UserAd/AgentMail

UserAd · 2026-01-14T17:40:12Z

Summary by CodeRabbit

New Features
- Instant mailbox change detection with 60-second safety timer.
- Enhanced notifications for agents without recipient state tracking.
Documentation
- Updated README and plugin documentation to reflect behavior changes and storage updates.
Chores
- Storage paths moved from .git/ to .agentmail/ directory.
- Message ID format updated to 8-character base62.
- Go version requirement updated to 1.25.
- Added exit code for general errors.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

- Update Go version from 1.23 to 1.25 in README.md and CLAUDE.md to match actual go.mod (1.25.5) and CI configuration - Fix storage path references from .git/mail/ and .git/mail-recipients.jsonl to .agentmail/ and .agentmail/recipients.jsonl in main.go help text and claude-plugin/commands/status.md - Add missing UserPromptSubmit hook to plugin documentation table

- Replace outdated "monitors every 10 seconds" polling description with accurate file watching behavior (fsnotify with 500ms debounce) - Update fallback timer from 10s to correct 60s interval - Add documentation for stateless agent notification support - Update daemon system diagram to reflect actual implementation

SKILL.md fixes: - Change storage location from .git/mail/ to .agentmail/mailboxes/ - Fix message ID format from "6-character hex" to "8-character base62" - Remove non-existent Timestamp field from message format README.md fixes: - Clarify daemon uses safety timer alongside watching (not fallback) - Add missing exit code 1 for mailman errors

coderabbitai · 2026-01-14T17:40:24Z

📝 Walkthrough

Walkthrough

This pull request updates documentation and help text to reflect configuration changes across the agentmail system. Key updates include migrating file storage paths from .git/mail/* to .agentmail/*, refining message identification from hexadecimal to base62 format, documenting a transition from polling-based to filesystem-watching approach in mailman, expanding exit codes, and updating Go version references from 1.21 to 1.25 throughout documentation.

Changes

Cohort / File(s)	Summary
Mailman behavior and core functionality `README.md`	Documents transition from periodic polling (10-second intervals) to fsnotify-based filesystem watching with 500ms debounce and 60-second fallback timer; expands exit codes to include code 1 for general errors; extends notification behavior to stateless agents every 60 seconds if unread messages exist; updates Claude Code plugin documentation with new event mappings (SessionEnd replaced with UserPromptSubmit).
Plugin documentation and skill definitions `claude-plugin/commands/status.md`, `claude-plugin/skills/agentmail/SKILL.md`	Updates storage location references from `.git/mail-recipients.jsonl` and `.git/mail/` to `.agentmail/recipients.jsonl` and `.agentmail/mailboxes/`; refines message identifier format from 6-character hexadecimal to 8-character base62 encoding (a–z, A–Z, 0–9).
CLI help text and user-facing documentation `cmd/agentmail/main.go`	Updates help text and example messages to reference new `.agentmail/` storage paths instead of `.git/mail/` locations.
CI and testing documentation `CLAUDE.md`	Updates Go Docker container version from 1.21 to 1.25 in CI testing documentation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title mentions README documentation but the PR includes significant changes beyond README: CLAUDE.md, multiple files in claude-plugin/, and cmd/agentmail/main.go with functional behavior updates.	Update the title to reflect the broader scope of changes, such as 'Update documentation and file paths for agentmail migration to .agentmail/ directory' or 'Migrate storage paths and update documentation for filesystem watching'.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

📜 Recent review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2a3580a and 226689d.

📒 Files selected for processing (5)

CLAUDE.md
README.md
claude-plugin/commands/status.md
claude-plugin/skills/agentmail/SKILL.md
cmd/agentmail/main.go

🧰 Additional context used

📓 Path-based instructions (1)

**/*.go

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.go: Must use Go 1.21+ with Standard library only (os/exec for tmux, encoding/json for JSONL) for agent mail structure
Store messages in JSONL format in .agentmail/mailboxes/<recipient>.jsonl with file locking for atomic operations
Build system must pass go vet ./... without errors
Build system must pass go fmt ./... without errors
Build system must pass govulncheck ./... without errors
Build system must pass gosec ./... without errors
Use Go standard library only (os, filepath, syscall, encoding/json) for storage restructuring without external dependencies
Use Go standard library only (time, sync) for stale agent detection tracking
MCP server implementation must use Go 1.23+ with github.com/modelcontextprotocol/go-sdk official SDK and STDIO transport

Files:

cmd/agentmail/main.go

🧠 Learnings (12)

📓 Common learnings

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-14T09:13:13.503Z
Learning: Applies to **/*.go : Must use Go 1.21+ with Standard library only (os/exec for tmux, encoding/json for JSONL) for agent mail structure

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-14T09:13:13.503Z
Learning: Applies to **/*.go : Store messages in JSONL format in `.agentmail/mailboxes/<recipient>.jsonl` with file locking for atomic operations

Learnt from: CR
Repo: UserAd/AgentMail PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-14T09:13:13.503Z
Learning: The build system shall produce agentmail binary