Skip to main content
Glama
README.md
# Local Agent Board

Локальная почта и блокировки тем для AI-агентов, которые работают над одним проектом в разных сессиях или Git worktree. Один агент может сообщить, что задача готова к проверке, а другой может увидеть, свободна ли нужная область работы. Сообщения и отметки о прочтении сохраняются в SQLite между запусками. Для человека доступна веб-доска с блокировками и 25 последними сообщениями.

Проект основан на сценариях и устройстве кода [форка agent-exchange](https://github.com/pravoslavnaacerkovukrainy-tech/agent-exchange/tree/13f073533dee461c846e7bc9e35e7454d8dce453). Хранилище, интерфейсы и веб-доска реализованы отдельно на Python 3.9+ и стандартной библиотеке. Исходное уведомление MIT сохранено в [LICENSE](LICENSE).

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

Из каталога проекта выполните команды. Они используют временную базу и данные для примера.

```sh
board_dir="$(mktemp -d)"
python3 -m agent_board --data "$board_dir" --agent Codex lock demo/tests --ttl 900 --note "Проверяю тесты"
python3 -m agent_board --data "$board_dir" --agent Codex post Reviewer demo/tests "Проверь отчёт."
python3 -m agent_board --data "$board_dir" --agent Reviewer inbox --unread
python3 -m agent_board --data "$board_dir" --agent Reviewer ack 1
python3 -m agent_board --data "$board_dir" serve
```

Последняя команда напечатает адрес [локальной доски](http://127.0.0.1:9781/). Откройте его в браузере и нажимайте «Обновить», чтобы перечитать состояние. Для Markdown выполните `python3 -m agent_board --data "$board_dir" snapshot`.

В постоянной работе укажите один абсолютный путь `--data` на проект и передавайте его всем участникам, включая процессы из других worktree. По умолчанию используется `.agent-board` в текущем каталоге. Команда `python3 -m agent_board --help` перечисляет операции. После установки через `python3 -m pip install .` с актуальным pip доступна команда `local-agent-board`.

## Подключение MCP

Для клиента с конфигурацией `mcpServers` добавьте сервер по образцу. Укажите абсолютные пути к Python, каталогу исходников и общей папке данных. Во второй конфигурации поменяйте значение `--agent` на `Reviewer`, сохранив тот же путь `--data`. Сервер поддерживает MCP stdio версий 2025-11-25 и 2025-06-18. [Спецификация транспорта](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)

```json
{
  "mcpServers": {
    "local-agent-board": {
      "command": "/usr/bin/python3",
      "args": ["-m", "agent_board", "--data", "/absolute/path/to/project-board", "--agent", "Codex", "mcp"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/local-agent-board"
      }
    }
  }
}
```

| Инструмент MCP | Действие |
| --- | --- |
| `post` | Отправляет текст одному получателю или всем через адрес `*`. |
| `inbox` | Показывает входящие, начиная с новых. Поддерживает `unread`, фильтр `topic` и переход к старым сообщениям через `before` из значения `next_before`. |
| `ack` | Отмечает список `ids` как прочитанный для текущего агента. |
| `lock` | Занимает тему на `ttl` секунд и возвращает токен. |
| `renew` | Продлевает действующую блокировку с её токеном. |
| `unlock` | Освобождает блокировку с её токеном. |
| `lock_status` | Показывает владельцев, сроки и истёкшие блокировки. |

## Как устроен обмен

- Имена агентов регистрозависимы. Тема нормализуется по регистру и пробелам. Удобно договориться о едином формате, например `web/review`.
- Рассылка `*` появляется во входящих каждого участника. Отметка о прочтении хранится отдельно для каждого имени.
- Срок блокировки по умолчанию составляет 30 минут. Для продления или освобождения используйте токен из ответа `lock`. После повторного захвата старый токен теряет силу, даже если оба процесса работают под одним именем. При захвате истёкшей блокировки прежний владелец получает внутреннее уведомление.
- CLI и MCP используют одно транзакционное хранилище. Веб-доска привязана к `127.0.0.1` и показывает только состояние базы. Отдельная команда `snapshot` печатает Markdown в stdout.

Блокировки действуют по соглашению участников. Изменения в Git и файловой системе остаются под контролем каждого агента. Доска рассчитана на доверенные процессы одного пользователя ОС. Имя задаётся при запуске процесса, а пользователь с доступом к файлу SQLite может прочитать данные. Для новой доски требуется своя папка. Схема SQLite отличается от схемы исходного форка.

## Проверка

```sh
python3 -m unittest discover -s tests -v
```

Тесты используют временные каталоги и проверяют доставку, отметки о прочтении, истечение и конкурентный захват блокировок, обмен через CLI и MCP, а также доступ к веб-доске.

TDQS

B3.4/5.0

Scored across 7 tools

Disambiguation5/5

Each tool maps to a clearly distinct action in one of two domains: lease management (lock, renew, unlock, lock_status) and messaging (post, inbox, ack). No two tools can reasonably be confused for the same operation.

Naming Consistency4/5

Most names are short action verbs (lock, renew, unlock, post, ack), with two noun-oriented names (lock_status, inbox). The convention is mostly predictable but not uniformly verb_noun.

Tool Count5/5

Seven tools is well-scoped for a local agent coordination board. Each tool covers a necessary operation and there is no redundant surface.

Completeness4/5

The lease lifecycle is fully covered (acquire, renew, release, inspect), and messaging supports send, read, and acknowledge. Minor gaps exist around retracting/editing posted messages or listing known agents, but core workflows are complete.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues