@gent
Get it on PyPIPyPI

@gent

Email an idea. Your coding agent gets to work.

You email yourself a task. Codex or Claude Code runs it on your own computer and replies in the same Gmail thread.

youremail+agents@gmail.comUse the Gmail you already have. Add +agents to your own address. Gmail delivers it to your normal inbox, so you need no new email account.
uv tool install atgent
Get it on PyPIHow it works

FreeYour own GmailRuns on your computer

Works withCodexClaude CodeGmailmacOSLinux

A sample thread. The runner sends Queued, Started and the result as replies to your task.

Ideas show up when you’re away from your desk.

You remember a bug on a walk. You think of a change while you wait for coffee. You can send it to your agent right then, from your phone.

While you’re out

You remember a bug while you’re out.You are on a walk and remember that people get stuck on your signup form. Your computer is at home.

One email starts a task. Replies keep it going.

You set up a small runner on your computer once. You need no phone app, SSH, tunnel, hosted mail service or agent plugin.

From any device

You email yourself a task.You send it from your own Gmail to your own address with +agents added, from your phone or any other device. The subject starts with the agent’s name. You can add a model in square brackets. Add terminal there to open the task in a Terminal window instead of running it in the background. Attach files and the agent gets them.

On your computer

Your computer picks it up.The runner reads your Gmail Sent folder, not your Inbox. It starts Codex in your project with your existing sign-in. Tasks for different projects can run at the same time.

Only you can send it tasks.

Mail from other people lands in your Inbox. The runner does not read your Inbox, so their mail cannot start a task.

Queued, Started, then the result.Each update arrives as a reply in your task’s thread. The result is the agent’s final message as formatted email. Every reply ends with the task id and the command to open it in your terminal.

In the thread

Reply to keep going.Your reply goes to the same agent session. The agent still has the earlier turns.
Check or stop from your phone.A reply of status gets progress back. A reply of stop stops the running agent. Changes it already made stay in your project. With approval emails on, you approve or deny a blocked action from your phone too.

At your desk

Continue in your terminal.atgent list shows each email task with its agent, model and status. Select one and press Enter to resume the same session in your terminal. The agent then answers there, not by email. You can stop a task that is still running from email and open it from the list.

The subject line picks the agent, the project and the model.

You send every task to your +agents address. Write the task in the email body. Plain text, HTML email and attachments are supported.

You sendWhat happens
Codex: improve the signup formCodex runs the task in your default project.
Claude: improve the signup formClaude Code runs the task in your default project.
Codex/website: fix the footer linksCodex runs the task in the project named website in your config.
Claude [opus]: review the auth flowClaude Code runs the task with the opus model. Replies in the thread keep that model.
Codex/website [gpt-6.1-sol]: fix the buildCodex runs the task in the website project with the gpt-6.1-sol model.
Claude [opus, terminal]: review the auth flowClaude Code opens the task in a new Terminal window and uses the opus model. Add headless in the brackets to run the task in the background.
A reply with your next instructionThe same session continues with your reply.
A reply of statusYou get the status of each turn by email.
A reply of stopQueued turns are cancelled and the running agent stops. File changes it already made are kept.

Agent names ignore case. Project names are case sensitive. Without a model in brackets, the agent’s default model from your config is used. Without terminal or headless in brackets, your configured default mode is used, and a new config runs tasks in the background. A terminal task finishes its email turn when the window opens, and the agent’s output stays in that window. A reply resumes a Claude terminal session. Codex terminal sessions are not tracked, so a reply opens a new window. You write replies above the quoted conversation.

You set it up once on the computer that runs the agent.

Install uv first. Then install Codex or Claude Code and sign in.

  1. Install

    Install the runner with uv.

    uv tool install atgent

  2. Create the config

    The guided setup asks for your Gmail address, how the runner signs in, your project folders, which installed agents to use and a default model for each. It writes no secret to the config.

    atgent init

  3. Give it Gmail access

    Turn on IMAP in your Gmail settings. Create a Google app password. If your account blocks app passwords, use your own Gmail OAuth desktop client instead.

    Keep the app password in your OS keychain or in the AGENT_MAILBOX_PASSWORD environment variable. Never put it in the config file.

  4. Check

    Doctor signs in to Gmail over IMAP and SMTP without sending mail. It also checks that Codex and Claude Code are installed.

    atgent doctor

  5. Start

    Start runs the runner in the background. Its first check skips your old Sent mail. You send your first task after that.

    atgent start

  6. Change a model

    Set an agent’s default model at any time. Use default to go back to the agent’s own default.

    atgent model claude opus

  7. Choose headless or terminal

    Set how tasks run by default. Terminal opens each task in a new Terminal window. Headless runs it in the background and emails the result. A subject can override this for one task. Name an agent to change only that agent.

    atgent mode terminal claude

    For Claude terminal tasks, Remote Control lets you continue the session from your phone or the web.

    atgent remote-control on

What it needs and what this release supports.

HTML email, attachments, concurrent projects, approval email replies with both agents, and the login service were tested live on macOS. Linux and Gmail OAuth are unit-tested only.

You need

Before you install
  • A Gmail account with IMAP access and an app password or your own OAuth client ID. Managed accounts may require administrator approval.
  • macOS or Linux.
  • Python 3.11 or later, and uv.
  • Codex or Claude Code, installed and signed in. Claude Code needs version 2.1.259 or later.
  • A computer that stays awake and online. The optional login service restarts the runner after you sign in.

In this release

Features and limits
  • Plain text and HTML email are accepted. Attachments are saved privately and their paths are given to the agent. Defaults: 5 MiB per attachment, 10 MiB combined, up to 10 files.
  • Several tasks can run at once. Set up to 32 workers, and mark a project concurrent to run separate tasks in one folder. The default is one worker. Turns in the same thread or session always run one at a time.
  • Replies are sent as formatted email with bold text, lists, tables and links, plus a plain text copy.
  • Codex sandbox and approval policy are configurable per project and agent. The defaults remain workspace-write and no approval prompts.
  • Approval emails are optional for Codex and Claude Code. With approvals off, Claude denies actions needing approval and marks the turn needs_review. The reply names each blocked call with its command or file. Completed work is kept.
  • Email bodies are limited to 32,000 characters. Raw messages over 20 MiB are ignored. Linux service setup and Gmail OAuth have unit tests; they have not been tested live.

Optional approvalsEnable approval emails to approve or deny a blocked action before it runs. Reply directly to its approval email with approve or deny. Token replies are also supported. Silence times out to deny. Each approval covers one action; approve all is not supported.

Questions

Short answers about cost, safety and where the work runs.

Yes. It is free. Your existing Codex or Claude Code plan and its limits apply.

Only mail you send from your own Gmail account. The runner reads your Sent folder, not your Inbox. Anyone who can add mail to your Sent folder can also send tasks, so protect your Gmail account and its credentials.

It runs on your computer, in the project folders you list in the config. Your repositories and agent sign-ins stay on your computer. Task text and results travel through Gmail and your agent provider.

By default, Codex uses workspace-write and never waits for approval prompts. Its sandbox and approval policy can be configured per project and agent. Claude Code denies actions needing approval by default. Enable optional approval emails to approve or deny individual native requests. No reply means denial after the configured timeout. You review the work before you publish or deploy it.

Yes, when you install the optional login service with atgent install-service. It starts after you sign in and restarts the runner on failure. Use service-status to check it or uninstall-service to remove it. The computer must stay awake and online while tasks run. The macOS service was tested live; Linux was unit-tested only.

Yes. Run atgent list, move to the task with the arrow keys and press Enter. The same session resumes in your terminal, and the agent answers there instead of by email. atgent open TASK_ID opens one task directly. Type / in the list to filter it. A task still running from email can be stopped from the list and then opened.

Yes. Setup asks for a default model for each agent, and atgent model claude opus changes it later. To use another model for one task, put its name in square brackets in the subject, as in Claude [fable]: your task. Replies in that thread and a terminal resume keep the same model. Put terminal or headless in the same brackets, as in Claude [opus, terminal]: your task, to choose whether that task opens in a Terminal window or runs in the background.

Send your first task.

Install the runner, run doctor, then email a task to your +agents address.

Get it on PyPISetup