{"id":31633357,"url":"https://github.com/LuRenJiasWorld/Claude-Code-Mailer","last_synced_at":"2025-10-07T00:03:20.812Z","repository":{"id":317200309,"uuid":"1066387109","full_name":"LuRenJiasWorld/Claude-Code-Mailer","owner":"LuRenJiasWorld","description":"📧 Never miss important Claude Code events again! Get instant email notifications when Claude needs your input,    finishes tasks, or runs into issues. Features smart templates, automatic Claude Code integration, and support for    Chinese (Simplified/Traditional) and English languages.","archived":false,"fork":false,"pushed_at":"2025-09-29T14:43:06.000Z","size":118,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-29T14:44:06.113Z","etag":null,"topics":["claude","claude-code","javascript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/claude-code-mailer","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LuRenJiasWorld.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-29T12:17:02.000Z","updated_at":"2025-09-29T14:43:09.000Z","dependencies_parsed_at":"2025-09-29T14:44:11.178Z","dependency_job_id":null,"html_url":"https://github.com/LuRenJiasWorld/Claude-Code-Mailer","commit_stats":null,"previous_names":["lurenjiasworld/claude-code-mailer"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/LuRenJiasWorld/Claude-Code-Mailer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuRenJiasWorld%2FClaude-Code-Mailer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuRenJiasWorld%2FClaude-Code-Mailer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuRenJiasWorld%2FClaude-Code-Mailer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuRenJiasWorld%2FClaude-Code-Mailer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LuRenJiasWorld","download_url":"https://codeload.github.com/LuRenJiasWorld/Claude-Code-Mailer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuRenJiasWorld%2FClaude-Code-Mailer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278698809,"owners_count":26030399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code","javascript"],"created_at":"2025-10-07T00:00:54.531Z","updated_at":"2025-10-07T00:03:20.794Z","avatar_url":"https://github.com/LuRenJiasWorld.png","language":"JavaScript","funding_links":[],"categories":["Project \u0026 Knowledge Management"],"sub_categories":["Other IDEs"],"readme":"# Claude Code Mailer\n\nA standalone email notification service for Claude Code, built with Node.js and Nodemailer.\n\n## Quick Start\n\nGet started in seconds with global installation:\n\n```bash\n# Install globally from npm\nnpm install -g claude-code-mailer\n\n# First run will create config file - edit it with your settings\nclaude-code-mailer test\n\n# Install Claude Code hooks\nclaude-code-mailer install\n\n# Send a test email\nclaude-code-mailer test\n```\n\nThat's it! You're ready to receive email notifications from Claude Code.\n\n## Configuration\n\nClaude Code Mailer supports flexible configuration with automatic config file creation.\n\n### Config File Locations\n\nThe tool automatically looks for configuration files in this order:\n\n1. **Environment Variables** (highest priority)\n2. **Project-level `.env`** file (in project root)\n3. **Global Config File** `~/.claude-code-mailer/.env` (created automatically)\n4. **Default Values** (lowest priority)\n\n### First Run Setup\n\nWhen you first run Claude Code Mailer, it will:\n\n1. Create a global config file at `~/.claude-code-mailer/.env`\n2. Ask you to edit it with your email settings\n3. Provide a template with all necessary configuration options\n\n### Configuration Options\n\n```env\n# SMTP Configuration\nSMTP_HOST=smtp.example.com\nSMTP_PORT=587\nSMTP_SECURE=false\nSMTP_USER=your-email@example.com\nSMTP_PASS=your-password\n\n# Email Settings\nFROM_EMAIL=your-email@example.com\nTO_EMAIL=recipient@example.com\nSUBJECT_PREFIX=[Claude Code]\n\n# Template Language (zh-CN, zh-HK, en)\nTEMPLATE_LANGUAGE=zh-CN\n\n# Retry Settings\nRETRY_ATTEMPTS=3\nRETRY_DELAY=1000\nTIMEOUT=10000\n```\n\n### Project-specific Configuration\n\nFor project-specific settings, create a `.env` file in your project root:\n\n```bash\n# Navigate to your project\ncd /path/to/your/project\n\n# Create project-specific .env file\necho \"TO_EMAIL=project-specific@example.com\" \u003e .env\necho \"TEMPLATE_LANGUAGE=en\" \u003e\u003e .env\n```\n\nProject-level configs override global settings but are overridden by environment variables.\n\n## Features\n\n- 🚀 Standalone Node.js project dedicated to email sending\n- 📧 Email sending via Nodemailer with SMTP support\n- 🔄 Retry mechanism for failed emails\n- 📝 Detailed logging and debugging\n- 🔧 Flexible configuration options\n- 🎯 CLI tool for easy integration\n- 📋 YAML template system with variable substitution and conditional rendering\n- 🏷️ Email subjects automatically include working directory name\n- ⏰ Timestamp formatting (HH:MM format)\n- 💬 Markdown quote format support\n- 🌍 Multilingual template support (Simplified Chinese, Traditional Chinese, English)\n\n## Installation\n\n### Local Development\n\n```bash\ncd /data/dev/claude-code-mailer\npnpm install\n```\n\n### Global Installation\n\nFor global usage with the `claude-code-mailer` command:\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd claude-code-mailer\n\n# Install dependencies\npnpm install\n\n# Install globally\nnpm install -g .\n```\n\nAfter global installation, you can use the CLI from anywhere:\n\n```bash\nclaude-code-mailer install    # Install Claude Code hooks\nclaude-code-mailer send       # Send email notification\nclaude-code-mailer test       # Send test email\nclaude-code-mailer verify     # Verify SMTP connection\nclaude-code-mailer uninstall  # Remove Claude Code hooks\n```\n\n## Configuration\n\n### Environment Variables\n\nCopy `.env.template` to `.env`:\n\n```bash\ncp .env.template .env\n```\n\nEdit `.env` file:\n\n```env\n# SMTP Configuration\nSMTP_HOST=smtp.example.com\nSMTP_PORT=587\nSMTP_SECURE=false\nSMTP_USER=your-email@example.com\nSMTP_PASS=your-password\n\n# Email Settings\nFROM_EMAIL=your-email@example.com\nTO_EMAIL=recipient@example.com\nSUBJECT_PREFIX=[Claude Code]\n\n# Template Language (zh-CN, zh-HK, en)\nTEMPLATE_LANGUAGE=zh-CN\n\n# Retry Settings\nRETRY_ATTEMPTS=3\nRETRY_DELAY=1000\nTIMEOUT=10000\n```\n\n### Multilingual Email Templates\n\nSet language in `.env` file:\n\n```env\nTEMPLATE_LANGUAGE=zh-CN  # Supports: zh-CN, zh-HK, en\n```\n\nEach language has its own template file:\n\n- `config/templates.zh-CN.yaml` - Simplified Chinese templates\n- `config/templates.zh-HK.yaml` - Traditional Chinese templates  \n- `config/templates.en.yaml` - English templates\n\n**Template file structure:**\n\n```yaml\n# config/templates.en.yaml\nsubjects:\n  Notification: \"Your attention needed\"\n  Stop: \"Task completed\"\n  Error: \"Error encountered\"\n\ncontent:\n  Notification: |\n    Current time is {{timestamp}} \n    \n    {{#if message}}\n    \u003e {{message}} \n    \n    {{/if}}Working directory: {{cwd}} \n    Session ID: {{sessionId}} \n    \n    Please open Claude Code terminal for details. \n\ndefaults:\n  subject: \"Notification\"\n  message: \"\"\n```\n\n**Supported languages:**\n- `zh-CN` - Simplified Chinese (default)\n- `zh-HK` - Traditional Chinese (Hong Kong)\n- `en` - English\n\n**Template variables:**\n- `{{timestamp}}` - Current time (HH:MM format)\n- `{{message}}` - Message content (wrapped in Markdown quote format)\n- `{{cwd}}` - Working directory\n- `{{sessionId}}` - Session ID\n- `{{error}}` - Error message\n- `{{warning}}` - Warning message\n\n**Conditional rendering:**\n- `{{#if variable}}content{{/if}}` - Only show content if variable exists\n\n## Usage\n\n### CLI Commands\n\nThe CLI can be used in two ways:\n\n#### Global Usage (after `npm install -g .`)\n```bash\n# Verify SMTP connection\nclaude-code-mailer verify\n\n# Send test email\nclaude-code-mailer test\n\n# Send notification email\nclaude-code-mailer send --event Notification --session test-session\n\n# Send custom email\nclaude-code-mailer custom --subject \"Test Email\" --message \"This is a test email\"\n\n# Show configuration\nclaude-code-mailer config\n\n# Install/Uninstall Claude Code hooks\nclaude-code-mailer install\nclaude-code-mailer uninstall\n```\n\n#### Local Development Usage\n```bash\n# Verify SMTP connection\nnode bin/claude-code-mailer.js verify\n\n# Send test email\nnode bin/claude-code-mailer.js test\n\n# Send notification email\n# Read JSON from stdin\necho '{\"hook_event_name\":\"Notification\",\"session_id\":\"test-session\"}' | node bin/claude-code-mailer.js send --stdin\n\n# Use command line arguments\nnode bin/claude-code-mailer.js send --event Notification --session test-session\n\n# Send custom email\nnode bin/claude-code-mailer.js custom --subject \"Test Email\" --message \"This is a test email\"\n\n# Show configuration\nnode bin/claude-code-mailer.js config\n\n# Install/Uninstall Claude Code hooks\nnode bin/claude-code-mailer.js install\nnode bin/claude-code-mailer.js uninstall\n```\n\n### Programming Interface\n\n```javascript\nconst ClaudeMailer = require('./src/index');\n\nconst mailer = new ClaudeMailer();\n\n// Send notification\nawait mailer.sendNotification('Notification', { sessionId: 'test-session' });\n\n// Send custom email\nawait mailer.sendCustomEmail({\n  subject: 'Custom Email',\n  text: 'Email content'\n});\n\n// Verify connection\nawait mailer.verifyConnection();\n```\n\n### Available Commands\n\nThe `claude-code-mailer` CLI supports the following commands:\n\n| Command | Description |\n|---------|-------------|\n| `send` | Send email notification (default command) |\n| `install` | Install Claude Code hooks automatically |\n| `uninstall` | Uninstall Claude Code hooks |\n| `test` | Send test email |\n| `verify` | Verify SMTP connection |\n| `config` | Show current configuration |\n| `custom` | Send custom email |\n| `help` | Show help information |\n\n### Global Installation Benefits\n\nWhen installed globally (`npm install -g .`), Claude Code Mailer provides:\n\n- **System-wide access**: Use `claude-code-mailer` from any directory\n- **Automatic path detection**: Intelligently finds installation location\n- **Unified CLI**: Single entry point for all functionality\n- **Backward compatibility**: All existing functionality preserved\n- **Easy integration**: Simple Claude Code hooks installation and management\n\n## Claude Code Integration\n\n### Automatic Installation\n\nUse the automatic installation script to configure Claude Code hooks:\n\n```bash\nnode bin/install-claude.js\n```\n\nThis script will:\n- 🎯 Automatically detect Claude Code Mailer installation directory\n- 🔧 Add Claude Code Mailer hooks to `~/.claude/settings.json`\n- 🛡️ Preserve existing configuration\n- 🚫 Prevent duplicate installations\n- 📊 Show installation summary\n\n### Manual Configuration\n\nIf you prefer manual configuration, add the following to `~/.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"Notification\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"node /data/dev/claude-code-mailer/bin/cli.js send --stdin\"\n          }\n        ]\n      }\n    ],\n    \"Stop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"node /data/dev/claude-code-mailer/bin/cli.js send --stdin\"\n          }\n        ]\n      }\n    ],\n    \"SubagentStop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"node /data/dev/claude-code-mailer/bin/cli.js send --stdin\"\n          }\n        ]\n      }\n    ],\n    \"Error\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"node /data/dev/claude-code-mailer/bin/cli.js send --stdin\"\n          }\n        ]\n      }\n    ],\n    \"Warning\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"node /data/dev/claude-code-mailer/bin/cli.js send --stdin\"\n          }\n        ]\n      }\n    ],\n    \"Info\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"node /data/dev/claude-code-mailer/bin/cli.js send --stdin\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### Supported Events\n\n- `Notification` - Claude needs your input or permission\n- `Stop` - Claude completed task\n- `SubagentStop` - Claude subtask completed\n- `Error` - Claude encountered error\n- `Warning` - Claude issued warning\n- `Info` - Claude information notification\n\n### Claude Code Provided Variables\n\n- `{{sessionId}}` - Current session ID\n- `{{cwd}}` - Current working directory\n- `{{message}}` - Notification message content\n- `{{transcript_path}}` - Session transcript file path\n\n### Email Format Features\n\n- Email subjects automatically include the last folder name from working directory\n- Timestamp shows only hours and minutes (e.g., 19:39)\n- Message content uses Markdown quote format (\u003e message)\n- Space added at end of each line to prevent email clients from joining lines\n\n## Logs\n\nLog file locations:\n- Regular logs: `~/.claude-code-mailer/mailer.log`\n- Error logs: `~/.claude-code-mailer/error.log`\n\n## Project Structure\n\n```\nclaude-code-mailer/\n├── src/\n│   ├── index.js          # Main entry point\n│   ├── mailer.js         # Email sending core\n│   ├── config-loader.js  # Configuration loader\n│   └── logger.js         # Logger\n├── bin/\n│   ├── cli.js            # CLI tool\n│   └── install-claude.js # Claude Code hooks installer\n├── config/\n│   ├── templates.zh-CN.yaml  # Simplified Chinese templates\n│   ├── templates.zh-HK.yaml  # Traditional Chinese templates\n│   └── templates.en.yaml      # English templates\n├── .env                  # Environment variables\n├── .env.template         # Environment template\n├── package.json\n├── pnpm-lock.yaml\n├── .gitignore\n├── README.md             # This file\n└── README.zh.md          # Chinese documentation\n```\n\n## Development and Maintenance\n\n### Adding new email templates\n\n1. Edit the corresponding language template file (e.g., `config/templates.zh-CN.yaml`)\n2. Add new subjects in `subjects` section\n3. Add corresponding content templates in `content` section\n4. Use `{{variable}}` syntax to reference variables\n5. Use `{{#if variable}}content{{/if}}` for conditional rendering\n\n### Adding new language support\n\n1. Create new template file in `config/` directory (e.g., `templates.ja.yaml`)\n2. Copy existing template structure and translate content\n3. Add new language option description in `.env.template`\n\n### Configuration Management\n\n- All configuration managed through environment variables (.env file)\n- No JSON configuration files used\n- Template system uses YAML format for maintainability\n\n### Email Format Optimizations\n\n- Timestamp: Shows only hours and minutes for better readability\n- Working directory: Automatically extracts last folder name to email subject\n- Message format: Uses Markdown quote format for emphasis\n- Line spacing: Space added at end of each line to prevent email client line joining\n- Multilingual support: Supports Simplified Chinese, Traditional Chinese (Hong Kong), and English templates\n- Independent language files: Each language has separate template files for easy maintenance and extension\n\n## Development\n\n### Run development mode\n```bash\npnpm dev\n```\n\n### Run tests\n```bash\npnpm test\n```\n\n## Troubleshooting\n\n### SMTP Connection Failed\n1. Check SMTP server configuration\n2. Verify username and password\n3. Check network connection\n4. View error logs\n\n### Email Sending Failed\n1. Verify recipient email address\n2. Check email content format\n3. View `~/.claude-code-mailer/error.log` logs\n\n### Permission Issues\n1. Ensure script has execute permission: `chmod +x bin/cli.js`\n2. Ensure log directory has write permission\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLuRenJiasWorld%2FClaude-Code-Mailer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLuRenJiasWorld%2FClaude-Code-Mailer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLuRenJiasWorld%2FClaude-Code-Mailer/lists"}