From 8df0eb18622e1162ea57cd9f322c915ba58ae945 Mon Sep 17 00:00:00 2001 From: Konstantin Tumalevich Date: Sun, 18 Jan 2026 09:30:38 +0500 Subject: [PATCH 1/2] docs: add cleanup command documentation and update spec status - Add cleanup command documentation to README.md with full usage examples - Add cleanup utility to Features list in README.md - Update specs/011-cleanup/spec.md status from Draft to Implemented - Add reminder to CLAUDE.md about updating README after spec implementation --- CLAUDE.md | 2 ++ README.md | 46 +++++++++++++++++++++++++++++++++++++++ specs/011-cleanup/spec.md | 2 +- 3 files changed, 49 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 74fc735..a4e4794 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -78,6 +78,8 @@ This project uses speckit for feature specification and planning. Available comm Templates are stored in `.specify/templates/` and project constitution in `.specify/memory/constitution.md`. +**Important:** After implementing a spec, always update `README.md` to reflect the new functionality. + ## Active Technologies - Go 1.21+ (per IC-001) + Standard library only (os/exec for tmux, encoding/json for JSONL) (001-agent-mail-structure) - JSONL file in `.agentmail/` directory (001-agent-mail-structure) diff --git a/README.md b/README.md index 2e2dd9f..1148aaf 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ A Go CLI tool for inter-agent communication within tmux sessions. Agents running - **Agent status tracking** - Agents can set status (ready/work/offline) for smart notifications - **MCP server** - Model Context Protocol server for Claude Code, Codex CLI, and Gemini CLI - **Claude Code integration** - Plugin and hooks for AI agent orchestration +- **Cleanup utility** - Remove stale recipients, old messages, and empty mailboxes ## Requirements @@ -257,6 +258,51 @@ This command outputs a quick reference for AI agents to understand AgentMail's c **Exit codes:** - `0` - Success +### cleanup + +Remove stale data from the AgentMail system. + +```bash +agentmail cleanup [flags] +``` + +**What gets cleaned:** +- **Offline recipients** - Entries in recipients.jsonl for tmux windows that no longer exist +- **Stale recipients** - Recipients not updated within the threshold (default: 48 hours) +- **Old delivered messages** - Read messages older than the threshold (default: 2 hours) +- **Empty mailboxes** - Mailbox files with zero messages + +**Flags:** +- `--stale-hours ` - Hours threshold for stale recipients (default: 48) +- `--delivered-hours ` - Hours threshold for delivered messages (default: 2) +- `--dry-run` - Report what would be cleaned without deleting + +**Examples:** +```bash +# Preview what would be cleaned +agentmail cleanup --dry-run + +# Clean with default thresholds (48h stale, 2h delivered) +agentmail cleanup + +# Clean with custom thresholds +agentmail cleanup --stale-hours 24 --delivered-hours 1 +``` + +**Output:** +``` +Cleanup complete: + Recipients removed: 3 (2 offline, 1 stale) + Messages removed: 15 + Mailboxes removed: 2 +``` + +**Exit codes:** +- `0` - Success +- `1` - Error during cleanup + +**Note:** This is an administrative command not intended for AI agent use. It is not exposed via MCP tools or onboarding. + ### help Display usage information. diff --git a/specs/011-cleanup/spec.md b/specs/011-cleanup/spec.md index 6e300a2..432c05e 100644 --- a/specs/011-cleanup/spec.md +++ b/specs/011-cleanup/spec.md @@ -2,7 +2,7 @@ **Feature Branch**: `011-cleanup` **Created**: 2026-01-15 -**Status**: Draft +**Status**: Implemented **Input**: User description: "I want to have ability to cleanup old recipients/messages/mailboxes." ## Clarifications From 78a72021dfad08b4befaf5b46eb75145f3d1b757 Mon Sep 17 00:00:00 2001 From: Konstantin Tumalevich Date: Sun, 18 Jan 2026 09:40:45 +0500 Subject: [PATCH 2/2] fix: resolve markdownlint issues in README.md - Add .markdownlint.json config to disable MD013 (line length) rule - Add blank lines around lists and fenced code blocks (MD031, MD032) - Add language specifiers to code blocks (MD040) - Fix table column spacing (MD060) - Fix link fragment to match actual heading (MD051) - Rename duplicate "How It Works" heading to "Architecture" (MD024) --- .markdownlint.json | 6 +++++ README.md | 57 ++++++++++++++++++++++++++++++++++------------ 2 files changed, 48 insertions(+), 15 deletions(-) create mode 100644 .markdownlint.json diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..ef592cf --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,6 @@ +{ + "MD013": false, + "MD024": { + "siblings_only": true + } +} diff --git a/README.md b/README.md index 1148aaf..31a0743 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,7 @@ brew install agentmail Download the latest binary for your platform from the [Releases](https://github.com/UserAd/AgentMail/releases) page. Available platforms: + - Linux (amd64, arm64) - macOS (amd64, arm64) @@ -100,16 +101,19 @@ agentmail send [flags] [] [] ``` **Arguments (positional or flags):** + - `` - Target tmux window name (required) - `` - Message content (optional if using stdin) **Flags:** + - `-r, --recipient ` - Recipient tmux window name - `-m, --message ` - Message content Flags take precedence over positional arguments. **Examples:** + ```bash # Send with positional arguments agentmail send agent-2 "Task completed successfully" @@ -127,6 +131,7 @@ cat report.txt | agentmail send agent-2 ``` **Exit codes:** + - `0` - Message sent successfully - `1` - Error (invalid recipient, missing message, etc.) - `2` - Not running inside tmux @@ -140,10 +145,12 @@ agentmail receive [--hook] ``` **Flags:** -- `--hook` - Enable hook mode for Claude Code integration (see [Claude Code Hooks](#claude-code-hooks)) + +- `--hook` - Enable hook mode for Claude Code integration (see [Claude Code Hooks](#claude-code-hooks-manual-setup)) **Output format (normal mode):** -``` + +```text From: ID: @@ -153,11 +160,13 @@ ID: Returns "No unread messages" if the mailbox is empty. **Exit codes (normal mode):** + - `0` - Success (message displayed or no messages) - `1` - Error reading mailbox - `2` - Not running inside tmux **Exit codes (hook mode):** + - `0` - No messages, not in tmux, or error (silent) - `2` - New message available (output to STDERR) @@ -170,7 +179,8 @@ agentmail recipients ``` **Example output:** -``` + +```text agent-1 [you] agent-2 agent-3 @@ -179,6 +189,7 @@ agent-3 The current window is marked with `[you]`. **Exit codes:** + - `0` - Success - `1` - Error listing windows - `2` - Not running inside tmux @@ -192,11 +203,13 @@ agentmail status ``` **Statuses:** + - `ready` - Available to receive notifications (daemon will alert you of new mail) - `work` - Busy working (notifications suppressed until you return to ready) - `offline` - Not available (notifications suppressed) **Examples:** + ```bash # Mark yourself as ready to receive notifications agentmail status ready @@ -209,6 +222,7 @@ agentmail status offline ``` **Exit codes:** + - `0` - Status updated successfully - `1` - Invalid status value @@ -221,9 +235,11 @@ agentmail mailman [--daemon] ``` **Flags:** + - `--daemon` - Run in background (daemonize) **Behavior:** + - Uses file watching (fsnotify) for instant notification on mailbox changes - Includes 60-second safety timer that runs alongside watching - Sends notifications to agents with `ready` status that have unread mail @@ -232,6 +248,7 @@ agentmail mailman [--daemon] - Gracefully shuts down on SIGTERM/SIGINT **Examples:** + ```bash # Run in foreground (useful for debugging) agentmail mailman @@ -241,6 +258,7 @@ agentmail mailman --daemon ``` **Exit codes:** + - `0` - Daemon started/stopped successfully - `1` - Error (failed to start, PID file error, etc.) - `2` - Daemon already running @@ -256,6 +274,7 @@ agentmail onboard This command outputs a quick reference for AI agents to understand AgentMail's capabilities. Used by Claude Code SessionStart hooks for agent initialization. **Exit codes:** + - `0` - Success ### cleanup @@ -267,17 +286,20 @@ agentmail cleanup [flags] ``` **What gets cleaned:** + - **Offline recipients** - Entries in recipients.jsonl for tmux windows that no longer exist - **Stale recipients** - Recipients not updated within the threshold (default: 48 hours) - **Old delivered messages** - Read messages older than the threshold (default: 2 hours) - **Empty mailboxes** - Mailbox files with zero messages **Flags:** + - `--stale-hours ` - Hours threshold for stale recipients (default: 48) - `--delivered-hours ` - Hours threshold for delivered messages (default: 2) - `--dry-run` - Report what would be cleaned without deleting **Examples:** + ```bash # Preview what would be cleaned agentmail cleanup --dry-run @@ -290,7 +312,8 @@ agentmail cleanup --stale-hours 24 --delivered-hours 1 ``` **Output:** -``` + +```text Cleanup complete: Recipients removed: 3 (2 offline, 1 stale) Messages removed: 15 @@ -298,6 +321,7 @@ Cleanup complete: ``` **Exit codes:** + - `0` - Success - `1` - Error during cleanup @@ -335,7 +359,7 @@ monitoring AgentMail includes a built-in MCP (Model Context Protocol) server that enables AI agents to communicate via a standardized interface. The MCP server exposes four tools: | Tool | Description | -|------|-------------| +| ---- | ----------- | | `send` | Send a message to another agent (max 64KB) | | `receive` | Receive the oldest unread message (FIFO) | | `status` | Set agent availability (ready/work/offline) | @@ -464,7 +488,7 @@ git clone https://github.com/UserAd/AgentMail.git The plugin configures hooks that automatically: | Event | Action | Status | -|-------|--------|--------| +| ----- | ------ | ------ | | **SessionStart** | Sets status to ready, runs onboarding | `ready` | | **UserPromptSubmit** | Sets status to work (agent is busy) | `work` | | **Stop** (end of turn) | Sets status to ready, checks for messages | `ready` | @@ -541,7 +565,7 @@ Add to your Claude Code settings (`.claude/settings.json` in your project or `~/ ### How It Works | Hook Event | Command | Purpose | -|------------|---------|---------| +| ---------- | ------- | ------- | | **SessionStart** | `agentmail status ready && agentmail onboard` | Sets agent ready, outputs onboarding context | | **SessionEnd** | `agentmail status offline` | Marks agent as offline when session ends | | **Stop** | `agentmail status ready && agentmail receive --hook` | Sets ready after each turn, checks for mail | @@ -550,7 +574,7 @@ Add to your Claude Code settings (`.claude/settings.json` in your project or `~/ ### Hook Mode Behavior (`--hook` flag) | Condition | Output | Exit Code | -|-----------|--------|-----------| +| --------- | ------ | --------- | | Unread messages exist | Message to STDERR with "You got new mail" | 2 | | No unread messages | None | 0 | | Not in tmux session | None | 0 | @@ -562,7 +586,7 @@ Hook mode is designed to be non-disruptive: errors exit silently rather than int When you have mail (on Stop hook), Claude Code will display: -``` +```text You got new mail From: agent-1 ID: xK7mN2pQ @@ -570,11 +594,9 @@ ID: xK7mN2pQ Task completed! Results are in /tmp/output.json ``` -## How It Works +## Architecture -### Architecture - -``` +```text ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ agent-1 │ │ agent-2 │ │ agent-3 │ │ (tmux win) │ │ (tmux win) │ │ (tmux win) │ @@ -613,7 +635,7 @@ AgentMail uses POSIX file locking (`flock`) to ensure atomic read-modify-write o The mailman daemon provides proactive notifications for agents: -``` +```text ┌─────────────────────────────────────────────────────────────┐ │ Mailman Daemon │ │ │ @@ -628,12 +650,14 @@ The mailman daemon provides proactive notifications for agents: ``` **Recipient State File** (`.agentmail/recipients.jsonl`): + ```json {"recipient":"agent-1","status":"ready","updated_at":"2024-01-12T10:00:00Z","notified":false} {"recipient":"agent-2","status":"work","updated_at":"2024-01-12T10:05:00Z","notified":false} ``` **Notification Flow:** + 1. Agent sets status to `ready` using `agentmail status ready` 2. Mailman daemon detects unread messages for agent 3. Daemon sends notification via tmux: `Check your agentmail` @@ -695,6 +719,7 @@ docker run --rm -v $(pwd):/app -w /app golang:1.25.5 go test -v -race ./... The project uses GitHub Actions for continuous integration and delivery: **Test Workflow** (on push to main and PRs): + - Code formatting verification (`gofmt`) - Dependency verification (`go mod verify`) - Static analysis (`go vet`) @@ -703,6 +728,7 @@ The project uses GitHub Actions for continuous integration and delivery: - Security scanning (`govulncheck`, `gosec`) **Release Workflow** (on push to main): + - Pre-release test validation - Semantic version calculation from commit messages - Cross-platform builds (Linux/macOS, amd64/arm64) @@ -711,7 +737,7 @@ The project uses GitHub Actions for continuous integration and delivery: ## Project Structure -``` +```text AgentMail/ ├── cmd/ │ └── agentmail/ # CLI entry point @@ -755,6 +781,7 @@ AgentMail includes several security measures: 5. Open a Pull Request Please ensure: + - Code passes `go fmt` and `go vet` - Tests pass with `go test -race ./...` - New features include appropriate tests