Using AI agents with HEY
Connect an AI agent (Claude Code, Codex, or another tool you already use) to your HEY account through the HEY CLI, and it works in your email the same way you do. Ask it to sort your Screener, clear out Reply Later, draft a reply, or pull the details out of a long thread.
The agent acts as you, with the same access you have, so it tends to earn its keep on the parts of your routine that repeat every day. If you'd rather work in the terminal yourself instead of handing tasks to an agent, the HEY TUI runs on the same CLI with no agent involved.
In this article
Everything here happens in a terminal on your computer. You'll also need a subscription to an AI service like Claude or ChatGPT — the CLI connects your agent to HEY, but it doesn't provide the agent.
Installing the CLI
Open your terminal and paste this in:
curl -fsSL https://hey.com/install-cli | bash
That's the whole install. The script downloads the hey binary and puts it somewhere your terminal can find it.
New to the command line? The terminal is an app that's already on your computer — it's called Terminal on a Mac. Open it, paste the line above, and press Return. You don't need to know anything else about the terminal to get through the rest of this article.
On Windows 11, Smart App Control may block the install. Check our Windows troubleshooting steps.
Signing in to your account
Run hey for the first time and our setup wizard will walk you through everything. It signs you in through your browser, confirms your identity, and connects any coding agents it finds on your machine.
After that, entering hey on its own prints the list of available commands. Four more cover the rest of signing in:
hey setup— run the wizard again at any timehey login— sign back inhey logout— sign out and clear your credentialshey auth status— check whether you're currently signed in
If something stops working — the CLI won't connect, or mail stops updating — run hey doctor . It checks whether you're still signed in, whether your credentials are stored securely, and whether you're on the current version, and it suggests a fix for anything it finds.
Connecting your agent
Most people don't need to do anything here. The setup wizard detects Claude Code and Codex during first run and connects them for you.
To connect one on its own, or to reconnect after installing a new agent:
hey setup claude
hey setup codex
Run hey setup --skip-agents if you'd rather the wizard leave your agent setup alone.
For any other agent, the CLI runs as an MCP server, which most agents can connect to:
hey mcp
Register it with your agent as a stdio server — in Claude Code, that's claude mcp add hey -- hey mcp . This serves your boxes, search, threads, contacts, todos, and calendars as tools your agent can call.
NOTE: your agent gets the same access you have. Every message in every box, your calendar, todos, and contacts — none of it is walled off, and the agent can write as well as read. Two ways to draw a line around that: run hey mcp --read-only to serve read-only actions only, or hey logout to cut access off entirely.
Putting your agent to work
Ask for what you want in plain language. The agent works out which commands to run:
Let’s set up a routine to manage my screener. Screen IN anything transactional (receipts, shipping notifications, etc) or anything that is clearly personal and real, but screen OUT anything that is clearly a sales pitch or a scam or misleading or whatever. Do this once a day.
Beyond email, the CLI reaches most of HEY:
- Boxes, threads, replies, drafts, and composing new mail
- Search
- Contacts
- Calendars and events
- Todos, habits, and time tracking
- Journal entries
To see the everything the HEY CLI can do, run hey on its own or browse the hey-cli repository.
Doing something interesting with your agent? We'd love to hear about it — get in touch.