max-cli

<p align="center"> <img src="https://raw.githubusercontent.com/leemour/max-cli/main/docs/design/logo_text.png" alt="Max CLI" width="480"> </p> # max-cli Ваш личный аккаунт мессенджера [MAX](https://max.ru) в терминале и в ИИ-агентах. `max` — программа для терминала и MCP-сервер: читайте и пишите в чаты сами или поручите это Claude, Codex, Cursor и другим агентам. > ⚠️ **max-cli использует неофициальный внутренний API MAX.** API может измениться без > предупреждения, а использование инструмента может нарушать условия сервиса. Вы используете > max-cli на свой риск; авторы и контрибьюторы не несут ответственности за блокировки аккаунтов, > потерю данных или другие последствия. ```sh max chats list --limit 5 max messages list "Иван Петров" max messages send "Иван Петров" "Опаздываю на 15 минут" ``` ## Как это использовать Самое полезное — поручить переписку агенту: Claude, Codex или другому. Он читает чаты через `max` и делает то, что вы попросили словами. - **Проверка по расписанию.** Утром и вечером агент смотрит, что пришло, и присылает короткую сводку: кто ждёт ответа, что срочно, что можно не читать. - **Отчёты.** Итог недели по рабочему чату: что решили, кто что взял на себя, какие вопросы остались без ответа. - **Кто кому должен.** `max review` одним вызовом отдаёт всё, что было в переписке с прошлого обзора, — ваши сообщения тоже, голосовые — текстом. Агент раскладывает это на «я должен», «жду от других» и «нужно уточнить», а прежде чем назвать что-то просроченным, проверяет рабочие группы: может, уже сделано. - **Напоминания.** Кому вы обещали ответить и не ответили; чей вопрос висит третий день. - **Черновики ответов.** Агент предлагает текст, а отправляете вы — или он сам, если вы разрешили писать в этот чат. - **Поиск.** «Когда мы договорились о встрече с Иваном?» — ответ с датой и самим сообщением. Как это выглядит: ```text Вы: Что я кому обещал за последние три дня? Агент: (вызывает max review: 12 чатов, 3 голосовых расшифровано) Я должен · Ивану Петрову — прислать счёт до пятницы. «Иван Петров», 24.09 Жду от других · Ольга — макет к 25.09. В группе «Дизайн» его пока нет Нужно уточнить · «Проект Альфа»: кто везёт образцы — договорились «потом решим», 25.09 Следующий обзор — с 26.09, 14:05. Вы: Напомни Ольге про макет. Агент: Черновик: «Ольга, привет! Как там макет?» Отправить? Вы: Да. ``` Агент ничего не отправляет без вашего «да», а чтение не ставит отметку «прочитано». Как настроить агента под каждую задачу — готовые запросы, расписание и ограничения: [docs/recipes.md](docs/recipes.md). ## Как это работает `max` работает от вашего имени, как ещё одно ваше устройство, а не как бот. Вы входите один раз по QR-коду, и дальше доступно то же, что в приложении: чаты, сообщения, файлы, группы, контакты и профиль. Агенту `max` подключается одним из двух способов: - **Агент с терминалом** — Claude Code, Codex, Gemini CLI. Он сам вызывает команды `max`. Дайте ему навык (skill) — инструкцию, как работать с `max`: одна команда, см. [ниже](#для-скриптов-и-агентов). - **Агент без терминала** — Claude Desktop, Cursor и другие клиенты MCP. Подключите `max mcp`: готовую запись для их настроек печатает `max mcp config`. Там же есть команды `/catch-up` (что нового), `/review` (кто кому должен), `/reply` (черновик ответа) и `/find` (поиск). По умолчанию агент только читает. Отправку можно разрешить, в том числе с вашим подтверждением каждого сообщения. [](https://www.npmjs.com/package/@leemour/max-cli) [](https://github.com/leemour/max-cli/actions/workflows/ci.yml) [](https://nodejs.org/) [](https://bun.sh/) [](https://www.npmjs.com/package/@leemour/max-cli) [](LICENSE) ## Что умеет - **Читать.** Чаты, история, одно сообщение вместе с соседними, непрочитанное во всех чатах сразу (`max inbox`), вся переписка с прошлого обзора для разбора «кто кому должен» (`max review`), новые сообщения по мере прихода (`max watch`), скачивание вложений, расшифровка голосовых в текст на вашем компьютере, выгрузка переписки в JSONL или Markdown. - **Искать.** Сообщения — по тексту всего прочитанного, без подключения к MAX. Чаты и контакты — по части названия или имени. - **Писать.** Текст и разметка, ответы, фото и файлы, правка, пересылка, закрепление, реакции, отложенная отправка, удаление — у себя или у всех. - **Вести группы и каналы.** Создать группу, вступить по ссылке, выйти, участники и админы, название и настройки, заявки на вступление, ссылка-приглашение, папки. - **Контакты и аккаунт.** Найти человека по номеру, добавить, удалить, импортировать из файла; изменить профиль; посмотреть и завершить другие сеансы. - **Входить удобным способом.** QR-код прямо в терминале, QR-код или SMS через web.max.ru в браузере, или готовый токен. ## Чем он хорош - **Читает незаметно.** Чтение не ставит отметку «прочитано»: собеседник не видит, что вы открыли чат. Отметить прочитанным можно, когда нужно: `max chats read` или `--mark-read`. - **Агент не напишет лишнего.** Есть профиль только для чтения, список чатов, в которые можно писать, и лимит сообщений в час. MCP-сервер может показывать вам каждое действие до того, как его выполнить. Если имя подходит к двум чатам, `max` не выбирает сам, а показывает оба. - **Сообщение не уйдёт дважды.** Если связь оборвалась во время отправки, `max` прямо говорит, что не знает, дошло ли сообщение, и даёт команду для повтора. MAX узнаёт повтор и второго сообщения не создаёт. - **Своя копия переписки.** Всё прочитанное сохраняется на вашем компьютере. По ней работает быстрый поиск по тексту сообщений, и её можно читать без интернета (`--offline`). При входе MAX присылает только то, что изменилось. Стереть копию — `max cache clear`. - **Чужой текст не управляет вашим терминалом.** Имена, названия чатов, имена файлов и сообщения пишут другие люди. Управляющие символы из них показываются как текст, имя всегда печатается в одну строку, а автодополнение подставляет только номер чата — поддельную строку переписки или команду в оболочке так не подсунуть. - **Пароль от аккаунта не лежит в файле.** Токен входа хранится в системном хранилище паролей: Keychain в macOS, Secret Service (GNOME Keyring, KWallet) в Linux, диспетчер учётных данных в Windows. В историю команд он не попадает. - **Скрипту и агенту легко разобрать ответ.** С `--json` команда отдаёт только данные, в одной и той же форме, без текста для человека вокруг. Ошибка приходит отдельно и с номером, поэтому скрипт сразу понимает, что случилось: нет входа, чат не найден или MAX не ответил вовремя. - **Разбор проблем без вашей переписки.** `--trace` показывает каждый запрос к MAX, чтобы понять, почему команда не сработала. В этой записи нет текстов, имён, телефонов и токена, поэтому её можно приложить к сообщению об ошибке. Без флага ничего не записывается. ## Под заказ Делаем автоматизацию процессов и инструменты под вашу задачу: интеграции с MAX и другими мессенджерами, ИИ-агентов, внутренние сервисы. Пишите на [info@neirox.ai](mailto:info@neirox.ai). ## Чем отличается от других Для MAX уже есть хорошие проекты, и max-cli многому у них научился. [PyMax](https://github.com/MaxApiTeam/PyMax) — самая полная библиотека для личного аккаунта; её код помог разобрать многие операции протокола. Выбирайте то, что подходит под задачу. | | max-cli | [PyMax](https://github.com/MaxApiTeam/PyMax) | [max-mcp](https://github.com/renosaza/max-mcp) | |---|:-:|:-:|:-:| | что это | программа для терминала и MCP-сервер | библиотека на Python | MCP-сервер на PyMax | | MCP-сервер и навык для агентов | ✅ | — | MCP | | ограничения для агента: только чтение, разрешённые действия, список чатов, лимит в час, подтверждение отправки | ✅ | — | — | | расшифровка голосовых в текст на вашем компьютере | ✅ | — | — | | готовые команды — не нужно писать свою программу | ✅ | — (библиотека для своего кода на Python) | — | | локальная копия с поиском и чтением без интернета | ✅ | — | — | | новые сообщения в реальном времени | ✅ `max watch` | ✅ обработчики событий | — | | отложенная отправка — уходит, даже если компьютер выключен | ✅ | ✅ | — | | выгрузка переписки в JSONL или Markdown | ✅ | — | — | | чтение, отправка текста, фото и файлов | ✅ | ✅ | ✅ | | реакции, правка, пересылка, закрепление | ✅ | ✅ | — | | удаление сообщений — у себя или у всех, с лимитом | ✅ | ✅ | — | | отметка «прочитано» по запросу | ✅ | ✅ | — | | группы и каналы: создать, вступить, участники, админы | ✅ | ✅ | чтение каналов | | контакты, профиль, другие сеансы | ✅ | ✅ | — | | отправка видео и кружков | — | ✅ | — | | отправка голосовых | — | ⚠️ в 2.4.1 не проходит ([#102](https://github.com/MaxApiTeam/PyMax/issues/102), [#103](https://github.com/MaxApiTeam/PyMax/issues/103)) | — | | опросы | — | ✅ | — | | пароль и двухфакторный вход, фото профиля | — | ✅ | — | Если нужен бот со своим аккаунтом, а не ваш личный аккаунт, — это официальный [Bot API MAX](https://dev.max.ru/docs). ## Содержание - [Установка](#установка) - [Вход](#вход) - [Использование](#использование) - [Для скриптов и агентов](#для-скриптов-и-агентов) - [Безопасность](#безопасность) - [Документация](#документация) - [Разработка](#разработка) - [Дорожная карта](#дорожная-карта) - [Лицензия](#лицензия) - [Участие](#участие) ## Установка Пакет — **`@leemour/max-cli`**, команда, которую он ставит, — **`max`**. Имя без области занято чужим пакетом с 2018 года. Запустить, ничего не устанавливая: ```sh npx @leemour/max-cli --help ``` Поставить насовсем: ```sh npm install -g @leemour/max-cli max --version ``` Нужен **Node 22 или новее**, либо **Bun 1.3+**. Работает на macOS, Linux и Windows. Подробности, переменные окружения и то, куда ложатся файлы, — [docs/installation.md](docs/installation.md). Если после установки команда `max` не находится, `npx @leemour/max-cli doctor` скажет почему и напечатает команду, которая это исправит. ## Вход `max session start qr` рисует QR-код в терминале: вы сканируете его приложением MAX, и токен входа сохраняется в системном хранилище паролей. Ещё способы — `qr-chrome`, `sms` (оба через web.max.ru в браузере) и `token` ([docs/sessions.md](docs/sessions.md)). ```sh max session start qr # QR-код в терминале max session start # или спросит токен, не отображая ввод pass show max/token | max session start # или из трубы max account show # кто вы ``` Несколько аккаунтов — несколько профилей, и профиль называется **первым словом**, а не флагом: ```sh max chats list # профиль default max personal chats list # профиль personal export MAX_PROFILE=personal # или на всю сессию оболочки ``` ## Использование ```sh max chats list --limit 5 max contacts list # люди, с кем есть личный чат max messages list 0 --limit 50 # по id чата max messages list "Иван Петров" # или по части названия max messages send 0 "текст" ``` Списки листаются одинаково везде, а история — по времени, потому что она к нему и привязана: ```sh max contacts list --limit 5 --page 2 # шестой по десятый max contacts list --all --order name # всё, по алфавиту max messages list 0 --before 2026-09-20T01:00:00Z ``` Что делала команда: ```sh max chats list --trace # показать по строке на запрос, ничего не сохраняя max chats list --record # сохранить, ничего не показывая max runs list # что делалось, новое сверху max runs show <id> ``` Локальная копия — чтобы было чем ответить без сети: ```sh max chats list --offline max cache clear ``` Полностью: [docs/usage.md](docs/usage.md). Каждая команда и каждая опция: [docs/commands.md](docs/commands.md) — эта страница собирается из самой программы, поэтому описать версию, которой не существует, она не может. ## Для скриптов и агентов ### Навык для агентов с терминалом Навык (skill) — файл с инструкцией, который агент читает перед работой. В навыке `max` описано, какие команды есть, что агент делает только по вашей просьбе и как безопасно повторить отправку. Его понимают **Claude Code**, **Codex** и **Gemini CLI**. Навык ставится одной командой и всегда той же версии, что и `max`: ```sh # Claude Code mkdir -p ~/.claude/skills/max-cli && max skill show > ~/.claude/skills/max-cli/SKILL.md # Codex и Gemini CLI — общая папка ~/.agents/skills mkdir -p ~/.agents/skills/max-cli && max skill show > ~/.agents/skills/max-cli/SKILL.md ``` Как эти агенты находят навыки: [Codex](https://learn.chatgpt.com/docs/build-skills), [Gemini CLI](https://geminicli.com/docs/cli/skills/). ### MCP-сервер для агентов без терминала Claude Desktop, Cursor и другие клиенты MCP подключаются к `max mcp` и работают с тем же аккаунтом. Без `--allow-send` агент только читает. С `--confirm-send` перед каждой отправкой вы видите чат и текст и отвечаете «да» или «нет». Подробно — [docs/mcp.md](docs/mcp.md). ```sh claude mcp add max -- max mcp # Claude Code max mcp config # запись для Claude Desktop, Cursor и других — с полными путями ``` Команды сервера — `/catch-up`, `/review`, `/reply`, `/find` — готовые просьбы: агент знает, какие инструменты вызвать и чего не делать. ### Ответы в JSON ```sh max chats list --json ``` С `--json` команда печатает только данные в JSON, без таблиц, цвета и подсказок. Так же она работает, когда её вывод читает другая программа, — например, в конвейере `max … | jq`. Любой список приходит в одной и той же форме: ```json { "items": [ … ], "page": 1, "limit": 20, "hasMore": true } ``` Ошибка приходит отдельно от данных, поэтому её нельзя принять за пустой результат: ```json {"error":{"code":"authentication_error","message":"no session for profile \"default\" — run `max session start`"}} ``` У каждой ошибки есть номер — код завершения программы. По нему скрипт решает, что делать дальше: `4` — нужно войти, `6` — чат или сообщение не найдены, `9` — MAX не ответил вовремя, `14` — неизвестно, ушло ли сообщение. Все коды — в [docs/commands.md](docs/commands.md). ## Безопасность - Токен входа — в системном хранилище паролей, не в файле и не в строке команды. - Локальная копия переписки и все служебные файлы доступны только вашему пользователю; от кражи диска защищает шифрование диска целиком. - Перед каждой отправкой, в том числе через фоновый сервер и MCP, `max` проверяет ограничения профиля и пишет строку в журнал — без текста сообщения. - MCP-сервер с `--confirm-send` показывает вам каждое действие, которое увидят другие, до того как его выполнить; `--file` не отправляет ключи и скрытые файлы без `--allow-any-file`. - Ограничения защищают от агента, которого уговорило прочитанное сообщение, но не от агента, который хочет их обойти: против такого нужна граница снаружи — песочница или отдельный пользователь. Подробно — что пишется на диск, что уходит в сеть и чего инструмент не делает никогда: [docs/security.md](docs/security.md). ## Документация - [docs/installation.md](docs/installation.md) — установка, обновление, куда что ложится - [docs/usage.md](docs/usage.md) — вход, чтение, отправка, машинный режим - [docs/sessions.md](docs/sessions.md) — токен, хранилище паролей, профили - [docs/configuration.md](docs/configuration.md) — настройки, переменные, порядок разрешения - [docs/mcp.md](docs/mcp.md) — MCP-сервер: подключение, отправка, соединение с MAX - [docs/recipes.md](docs/recipes.md) — рецепты для агентов: сводки, отчёты, долги, напоминания, расписание - [docs/diagnostics.md](docs/diagnostics.md) — `--trace`, `--record`, `max runs` - [docs/ROADMAP.md](docs/ROADMAP.md) — что планируется - [docs/security.md](docs/security.md) — что пишется на диск, а что никогда - [docs/troubleshooting.md](docs/troubleshooting.md) — по симптому: что делать, когда не работает - [docs/commands.md](docs/commands.md) — каждая команда и опция — **генерируется** из программы - [docs/protocol.md](docs/protocol.md) — каждый опкод и откуда известна его форма — **генерируется** - [docs/dev/ARCHITECTURE.md](docs/dev/ARCHITECTURE.md) — как это устроено и какие швы нельзя пересекать - [docs/dev/BACKLOG.md](docs/dev/BACKLOG.md) — что осталось Оглавление целиком — [docs/README.md](docs/README.md). ## Разработка ```sh pnpm install pnpm lint && pnpm typecheck && pnpm test pnpm build && pnpm smoke:bun # собранная команда под вторым рантаймом pnpm generate # переписать сгенерированные файлы ``` Протокол MAX неофициальный и разобран обратной инженерией: это не Bot API. Каждый опкод и форма каждого сообщения объявлены один раз в `src/spec/`, а реестр, типизированный клиент и [docs/protocol.md](docs/protocol.md) из них генерируются — и CI падает, если дерево устарело. Половина, не имеющая отношения к MAX — потоки вывода, рендерер, коды ошибок, хранилище паролей, часы, — вынесена в [`@leemour/cli-core`](https://github.com/leemour/cli-core) и общая с `braze-cli`. ## Дорожная карта Ближайшее: - голосовые сообщения и видео; - опросы: показывать при чтении и голосовать; - локальная копия по желанию — можно работать совсем без неё. Весь список — [docs/ROADMAP.md](docs/ROADMAP.md). ## Лицензия MIT — см. [LICENSE](LICENSE). ## Участие Пулл-реквесты, сообщения об ошибках и предложения приветствуются — [issues](https://github.com/leemour/max-cli/issues). Как устроен код и как его проверять — [docs/dev/ARCHITECTURE.md](docs/dev/ARCHITECTURE.md) и [docs/dev/TESTING.md](docs/dev/TESTING.md).