> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artil.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Who hears about new messages

> How an agent account's new email, texts, and messages at its Message URL reach the client that listens for them.

An agent account's new messages wait in its inbox: `artil email`, `artil sms`,
`artil telegram`, and the MCP `messages.list` tool show them at any time. To act on a message as
it arrives, a client listens to the agent, and Artil tells it the message's ID
when one comes in. The client reads the message and answers it the way its
instructions say, so test delivery and a reply before leaving it to answer on
its own; see [Messages are not instructions](/safety).

## Ways to listen

| Client | How it hears about a message | Set up with |
| - | - | - |
| [Claude Code](/claude-code) | The `artil-messages` channel in a session started with it | `artil init --client claude-code` or `artil plugin install claude-code` |
| [Pi](/pi) | The `artil-messages` extension in an open interactive or RPC session, which starts a turn | `artil init --client pi` or `artil plugin install pi` |
| [OpenClaw](/openclaw) | The Artil plugin in the running gateway | `artil plugin install openclaw` |
| [Hermes](/hermes) | A background job on this computer that starts a run, or the Artil plugin in the running gateway | `artil init --client hermes --connection local` or `artil plugin install hermes` |
| [Hermes on a server](/automatic-messages) | A webhook to its public URL | `artil init --client hermes --connection server` |
| [ChatGPT](/chatgpt) | An MCP events subscription | Ask it to watch the agent's messages |
| Your own server | A [webhook](/webhooks) | The API |

## One client at a time

An agent's new messages reach one client: the one that started listening last,
on this computer or another. When a client starts listening, the one before it
is told which client took over and hears nothing more until you start it again.
An MCP events subscription counts as a client: a new one ends the other
sign-ins' subscriptions and stops a CLI client listening as the agent. A
session that did not start listening never takes the messages, such as a Claude
Code session started without the channel or a `pi -p` run.

The agent's page in [Artil](https://app.artil.dev) shows the connected client.
`artil auth status` shows the client that listens now and this computer's
delivery setup, so it tells a client set up here apart from one that listens.

Webhooks are the exception. A [webhook](/webhooks) you add, and the one that
reaches a Hermes server, get every event whichever client listens.

## While nobody listens

A message that arrives while no client listens stays in the inbox and is not
delivered later. Check it with `artil email`, `artil sms`, or `artil telegram`,
the plugin's skill, or `messages.list`. Sending to the agent's [Message URL](/url) fails
while nobody listens, since Artil keeps no copy to read later.

## What the client is told

The notification names the message's ID. The client reads the message with the
CLI or the MCP `messages.read` tool and replies with `--reply-to` or
`messages.send`, only through Artil: a Telegram or email the client has of its
own is another account, and the sender would not get its answer there. A message at the [Message URL](/url) comes whole instead,
with who sent it and how to answer them.

Not every message wakes the agent: spam, limits, and senders the agent does not
take mail from are refused, and the inbox says why. See
[Who can wake the agent](/wake-access).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.