Email in. Work out. The Ultimate AI Agent for Email Lovers!
A local-first AI Agent that uses email as its default interactive entry point and subjects as project boundaries.
Create tasks and scheduled automation in 5 simple steps:
- Get OTP: Send an email to
otp@emailclaw.emailto get a one-time password. - Configure: Enter your registration email and OTP in Emailclaw settings. You'll receive your Agent Email (e.g.,
YOUR-AGENT@emailclaw.email). - Send Task: Send your task to the Agent Email (e.g., "Please tell me the latest global AI technology news").
- Confirm: Reply to the confirmation email with the TaskId to start the work. You will receive the task results.
- Schedule: Reply to the thread to convert it (e.g., "Please convert this task into a scheduled task, with the runtime hours set to 7, 12, 17 and 23"). Emailclaw will automatically run it for
When an email is received, a projectId is explicitly passed to the Agent, forcing its sandbox and file tools to bind to a dedicated
projects/<projectId> directory.
- Task Submission: User sends an email with a new subject and 3 markdown attachments, requesting an analysis.
- Initialization: Emailclaw creates a new project based on the "New subject, new project" rule. User confirms.
- Agent Execution: The Agent analyzes the materials, generates the result, and replies with the new markdown file attached.
- Physical Isolation: On the file system, all 3 user files and the 1 generated file are securely stored in the project's exclusive directory, completely isolated from other projects.
Emailclaw puts AI Agents into an inbox everyone is familiar with. It doesn't treat email as just another chat channel, but rather treats the email subject as a clear boundary for a specific task:
New Subject, New Project.
A new subject email without a valid TaskId will create an independent task session, a project record, and a project directory. The system replies with an email attaching a TaskId; once the user replies directly to this email, subsequent messages, attachments, and Agent work will stay within the same task. To start a different piece of work, simply write a new subject.
This makes Emailclaw especially suitable for email lovers and those who need to maintain clear contextual boundaries between research, writing, code review, reporting, customer replies, and automated tasks.
- Email-first : Uses IMAP to receive tasks and SMTP to return results. No need to learn or migrate to new instant chat apps.
- Subject-level Project Isolation : New Subject, New Project; TaskId binds email threads, session history, and project directories.
- Local-first : Configurations, projects, sessions, attachments, workspaces, logs, and plugins are saved on machines you control.
- Controlled Agent Actions : Models, tools, Skills, MCP, cron jobs, and plugins can be composed; high-risk tool calls can be approved via a 4-digit confirmation code in email.
- Suitable for Long-running : Supports Linux headless service mode, boot startup, Cron automation, and log troubleshooting.
- Extensible : Based on Java SPI and external JAR plugins; extensible for tools, Providers, hooks, MCP, UI, and channels.
- Powered by AgentScope Java : Utilizes AgentScope Java 2.0's Agent, model, event, tool, permission, and Harness capabilities.
Your Inbox
│ Send a new subject email
▼
Emailclaw Channel
│ Creates session + project, replies with TaskId
▼
Reply to the same email (keeping TaskId)
│
▼
Agent reasons in an isolated workspace, calls controlled tools, generates results
│
▼
Results, attachments, or approval requests return to the original email thread
The first new subject email is used to establish a stable task boundary; it will not immediately trigger a model call. Please reply to Emailclaw's response email and keep the complete TaskId at the end of the subject.
The release process builds desktop installation packages for the following platforms. Please visit https://github.com/emailclaw/emailclaw/releases/ to download the latest version installation package:
| Platform | Asset Type | Installation Method |
|---|---|---|
| Windows | .exe |
Double-click to install after down, and follow the setup wizard |
| macOS | .dmg |
Open the disk image and drag the application to the "Applications" folder |
| Linux Portable Deployment | .tar.gz |
Execute mkdir -p ~/.local/ && cd ~/.local/ && wget https://github.com/emailclaw/emailclaw/releases/latest/download/emailclaw-linux-latest.tar.gz && tar -xzf emailclaw-linux-latest.tar.gz -C ~/.local/ --no-same-owner . LaunchEmailclaw by running~/.local/emailclaw/bin/emailclaw |
| Debian/Ubuntu Linux | .deb |
Execute wget https://github.com/emailclaw/emailclaw/releases/latest/download/emailclaw-linux-latest.deb && sudo apt install ./emailclaw-linux-latest.deb . LaunchEmailclaw from the application menu or by running/opt/emailclaw/bin/emailclaw |
After launching the desktop application:
- In Providers , add the Base URL, API Key, and model ID of the model service.
- In Agents , create or select a default Agent, and choose the model and system prompt.
- It is recommended to send a simple message in local chat first to verify the model credentials and network availability.
Click Emailclaw Settings to open the configuration page. You can use your own email, or follow the interface instructions to register if the system-provided email function is available and you are authorized.
Fill in the following items:
- Email Address : The email address used by Emailclaw to send and receive tasks.
- Email Password : App-specific password, authorization code, or the credentials required by the email service.
- IMAP Host / Port / SSL / STARTTLS : Incoming mail server parameters.
- SMTP Host / Port / SSL / STARTTLS : Outgoing mail server parameters.
- Poll Interval : Inbox polling interval, minimum 5 seconds, default 30 seconds.
- Allowed Senders : Email addresses allowed to send tasks to the Agent, one per line.
Common addresses like Gmail, Outlook, iCloud, 163, 126, QQ, Foxmail, Yahoo, etc., will automatically match preset parameters. If your service provider is not among the presets, please query your service provider for IMAP/SMTP parameters and fill them in manually.
After saving the configuration, enable Emailclaw on the channels page. The system will start polling the mailbox in the background. It is strongly recommended to only add addresses you trust to the allowed senders list.
The prerequisite is that you have sent an email to otp@emailclaw.email to obtain a one-time password, and you fully agree to the Emailclaw Channel Service Agreement:
- The Service Provider reserves all rights, and may suspend or change the terms of this agreement at any time without prior notice.
- The Service Provider provides no quality guarantee for the services provided. The Service Provider shall not be held liable for any direct or indirect damages arising from the use of this service.
- The Emailclaw Channel only provides email channel services, and does not provide email storage services. All sent or received emails will be completely and irrecoverably deleted from the server after 15 minutes.
- If a user registers for the Emailclaw Channel service provided by the system but does not use the service for more than 100 consecutive days, the Service Provider will delete the user's service.
- By using this service, you agree to comply with all applicable local and international laws and regulations.
Just fill in the following items:
- Registration Email : The email address used to register for the service.
- One-time Password : The obtained one-time password credential.
After saving the configuration, enable Emailclaw on the channels page. The system will start polling the mailbox in the background. The allowed sender is simply your own email.
Send a new subject email to the Agent's email address, for example:
Subject: Organize competitor abstract for August product review
Please read the three materials in the attachment and output a one-page abstract in Chinese:
1. Three common trends;
2. Differences of each product;
3. Two suggestions for the product team.
Emailclaw will reply and append a TaskId at the end of the subject. Reply directly to this email to start execution; always reply to this thread when continuing the same task. When you need to start a different job, write a new subject email.
Emailclaw's goal is not to give the Agent unrestricted machine access.
- The Agent works within project and workspace boundaries.
emailAllowlistSendersrestricts which email addresses can initiate tasks.- High-risk tool calls can enter a manual approval process via email confirmation codes; timeouts, wrong codes, or replies across sessions will be rejected.
- Permission modes cover
explore(read-only),default(routine confirmation),accept_edits,dont_ask, andbypass. In production environments, please start withexploreordefault. - Third-party plugins, MCP services, and Skills may have file, network, or code execution capabilities. They should only be installed from trusted sources and verified in a low-privilege environment first.
The Linux .tar.gz package can be extracted and run directly in your home directory without root privileges. A user-level systemd service (~/.config/systemd/user/emailclaw.service) runs the daemon under your own user, sharing the same ~/emailclaw data directory as the desktop app. No config migration is needed.
The .deb package installs to /opt/emailclaw/ (requires sudo apt install); the installer creates a symlink at ~/.local/bin/emailclaw and registers the same user-level service for you.
After installation, enable the background service (no sudo required):
loginctl enable-linger "$USER" # keep the daemon running after logout
systemctl --user enable --now emailclaw
systemctl --user status emailclaw
journalctl --user -u emailclaw -f
Each Linux user can enable their own independent instance; every instance keeps its own ~/emailclaw data and configuration. For a complete step-by-step tutorial, see the User Manual.
Prerequisites: JDK 25, Maven, and the jpackage capabilities of the target operating system.
cd emailclaw
mvn -B package -DskipTests
The build will generate a shaded JAR and platform installation packages. GitHub Actions will build .exe, .dmg, and .deb on Windows, macOS, and Linux respectively when pushing v* tags, and additionally generate a Linux .tar.gz.
Run tests:
cd emailclaw
mvn -B test
emailclaw/ Java application source code and Maven build
plugin-samples/ Plugin development guide & InvokeAntigravityCli tool sample
docs/ Product features, architecture, and user manual
.github/workflows/ GitHub Release build workflows
The default runtime data root directory is ~/emailclaw, which can be modified via the Java system property emailclaw.home or the environment variable EMAILCLAW_HOME. Common subdirectories include:
| Path | Purpose |
|---|---|
.config/ |
JSON configurations for Providers, Agents, channels, projects, Cron, etc. |
.chat-history/ |
Session and message history |
projects/ |
Project directories created per task |
agent-workspace/ |
Agent workspaces |
skill-pool/ |
Skills |
plugins/ |
External plugins |
logs/ |
Application logs |
Plugins can provide tools, model Providers, startup/shutdown hooks, MCP, UI, or channel capabilities. Please start with the Plugin Developer Guide and plugin-samples/invokeAntigravityCli. Channel plugins are responsible for external session mapping, message forwarding, and (if needed) the secure delivery of approval requests.
We welcome improvements to Emailclaw through clear Issues and reviewable Pull Requests. Before submitting:
- Do not commit API Keys, email passwords, app authorization codes, or personal data.
- Add or update tests and documentation for behavioral changes.
- Run relevant Maven checks using JDK 25.
- Maintain plugin compatibility: external plugins should generally depend on the Emailclaw core API using
providedscope.
Emailclaw is licensed under the MIT License.