# MAX: start here (/en/docs/max)

`max` is a command-line tool that lets your AI agent read MAX, find messages and help you reply. You can also use it directly
from a terminal. It runs on Windows, macOS and Linux.

You are in the **MAX** documentation. Use the messenger switch at the top to open Telegram.

**On this page**

- [Choose what to connect](#choose-what-to-connect)
- [Start with your personal account](#start-with-your-personal-account)
- [Try it after connecting](#try-it-after-connecting)
- [Find the guide for your task](#find-the-guide-for-your-task)

## Choose what to connect [#choose-what-to-connect]

- **Personal account:** your chats, history and contacts, as on another device. Start with
  [installation and login](/llms.mdx/docs/installation/content.md#max).
- **Bot:** messages and actions in the bot's name, using its token. Open
  [the bot guide](/llms.mdx/docs/max/bot/content.md).

These are separate connections. Bots use the official MAX Bot API; personal accounts use an
internal API that may change without notice. See [security](/llms.mdx/docs/max/security/content.md) for limitations
and how credentials are stored.

## Start with your personal account [#start-with-your-personal-account]

### Connect through your agent [#connect-through-your-agent]

Open [the agent installation guide](/llms.mdx/docs/installation/content.md#max) and copy the short request.
Your agent will install the tool, help you log in and check the connection. You scan the QR code.

Then follow [the guide for your agent](/llms.mdx/docs/agents/content.md): Codex, Claude Code, Cursor, Gemini CLI
or Hermes. Apps that use MCP have a [separate MCP guide](/llms.mdx/docs/agents/content.md#mcp-and-skills).

### Start in a terminal [#start-in-a-terminal]

Open [the installation guide](/llms.mdx/docs/installation/content.md#max) and choose the terminal instructions.
After installing, run guided setup for QR login and agent skills:

```sh
max personal setup
```

```sh
max personal chats list --limit 5
```

`personal` is the profile name: choose any name at the first login and repeat it in every command.

Setup checks your account and up to five chats. Running it again reuses your session; it does not download full history or start the background service.

See [login and profiles](/llms.mdx/docs/max/sessions/content.md) for other login methods and additional accounts.

## Try it after connecting [#try-it-after-connecting]

Ask your agent to catch up on unread messages, find a message, recall agreements or prepare a
reply. Reading **does not mark messages as read**. Sending, deleting and other changes require
separate commands; you can restrict the agent's access.

`max search all` searches messages, imported mail and notes stored on this computer at once. Message search (`max search messages`) asks both the local archive and the messenger by default (`--backend both`); use `--backend archive` for local-only results. The query language is strict Lucene and does not correct typos; `--discover` also tries close spellings in the local archive. Prepare saved history before archive-only search, counting or rankings, and check coverage before treating an empty result as proof that a message is absent. Without a chat, the MAX server returns one best match from each chat. Counts, rankings and queries unsupported by the server use saved history. [Search guide](/llms.mdx/docs/max/search/content.md).

## Find the guide for your task [#find-the-guide-for-your-task]

| Task | Guide |
|---|---|
| Read, search and send messages in your own name | [Everyday commands](/llms.mdx/docs/max/usage/content.md) |
| Log in, log out or add another account | [Login and profiles](/llms.mdx/docs/max/sessions/content.md) |
| Connect a bot, send messages and add buttons | [Bots](/llms.mdx/docs/max/bot/content.md) |
| Follow unanswered questions and moderate a group | [Your groups](/llms.mdx/docs/max/groups/content.md) |
| Search syntax, dates and filters | [Message search](/llms.mdx/docs/max/search/content.md) |
| Search local history and export conversations | [Message archive](/llms.mdx/docs/max/archive/content.md) |
| Find a ready request for your agent | [Usage recipes](/llms.mdx/docs/max/recipes/content.md) |
| Fix an error | [Troubleshooting](/llms.mdx/docs/max/troubleshooting/content.md) |
| Look up an exact command or option | [Command reference](/llms.mdx/docs/max/commands/content.md) |
| Manage contacts, aliases and private notes | [People](/llms.mdx/docs/max/people/content.md) |
| Compare activity and inspect ranking evidence | [Rankings](/llms.mdx/docs/max/rankings/content.md) |
| Send, download and read files | [Attachments](/llms.mdx/docs/max/attachments/content.md) |
| Transcribe voice messages locally | [Voice transcription](/llms.mdx/docs/max/audio-recognition/content.md) |
| Configure optional model APIs | [External models](/llms.mdx/docs/max/external-models/content.md) |
| Restrict reads, writes and confirmations | [Permissions](/llms.mdx/docs/max/permissions/content.md) |
| Choose a personal or bot profile | [Profiles and bots](/llms.mdx/docs/max/profiles/content.md) |
| Look up setting types and precedence | [Configuration reference](/llms.mdx/docs/max/configuration-reference/content.md) |

The left sidebar lists shared guides and both messengers. The right sidebar lists sections of the current page. Start
with installation; use the detailed reference when you have a specific task.
