Email your @gent. Stay hands off.

$ uv tool install atgent Set it up

Hands off

Email, not a terminal.

A remote session keeps the terminal open on your phone. You watch each step scroll past and answer prompts as they come up. With atgent, you describe the task once, close the email, and receive a reply when there is something to read.

A remote terminal session

You keep the session open while the agent works.
You watch tool calls and output scroll past on a small screen.
You answer prompts as they come up.
You keep your attention on the agent until it finishes.

An email to atgent

You send one email and close it.
You receive a reply when the agent starts and another when it finishes or has a question.
The result lists the changed files and the checks the agent ran.
Reply merge, pr or undo, or reply with the next change.

While you’re out

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.

1Send the task from your own Gmail to your own address with +agents added.
2The subject line names the agent. The body describes the task.
3Queued and Started arrive as replies in the same thread.

1 2

CancelNew message

Fromyouremail@gmail.com

Toyouremail+agents@gmail.com

Subjectcodex

Find the confusing parts of the signup form, improve them, and run the relevant checks. Leave the changes ready to review.

3

Re: codex9:52

Queued: codex / main / agent default / headless

Re: codex9:52

Started. Your agent is working on this task.

On your computer

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.

Your Gmail Sent

To: +agents9:52 AMcodex — Find the confusing parts of the signup form…

To: Jess WongYesterdayCoffee Friday?

Your computer runner.log

09:41:02 INFO Intake armed for new messages; historical Sent mail skipped
09:52:17 INFO Accepted task 3f9c2a7e
09:52:18 INFO Running task 3f9c2a7e turn 1

The same thread 10:07 AM

Completed

I relabelled the signup fields and added inline error messages.

Task 3f9c2a7e. Reply in this thread to continue, or reply status / stop. On its own branch: reply merge, pr, undo, discard or diff. Continue in Terminal: atgent open 3f9c2a7e

In the thread

Reply in the thread to continue the task.

Queued, Started and the result stay in the same email thread. The result lists the changed files and the check results. Reply to continue, reply merge to land the branch, or open the same session at your desk.

codex4 messages

meRunner10:07 AM

Completed

I relabelled the signup fields and added inline error messages.

Finished in 14m 52s. Changes on branch atgent/3f9c2a7e: 2 files, +48 −9 - src/signup/Form.tsx +41 −9 - src/signup/Form.test.tsx (new) +7 Checks passed. npm test passed in 21s.

Task 3f9c2a7e. Reply in this thread to continue, or reply status / stop. On its own branch: reply merge, pr, undo, discard or diff. Continue in Terminal: atgent open 3f9c2a7e

1

me10:14 AM

Also add a test for the empty email case.

meRunnerSame session10:14 AM

Started. Your agent is working on this task.

2

statusreply with one word

Turn 1: completed
Turn 2: running

The reply lists each turn of the task and its state.

3

stopreply with one word

Stop requested. Queued turns cancelled; any running process is being stopped. Existing file changes are retained.

The running agent stops. Files it already changed stay changed.

4

mergereply with one word

Merged into main as one commit 8e41c0d2a9.
2 files changed, 48 insertions(+), 9 deletions(-)

The task lands on your branch as one commit. Reply revert to take it back.

A session you already started

Get a session you already started in your inbox.

Connect a persisted Claude Code or Codex session to atgent. With the MCP server and native identity hooks enabled, ask “email me this session.” Close the local session, hand it off, and reply from your phone to continue.

Claude Code website

> email me this session

atgent · attach_session (MCP)

Connected as task 7c41e2d0. The opening email is queued. Replies wait until you close this session and run atgent handoff 7c41e2d0.

Your Gmail a new thread

From: me4:12 PMFinish the settings page

Connected to your existing claude session: Finish the settings page
Project: website

Reply here from your phone. Replies queue while you work locally. Close the local session, then run atgent handoff 7c41e2d0 to enable email turns.

Hand off then reply

$ atgent handoff 7c41e2d0
Task 7c41e2d0: queued (email ownership)

me4:31 PM

Also cover the empty state.

meRunnerSame session4:31 PM

Started. Your agent is working on this task.

Connect a session Available in atgent 0.5.0

Smart parsing

The subject line picks the agent. Settings follow in any order.

atgent parses the subject. Put the agent first, then add a project, a model or other settings in any order. You do not need a colon or brackets. Write the task in the email body.

Every subject word

Subject

claudeAgentclaude, codex or another agent

websiteProjectA name from your config

opusModelOptional

terminalSettingsOptional, any order

codex

Codex runs the task in your default project, on its own branch.

claude website opus

Claude Code runs the task in the project named website with the opus model. Replies in the thread keep that model.

claude readonly

Claude Code reviews the code and changes no files.

codex high 30m pr

Codex works with high effort for up to 30 minutes and opens a pull request when it finishes.

codex terminal

Codex opens the task in a new Terminal window.

claude opus: fix the login page

Text after a colon is a title for your own inbox. atgent does not read it or send it to the agent.

Capital letters do not matter. A word that is not a setting does not stop the task. The Queued reply names each word it ignored. The older Claude/website [opus]: form still works.

Forward it, say it, schedule it.

Each one is a reply, an attachment or a word in the subject. Results come back to the same inbox.

A print of a hand holding a phone, sending an envelope with a note clipped on top.

fix thisa forwarded email

Forward a bug report or an error alert with a note such as fix this. The forwarded message becomes the task, marked as content from someone else.

A print of a person on a walk speaking into a phone, the sound travelling to a laptop on a desk.

memo.m4aan attachment

Attach a voice memo. It is transcribed on your computer before the task starts, and the audio does not leave your computer.

A print of a laptop sending a question by envelope to a person on a park bench.

Questiona result email

When the agent needs a decision, it ends its turn with a question. Your reply answers it in the same session.

A print of an envelope reaching a fork in a dotted path, each branch ending at a laptop.

claude codexin the subject

Put two agents in the subject and both work on the task, each on its own branch. Reply keep codex to keep one.

A print of a wall calendar and a clock sending envelopes at regular intervals.

weekdays 9amin the subject

Add when to run it to the subject. Each run starts a fresh task, and its result arrives in the same thread.

A print of a hand filing an envelope in a card box while a copy flies out.

save as reviewa reply

Reply save as review to save a task's settings and first instruction. Then send review as the subject.

A print of a pipeline of boxes sending an envelope to a laptop.

github_ciin the config

A failed GitHub Actions run, a labelled GitHub issue or a webhook starts a task on your computer.

A print of a hand opening a letter at a breakfast table.

atgent summary at 8amin a terminal

One email a day lists what ran, what is waiting on you and what failed.

A print of different tools on a pegboard linked to one envelope.

geminiin the subject

Gemini CLI, opencode, aider and Cursor's agent also work. Each is one word in the subject.

At your desk

Pick up the same session in your terminal.

atgent list shows your email tasks and the Claude Code and Codex sessions you connect. Enter resumes the selected session in your terminal. Use atgent 0.5.0 or later and refresh the runner after upgrading.

The same session, now answering in this terminal

Terminal · ~

atgent list
 atgent sessions   up/down move  Enter open  / filter  q quit
  AGENT   MODEL       STATUS        UPDATED   SUBJECT
  Claude  opus        running       2m ago    review the auth flow
> Codex   default     completed     14m ago   improve the signup form 
  Claude  default     needs_review  1h ago    fix the build
 3f9c2a7e last reply 
Completed. I relabelled the signup fields and added inline error messages.

>_ OpenAI Codex
Resuming session…

sessions a new email to your +agents address

To: youremail+agents@gmail.com4:40 PManything

sessions

The directory reply

Your atgent sessions

    7c41e2d0 | claude | website | local | Finish the settings page
    3f9c2a7e | codex | main | completed | improve the signup form

open 7c41e2d0 reply to the directory

me4:41 PM

open 7c41e2d0

meRunner4:41 PM

Session 7c41e2d0 queued for email delivery in its own thread.

Reply in that thread to continue. You need no dashboard login.

Find sessions by email Available in atgent 0.5.0

Optional dashboard

Find a session from your phone.

The optional dashboard lists sessions from your paired computers. Use the email address atgent already uses, sign in with a magic link, and choose a session for atgent to email you its thread.

atgent.dev/dashboard

SessionsCoding sessions from your paired computers, newest activity first.

Search by title or projectAllClaude CodeCodexAny status

SessionAgentStatus

Finish the settings pagewebsiteClaude CodeLocally controlled

improve the signup formmainCodexDone

review the auth flowwebsiteClaude CodeRunning

Finish the settings page

Project: website
Agent: Claude Code
Status: Locally controlled
Computer: Studio laptopOnline

Replies wait while the terminal on Studio laptop controls this session. Close the local session, then run atgent handoff 7c41e2d0 on that computer to continue by email.

Email me this thread

Sessions1 of 1 online

Search by title or project

Finish the settings pagewebsite · Claude CodeLocally controlled

improve the signup formmain · CodexDone

review the auth flowwebsite · Claude CodeRunning

Finish the settings pagewebsite · Studio laptopOnlineEmail me this thread

Login is optional

Dashboard login is optional. Your CLI and email workflow keep working without it. To pair a computer, run atgent login on it and approve it in the dashboard.

What it stores

The dashboard stores session titles, project aliases, agent and model, status and timestamps. It never receives transcripts, prompts, results, attachments, file paths, native session IDs or mailbox credentials. Titles can contain private text.

When the computer is offline

Requests wait for the computer. The computer must stay awake and online with the runner active. A finished request means the computer queued the email, not that Gmail delivered it.

Open dashboard Dashboard is available How pairing works

A print of a door with a mail slot. One hand turns the only key while a letter passes through, and other letters lie stopped on the mat.

Your Sent folder

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.

Where the code runs

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.

What to protect

Anyone who can add mail to your Sent folder can also send tasks. Protect your Gmail account and its credentials.

Setup

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

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

Optional: choose campaign measurement before setup

If you came through the Google test and want to share coarse campaign counts, read the measurement guide before running atgent init. Its opt-in must happen before configuration to count a new configuration. Ordinary setup works without it.

1
Installuv installs the atgent command.uv tool install atgent
2
Create the configGuided setup asks for your Gmail address, your project folders and which installed agents to use. It writes no secret to the config.atgent init
3
Give it Gmail accessTurn on IMAP and create a Google app password. Keep it in your OS keychain or password manager.
4
CheckDoctor checks Gmail over IMAP and SMTP without sending mail, plus the installed agents.atgent doctor
5
Enable automatic startupThe login service starts the runner after you sign in.atgent install-service

Terminal · one-time setup

uv tool install atgent
atgent init
Gmail or Google Workspace address: youremail@gmail.com
  Project alias (e.g. main): website
  Folder for website [/Users/you]: ~/code/website
  Use Claude Code (/opt/homebrew/bin/claude)? [Y/n]: y
Wrote ~/.config/atgent/config.json.
atgent doctor
Gmail authenticated; trusted Sent folder available
atgent install-service

Optional: connect sessions and pair a computer

Setup ends at step 5. Session options are available in atgent 0.5.0. Upgrade with uv tool upgrade atgent, then run atgent start to refresh the runner. Dashboard pairing is available with the email address in your config.

Email me this sessionAdd the local MCP server and the identity hooks to Claude Code. For Codex, use codex mcp add and atgent integrate codex.claude mcp add atgent -- atgent mcpatgent integrate claude --output ~/.claude/settings.jsonConnect a session

Find sessions by emailNo extra setup is required. Email sessions to your +agents address, then reply open with a task ID.Find sessions by email

Pair the dashboardPair this computer with the optional dashboard. You approve the pairing after you sign in with the email in your config.atgent loginPair a computer

Advanced: list new sessions automatically

Add --auto-register to also install a Stop hook. After a completed turn, it lists that persisted session in atgent list, the email directory and a paired dashboard. It sends no email. It works only in projects and profiles from your config, and it does not import older sessions.

atgent integrate claude --auto-register --output ~/.claude/settings.json

This release

What it needs and what this release supports.

The macOS login service, attachments and approval replies were tested live. Linux and Gmail OAuth are unit-tested only.

You need

A Gmail account with IMAP access and an app password or your own OAuth client ID.
macOS or Linux, Python 3.11 or later, and uv.
Codex, Claude Code, Gemini CLI, opencode, aider or Cursor's agent, installed and signed in.
A computer that stays awake and online.

In this release

In a git project, each task runs on its own branch until you reply merge.
Result emails list the changed files, a short diff and the check results.
Up to 32 workers can run tasks at once. Turns in one thread run one at a time.
Replies are formatted email with a plain text copy.
atgent list resumes an email task’s session in your terminal.
Approval emails are optional for Codex and Claude Code.

Sessions and the dashboard

Questions about connected sessions.

These answers cover session commands in atgent 0.5.0 and the optional dashboard. Sign in with the email address in your config to pair a computer.

Which email address do I use?

Use the Gmail or Google Workspace address in your atgent config. The dashboard sends the sign-in link to that address. Connecting the mailbox to atgent does not sign a browser in.

Why does my reply wait after I connect a session?

The terminal still controls the session. Replies queue until you close the local session and run atgent handoff TASK_ID. atgent cannot see every agent process, so it never releases a session on a timer.

What happens when my computer is offline?

Replies and dashboard requests wait until the computer is awake and online with the runner active. The dashboard shows a computer as offline after 90 seconds without a heartbeat.

What does the dashboard store?

The dashboard stores session titles, project aliases, agent and model, task IDs, status and timestamps. It never receives transcripts, prompts, results, attachments, file paths, native session IDs or mailbox credentials. Task text and results still travel through Gmail and your agent provider.

How do I remove a computer?

Run atgent logout on that computer, or revoke the computer in the dashboard. Your local task history and email stay as they are.

Send your first task.

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

$ uv tool install atgent Get it on PyPI