> ## 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.

# Receive messages automatically

> Let an incoming message notify Claude Code or start a Hermes run.

Use `artil init` to have incoming messages notify an open Claude Code session
or start a Hermes run. First [install the CLI](/installation),
[sign in as your agent](/authentication), and check that you can
[read its email](/email).

For inbox checks during a conversation, use the [Claude Code plugin](/claude-code)
or [Pi extension](/pi).

## 1. Choose where the agent will run

Choose a client below. Local setup adds message delivery, the `artil` skill,
secret loading, and the agent's MCP connections. Choosing a new client replaces
the existing delivery setup, including any remote Hermes webhook for this agent.

<Note>
  Local setup links **all** of the agent's stored secrets. Members who can access
  a workspace agent can reveal those secrets. The Claude Code link uses your
  user-level configuration and applies across projects; Hermes uses its configured
  installation. Review the agent's secrets before connecting a client.
</Note>

<Tabs>
  <Tab title="Claude Code">
    Install Claude Code and use Anthropic authentication. Channels are not
    available through Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry.
    On Team and Enterprise plans, an owner must enable channels first. Console
    organizations that deploy managed settings must enable `channelsEnabled`.
    The development flag below cannot override a disabled channel setting.
    See [Claude's channel requirements](https://code.claude.com/docs/en/channels#enterprise-controls).

    Connect this computer:

    ```bash theme={null}
    artil init --client claude-code
    ```

    Setup adds the `artil-messages` channel and allows the CLI commands that
    read and send messages. Complete any steps under **STILL YOURS TO DO**,
    such as fixing a skill conflict or finishing an MCP connection.

    Start a new Claude Code session using the command setup prints:

    ```bash theme={null}
    claude --dangerously-load-development-channels server:artil-messages
    ```

    Check that Claude starts with the channel enabled. Resolve any startup
    warning about blocked channels. The new session also loads the secrets hook.
    Keep it open for the email check below; closing it stops notifications.
  </Tab>

  <Tab title="Local Hermes">
    Install and configure Hermes first. Background delivery needs a macOS login
    session or a running Linux systemd user service.

    ```bash theme={null}
    artil init --client hermes --connection local
    ```

    Read the **STILL YOURS TO DO** output and complete any remaining setup.
    The machine must stay on and connected; no public webhook URL is needed.

    Setup prints the background job's log path. Each incoming message starts
    a separate `hermes chat -q` run, one at a time. Check that log if a run fails.
  </Tab>

  <Tab title="Remote Hermes">
    First give your remote Hermes access to Artil's `messages.read` and
    `messages.send` tools as this agent. The webhook only notifies Hermes when
    a message arrives. If those tools are not configured, use **Local Hermes**
    on the server with a [headless login](/authentication#use-a-headless-machine).

    Use the public URL for your Hermes server:

    ```bash theme={null}
    artil init --client hermes --connection server --url https://hermes.example.com
    ```

    Setup configures the webhook route and shared signing secret when Hermes'
    configuration is present locally. Otherwise it prints the configuration
    to add on the server. Follow those instructions before testing delivery.

    Start Hermes with that configuration and check that its public URL is
    reachable. The webhook asks Hermes to use `messages.read` and `messages.send`
    with the incoming message ID.

    Install any skills, credentials, and MCP connections Hermes needs on the
    remote server separately.
  </Tab>
</Tabs>

## 2. Check an incoming message

From your own email account, send a new message to the agent's address.
For example: “Please reply to confirm you can read this email.”

The client receives a notification containing the message ID. Local clients use
the CLI to read and reply; the remote Hermes webhook prompts it to use its
configured message tools.

Watch the client read the message, then check your inbox for its reply.

<Accordion title="No notification or reply?">
  Keep Claude's session open, or check the background-job log for local Hermes.
  For a remote Hermes server, check that webhook setup is complete and the URL
  is reachable. Inspect any client permission prompts before expecting a reply.

  Run `artil auth status` to check the agent and its channels. Sender
  restrictions, spam filtering, and notification limits can stop a message
  from reaching the client. See [message troubleshooting](/troubleshooting).
</Accordion>

Claude may show the same notification after reconnecting or in another session.
Keep one answering session open per agent to reduce duplicate replies.

<Card title="Next: sign up for a service" href="/email-identity">
  Use this inbox to receive a verification email, finish signup, and store the service's credentials.
</Card>

## Change or disconnect a client

<AccordionGroup>
  <Accordion title="Change or repair setup">
    Run `artil init` to choose a different client. A new choice replaces the
    existing delivery setup, including the agent's remote Hermes webhook if
    you switch to a local client. Keeping the same choice repairs outdated
    setup and updates the installed skill, secret links, and MCP entries.

    If a separately installed skill has the same name, setup keeps it and
    reports the conflict under **STILL YOURS TO DO**.
  </Accordion>

  <Accordion title="Disconnect message delivery">
    This command removes delivery setup on this computer and the selected
    agent's remote Hermes webhook. It stops webhook notifications to that
    server even if another computer configured the connection.

    ```bash theme={null}
    artil init --client none
    ```

    It also removes the skills, secret links, and MCP entries that setup added
    for the disconnected local clients. Your agent, messages, and secrets
    remain stored in Artil. The webhook route in Hermes' own configuration
    stays in place; you can remove that route yourself.

    Remove separately linked secrets, such as a project's `.env`, with
    `artil secrets unlink <place>`. Stop programs that already loaded those values.
    For CLI sign-out, see [manage a login](/authentication#manage-a-login).
  </Accordion>
</AccordionGroup>


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