Epiq: Git-трекер задач прямо в терминале

Epiq — распределённый трекер задач для терминала на основе Git.

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

Управляйте проектами через визуальную kanban-доску (канбан-доску) в терминале или через браузерный интерфейс, при этом всё состояние хранится локально, версионируется и синхронизируется через Git.

Уделяя особое внимание эргономике и удобству работы разработчика, Epiq стремится сделать управление проектами простым и безболезненным.

Epiq вырос из командной строки, но также имеет браузерный интерфейс, работающий на той же Git-основе.

Epiq — это самостоятельно развёртываемый (self-hosted) трекер задач с вдохновлённым Vim управлением, привносящий культуру разработчика в управление проектами. Он работает как в режиме ASCII-терминала, так и в виде веб-интерфейса, а состояние сохраняет в виде неизменяемого распределённого журнала событий, версионируемого и синхронизируемого через Git.

Большинство трекеров задач живут вне вашего рабочего процесса. Epiq переносит отслеживание задач туда, где вы уже работаете — в редактор.

Эти архитектурные решения дают систему со следующими свойствами:

Простая установка — никаких аккаунтов, SaaS-сервисов или внешних зависимостей
Нативность к репозиторию — задачи живут там, где и код
Работа офлайн — работает везде, с поддержкой итогового согласования (eventual consistency)
Скорость — подход «локальное прежде всего» и итоговое согласование делают редактирование в Epiq мгновенным
Портативность — запускается на локальной машине, удалённом Linux-сервере или чайнике вашей бабушки с интернетом
Управление командами — поддерживает скриптование и автоматизацию, готов к эпохе агентных систем
Версионирование — изменения отслеживаются и восстанавливаются через Git
Отслеживание задач — ведите работу через тикеты с именем, описанием, тегами, исполнителями, историей изменений и т.д.
Эргономика — быстрый UX с управлением с клавиатуры, командная строка с историей, подсветка синтаксиса и др.
Палитра команд (command palette) — нажмите ?, чтобы открыть прокручиваемый список всех доступных команд с описаниями
Путешествие во времени (time travel) — просмотрите состояние приложения час, неделю или год назад
Фильтрация — запрашивайте задачи по описанию, тегам, исполнителям и т.д.
Автодополнение — меньше ввода, больше концентрации, повторное использование предыдущих команд
Многопользовательский режим — совместная синхронизация через Git
Отслеживаемый журнал событий — состояние является полной историей всех когда-либо сделанных изменений
Браузерный GUI — графический интерфейс на той же Git-основе
Интеграция с MCP — поддержка Model Context Protocol для взаимодействия с агентами

Установка

Через скрипт

curl -fsSL https://raw.githubusercontent.com/ljtn/epiq/main/install.sh | sh

По умолчанию устанавливается в ~/.local/bin. Можно переопределить через переменную окружения EPIQ_INSTALL_DIR (или XDG_BIN_HOME); для фиксации конкретной версии используйте EPIQ_VERSION=v1.0.0.

Через npm

npm install --global epiq

Проверка установки

epiq --version

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

Убедитесь, что вы находитесь внутри Git-репозитория:

# При необходимости:
git init
# Для совместной работы используйте репозиторий с удалённым источником (например, клонированный с GitHub)

Запустите:

epiq

При первом запуске откроется интерактивный мастер настройки, который займёт около 30 секунд.

Вот и всё!

После настройки проекта можно запустить браузерный интерфейс командой:

epiq gui

Что создаёт мастер настройки

Мастер установки создаёт: пользовательскую конфигурацию в ~/.epiq-global/config.json.

Инициализация создаёт:

Определение проекта в ./.epiq/project.json
Авторитетное Git-состояние в ~/.epiq-global/worktrees/<id>
Обновляет ваш .gitignore, чтобы исключить локальный каталог .epiq/log/

Epiq автоматически управляет выделенной веткой Git и рабочим деревом (worktree) как единственным источником истины для синхронизации.

Работа с Epiq

Прежде всего: помощь всегда доступна по команде :help.
Нажмите ? в любой момент, чтобы открыть палитру команд со всеми доступными командами и описаниями.
Навигация выполняется с клавиатуры — стрелками или клавишами h j k l.
Войдите в узел клавишей enter, выйдите из контекста — q или esc.
Нажав :, вы переходите в режим командной строки, где можно вводить команды.
Команды контекстно-зависимы: например, :close доступна только для задач.
Создавайте узлы командой :new issue|swimlane|board <Название нового узла>.
Оставляйте комментарии к задачам командой :comment <текст>. Комментарии можно редактировать или удалять обычными командами :edit … и :delete.
Перемещайте узлы клавишей m. Это переводит вас в режим перемещения: навигируйте как обычно, перейдите в нужное место и снова нажмите m для подтверждения.
Применяйте фильтры командой filter с указанием цели и квалификатора. Чтобы отфильтровать все задачи с тегом prio, введите :filter tag prio и нажмите enter. Несколько команд фильтрации можно комбинировать последовательно.

Сбросить все фильтры: :filter clear
Закрывайте задачи командой :close. Задача перемещается на специальную доску Closed, до которой можно добраться, поднявшись вверх (нажав q несколько раз).
Повторно открыть задачу можно, перейдя на доску Closed, выбрав задачу и введя команду :reopen. Это вернёт задачу на её предыдущее место.
Профессиональный совет: как и в любом терминале — если нужно повторять одно и то же действие, перейдите в режим командной строки и нажмите стрелку вверх, чтобы получить последнюю выполненную команду. Очень удобно при создании задач с похожими именами или добавлении одного тега к множеству тикетов.

Интеграция с MCP

Epiq предоставляет сервер MCP (Model Context Protocol) для взаимодействия агентов с трекером, что позволяет легко встраивать его в современные агентные фреймворки. Сервер доступен через бинарный файл epiq-mcp, входящий в состав пакета.

Надёжный способ зарегистрировать сервер — команда claude mcp add: она сама запишет нужные данные в правильный конфигурационный файл, и вам не придётся вручную редактировать JSON:

# Доступно везде (рекомендуется)
claude mcp add --scope user epiq -- npx -y -p epiq epiq-mcp
# Или только в текущем проекте
claude mcp add epiq -- npx -y -p epiq epiq-mcp

Используйте --scope user, чтобы Epiq был доступен в любом каталоге; без этого флага регистрация действует только для текущего проекта. Проверьте подключение командой claude mcp list (должно отобразиться epiq … ✔ Connected). MCP-серверы загружаются при старте, поэтому перезапустите Claude Code после добавления сервера — только тогда его инструменты станут доступны.

Для клиентов с ручной настройкой добавьте следующее в MCP-конфигурацию клиента — обратите внимание, это не тот же файл, что ~/.claude.json у Claude Code; Claude Desktop использует claude_desktop_config.json:

{
  "mcpServers": {
    "epiq": {
      "command": "npx",
      "args": ["-y", "-p", "epiq", "epiq-mcp"]
    }
  }
}

После регистрации агенты смогут взаимодействовать с вашим локальным экземпляром Epiq через MCP.

Синхронизация через Git

Epiq работает с Git в фоновом режиме — никаких ручных Git-команд не требуется. Команда :sync синхронизирует изменения между локальным состоянием (хранящимся в ~/.epiq-global/worktrees/<id>/) и удалённым. Благодаря Git worktree синхронизация не затрагивает ваш обычный рабочий процесс. Метаданные отслеживания проекта хранятся в .epiq/project.json.

Распределённая конкурентность и согласованность

Epiq спроектирован для надёжной работы в распределённой Git-среде, где несколько пользователей могут обновлять состояние одновременно. Вместо изменения общих файлов Epiq использует событийно-ориентированную (event-sourced) модель, которая предотвращает конфликты слияния и делает параллельные изменения предсказуемыми.

Все изменения сохраняются как события только для добавления (append-only events) в файлах, принадлежащих конкретному пользователю, а не путём модификации общего файла состояния. Это исключает правку одних и тех же строк на месте и значительно снижает вероятность конфликтов Git.

Текущее состояние восстанавливается в памяти путём воспроизведения слияния всех пользовательских журналов в детерминированном порядке.

События используют составной идентификатор из сортируемых по времени ID (ULID) и ссылки на последнее известное событие («edge»). При создании события добавляются относительно последнего известного события. Если несколько событий имеют одну точку привязки, их относительный порядок определяется по временным ID.

Такой подход:

Обеспечивает стабильный и воспроизводимый порядок на разных машинах
Ограничивает влияние возможного расхождения часов (clock drift) незначительными локальными отличиями в порядке
Гарантирует, что параллельные обновления сходятся к одному состоянию

Epiq разрешает конкурентные изменения на уровне событий:

События по возможности разработаны идемпотентными (idempotent)
При конфликтах приоритет имеют более поздние события
Каждый пользователь пишет в свой файл журнала событий
Слияния в Git превращаются в тривиальное объединение изменений из независимых файлов

Epiq следует модели «локальное прежде всего» (local-first):

Все операции применяются мгновенно на локальной машине
Синхронизация происходит явно (:sync) или автоматически
При расхождении историй слияние журналов событий и их воспроизведение приводит к согласованному состоянию

Частая синхронизация сокращает расхождения и делает систему предсказуемой.