local-agent-board
# 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
Scored across 7 tools
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.
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.
Seven tools is well-scoped for a local agent coordination board. Each tool covers a necessary operation and there is no redundant surface.
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.