# iapeer

**Русский** · [English](../README.md)

iapeer — основа мультиагентной системы на одном хосте. Он держит реестр участников, единый демон-роутер для обмена сообщениями между ними и набор команд, которыми участниками управляют: создают, запускают, усыпляют, перезапускают, подключают к внешним каналам.

Участник системы называется **пиром**. Пиром может быть AI-агент (Claude, Codex), человек (через Telegram) или служебный процесс (планировщик, наблюдатель). iapeer не различает их по природе на уровне транспорта — все они адресуются одинаково и обмениваются сообщениями через один протокол.

```text
   send_to_peer (от любого пира)
        │
        ▼
   ┌────────────────────────┐
   │      демон-роутер        │   работает постоянно
   │   поиск · доставка       │   читает peers-profiles.json (реестр)
   └────────────────────────┘
        │
        ▼
   пир-получатель  (если спит — поднимет)
```

## Что это решает

Когда на машине живёт не один агент, а команда — у каждого своя роль, своя рабочая папка, свой рантайм, — возникают задачи, которых у одиночного агента нет:

- **Адресация.** Как агенту A отправить сообщение агенту B, не зная, запущен ли тот прямо сейчас.
- **Присутствие.** Держать ли каждого агента в памяти постоянно (дорого) или поднимать по требованию (нужен кто-то, кто поднимет).
- **Идентичность.** Один и тот же логический агент может присутствовать в разных рантаймах (сегодня Claude, завтра Codex) — система должна понимать, что это один и тот же пир.
- **Жизненный цикл.** Кто усыпит простаивающего агента, кто перезапустит зависшего, кто не даст упавшему агенту войти в цикл перезапусков.

iapeer берёт это на себя. Агенту достаточно вызвать `send_to_peer(<имя>, <текст>)` — остальное делает демон: найдёт получателя в реестре, проверит, жив ли он, доставит сообщение в живую сессию или поднимет спящего и доставит после пробуждения.

## Быстрый старт

Требования: **macOS** (управление процессами идёт через launchd), **[bun](https://bun.sh)** на `PATH` и хотя бы один агентский рантайм — Claude Code или Codex CLI.

```bash
# 1. Установите ядро — бинарь, раскладку ~/.iapeer и плист демона
npx @agfpd/iapeer

# 2. Подготовьте хост — onboard стартует демон, регистрирует marketplace,
#    ставит notifier, Telegram и память
iapeer onboard

# 3. Создайте первого агента
iapeer create assistant --runtime claude

# 4. Отправьте сообщение — демон поднимет сессию, если её нет
iapeer send assistant --message "привет, ты на связи?"
```

Подробный разбор каждого шага — в [02 — Быстрый старт](02-быстрый-старт.md).

## Документация

Разделы выстроены слоями: от «поставить и пользоваться» к «понять архитектуру и расширять».

**Введение**
- [01 — Обзор](01-обзор.md) — что такое iapeer и из чего он состоит
- [02 — Быстрый старт](02-быстрый-старт.md) — установка, онбординг, первый пир, первое сообщение

**Концепции**
- [03 — Пиры, рантаймы, идентичность](03-пиры-рантаймы-идентичность.md)
- [04 — Жизненный цикл и демон](04-жизненный-цикл-и-демон.md)
- [05 — Идентичность и системный промпт](05-системный-промпт.md)
- [06 — Хранение](06-хранение.md)

**Руководства**
- [07 — Установка и обновление](07-установка-и-обновление.md)
- [08 — Управление пирами](08-управление-пирами.md)
- [09 — Рантаймы](09-рантаймы.md)
- [10 — Обмен сообщениями](10-обмен-сообщениями.md)
- [11 — Расширения и память](11-расширения-и-память.md)

**Справочник**
- [12 — CLI](12-cli-reference.md) — все команды с флагами
- [13 — Архитектура и контракт](13-архитектура-и-контракт.md) — для разработчиков плагинов и рантайм-пакетов
- [14 — Конфигурация и журналы](14-конфигурация-и-журналы.md) — переменные окружения, журналы, диагностика
- [15 — Fleet API](15-fleet-api.md) — HTTP-поверхность демона для операторских клиентов (дашборды, tray-приложения, скрипты): снапшот, поток событий, команды
- [16 — Трей](16-tray.md) — дашборд флота в меню-баре macOS (плагин SwiftBar), первый внешний клиент Fleet API
- [17 — Подтверждение человеком](17-approval.md) — режим gated/yolo на пира: маршрутизация блокирующих подтверждений рантайма человеку через брокер демона (перехват хуком, брокер, Fleet API + CLI)
- [18 — Origin guard](18-origin-guard.md) — ответ агента человеку обязан целиться в канал, из которого человек писал: модель взведённой пары, удержание, `confirm-send`

## Статус

Построено и работает: единый демон-роутер, протокол обмена сообщениями (IAP), реестр пиров, идентичность и её ABI, жизненный цикл (пробуждение, усыпление, перезапуск, надзор), рантайм-адаптеры для Claude, Codex, Telegram и notifier, установка и онбординг хоста, подключение Telegram, слот памяти и capability-плагины.

Запланировано поверх основы: граф совместимости пакетов, доктор здоровья всей команды и интерактивный интерфейс координации. Пока этих надстроек нет, координационные операции живут в CLI `iapeer`.

## Планы

Более крупные направления, запланированы и ещё не сделаны:

- **Веб-интерфейс** — работа с командой через браузер.
- **Поддержка Linux** — сегодня iapeer работает на macOS; Linux в планах.
- **Дополнительные агентские рантаймы** — `opencode` и `antigravity`, два новых CLI-рантайма наряду с Claude Code и Codex.
- **Рантайм Discord** — рантайм присутствия человека для Discord, наряду с Telegram.
- **Гейт разрешений** — более тонкий контроль над тем, что агенту позволено делать.
- **Апрув разрешений через Telegram** — подтверждать запросы разрешений агента прямо из чата; сегодня разрешения выданы автоматически флагами.

Платформа сейчас — только macOS/launchd. Поддержка Linux (systemd) и Windows не реализована.