Skip to content

loutab4k/OpenLinear

BranchesTags

Repository files navigation

OpenLinear

OpenLinear is a Telegram-native project tracker/status UI. It renders issue data as a compact mobile-first TUI and edits one pinned Telegram message instead of spamming the chat.

Русская версия ниже

Why

Many projects do not need another heavy work-management surface. They need a Linear-like project TUI inside Telegram: fast to scan, easy to navigate and simple to feed from scripts, CI or an existing tracker export.

OpenLinear is that Telegram layer: easy to embed, easy to replace, and small enough to understand.

What It Does

  • Renders a project status dashboard for Telegram.
  • Uses one message as an app-like container.
  • Supports pages: main, menu, category lists and issue details.
  • Keeps navigation stateless through Telegram callback_data.
  • Reads project data from JSON files.
  • Avoids private SaaS lock-in for small teams and personal projects.

Architecture In One Minute

your scripts / CI / tracker export
        │
        ▼
settings.json + projects.json + issues.json
        │
        ▼
OpenLinear renderer
        │
        ▼
one editable Telegram message

Read more:

Status

This repository is an early standalone product foundation. The current version supports JSON-backed issue data and Telegram Bot API long polling.

Planned connectors can be added later without changing the TUI layer.

Quick Start With Docker

This is the recommended path. You only need Docker and a Telegram bot.

git clone git@github.com:loutab4k/OpenLinear.git
cd OpenLinear

docker compose run --rm openlinear validate --data-dir examples/basic
docker compose run --rm openlinear render --data-dir examples/basic

Create your own data directory:

docker compose run --rm openlinear init --data-dir /data
docker compose run --rm openlinear validate --data-dir /data

Run the Telegram bot:

export OPENLINEAR_BOT_TOKEN="paste_bot_token_here"
export OPENLINEAR_CHAT_ID="paste_chat_id_here"

docker compose run --rm openlinear sync --data-dir /data
docker compose up openlinear

Optional Local Go Run

git clone git@github.com:loutab4k/OpenLinear.git
cd OpenLinear

make check
go run ./cmd/openlinear render --data-dir examples/basic

Create your own data directory:

go run ./cmd/openlinear init --data-dir openlinear
go run ./cmd/openlinear validate --data-dir openlinear
go run ./cmd/openlinear render --data-dir openlinear

Run the Telegram bot:

export OPENLINEAR_BOT_TOKEN="paste_bot_token_here"
export OPENLINEAR_CHAT_ID="paste_chat_id_here"

go run ./cmd/openlinear sync --data-dir openlinear
go run ./cmd/openlinear run --data-dir openlinear

The first sync sends a status message and stores its message_id in .openlinear/state.json. Later updates edit the same message.

Doppler

Doppler is recommended for local secret management, but OpenLinear does not require it. If you use Doppler:

doppler run -- docker compose run --rm openlinear sync --data-dir /data
doppler run -- docker compose up openlinear

Environment Variables

Variable Required Default Description
OPENLINEAR_BOT_TOKEN yes for Telegram Telegram bot token
OPENLINEAR_CHAT_ID yes for Telegram Telegram chat, group or channel ID
OPENLINEAR_STATUS_MESSAGE_ID no Existing message ID to edit
OPENLINEAR_DATA_DIR no openlinear Data directory
OPENLINEAR_STATE_PATH no .openlinear/state.json Local state file
OPENLINEAR_API_BASE_URL no https://api.telegram.org Telegram API base URL
OPENLINEAR_POLL_TIMEOUT_SECONDS no 30 Long polling timeout
OPENLINEAR_POLL_LIMIT no 50 Updates per polling request
OPENLINEAR_HTTP_TIMEOUT_SECONDS no 35 HTTP client timeout

Data Files

OpenLinear reads three JSON files:

  • settings.json controls width, labels, categories and aliases.
  • projects.json contains optional project metadata.
  • issues.json contains the actual cards.

See examples/basic and docs/schema.md.

Commands

openlinear init --data-dir openlinear
openlinear validate --data-dir openlinear
openlinear render --data-dir openlinear
openlinear render --data-dir openlinear p
openlinear sync --data-dir openlinear
openlinear run --data-dir openlinear

Integration Path

  1. Keep OpenLinear data in openlinear/.
  2. Generate or edit JSON files.
  3. Run openlinear validate.
  4. Preview the Telegram UI with openlinear render.
  5. Add Telegram secrets through env, Doppler, GitHub Actions secrets, systemd or your own secret manager.
  6. Run one sync to create the status message.
  7. Keep run alive for inline navigation.
  8. Call sync from CI or cron for scheduled refreshes.

Telegram Navigation

The main screen has only minimal controls: refresh and menu. The menu contains categories. Category pages show cards available in that section. Selecting a card opens the full issue page, similar to opening a pull request details page.

Every internal page includes navigation back to the main screen and one step back where applicable.

Development

make fmt
make test
make vet
make check

CI runs the same quality gate on GitHub Actions.

Security

Do not commit .env, .openlinear/state.json or real exported project data containing secrets. The example data is synthetic.

License

MIT

Русская версия

OpenLinear — небольшой self-hosted Telegram-интерфейс для статусов проектов. Он рендерит задачи в компактный мобильный TUI и редактирует одно закреплённое сообщение вместо спама в чат.

Зачем

Многим проектам не нужен ещё один тяжёлый work-management surface. Нужен Linear-like TUI прямо в Telegram: быстро смотреть, удобно ходить по карточкам и просто кормить данными из скриптов, CI или экспорта существующего трекера.

OpenLinear — этот Telegram-слой: легко встроить, легко заменить, достаточно мал, чтобы быстро разобраться.

Что Делает

  • Показывает статус проекта в Telegram.
  • Использует одно сообщение как контейнер приложения.
  • Поддерживает страницы: главная, меню, списки категорий и детальная карточка задачи.
  • Хранит навигацию stateless через Telegram callback_data.
  • Читает данные проекта из JSON-файлов.
  • Убирает жёсткую зависимость от SaaS-трекеров для небольших команд и личных проектов.

Архитектура За Минуту

your scripts / CI / tracker export
        │
        ▼
settings.json + projects.json + issues.json
        │
        ▼
OpenLinear renderer
        │
        ▼
one editable Telegram message

Подробнее:

Статус

Это ранний foundation отдельного продукта. Текущая версия поддерживает JSON-источник задач и Telegram Bot API через long polling.

Коннекторы к внешним трекерам можно добавить позже без переписывания TUI-слоя.

Быстрый Старт Через Docker

Это рекомендуемый путь. Нужны только Docker и Telegram-бот.

git clone git@github.com:loutab4k/OpenLinear.git
cd OpenLinear

docker compose run --rm openlinear validate --data-dir examples/basic
docker compose run --rm openlinear render --data-dir examples/basic

Создать свои файлы данных:

docker compose run --rm openlinear init --data-dir /data
docker compose run --rm openlinear validate --data-dir /data

Запустить Telegram-бота:

export OPENLINEAR_BOT_TOKEN="paste_bot_token_here"
export OPENLINEAR_CHAT_ID="paste_chat_id_here"

docker compose run --rm openlinear sync --data-dir /data
docker compose up openlinear

Опциональный Запуск Через Go

git clone git@github.com:loutab4k/OpenLinear.git
cd OpenLinear

make check
go run ./cmd/openlinear render --data-dir examples/basic

Создать свои файлы данных:

go run ./cmd/openlinear init --data-dir openlinear
go run ./cmd/openlinear validate --data-dir openlinear
go run ./cmd/openlinear render --data-dir openlinear

Запустить Telegram-бота:

export OPENLINEAR_BOT_TOKEN="paste_bot_token_here"
export OPENLINEAR_CHAT_ID="paste_chat_id_here"

go run ./cmd/openlinear sync --data-dir openlinear
go run ./cmd/openlinear run --data-dir openlinear

Первый sync отправит статус-сообщение и сохранит его message_id в .openlinear/state.json. Следующие обновления будут редактировать это же сообщение.

Doppler

Doppler рекомендуется для локального хранения секретов, но OpenLinear не требует его. Если используешь Doppler:

doppler run -- docker compose run --rm openlinear sync --data-dir /data
doppler run -- docker compose up openlinear

Переменные Окружения

Переменная Обязательна По умолчанию Назначение
OPENLINEAR_BOT_TOKEN да для Telegram токен Telegram-бота
OPENLINEAR_CHAT_ID да для Telegram ID чата, группы или канала
OPENLINEAR_STATUS_MESSAGE_ID нет существующий message ID для редактирования
OPENLINEAR_DATA_DIR нет openlinear директория данных
OPENLINEAR_STATE_PATH нет .openlinear/state.json локальный state-файл
OPENLINEAR_API_BASE_URL нет https://api.telegram.org base URL Telegram API
OPENLINEAR_POLL_TIMEOUT_SECONDS нет 30 timeout long polling
OPENLINEAR_POLL_LIMIT нет 50 число updates за polling-запрос
OPENLINEAR_HTTP_TIMEOUT_SECONDS нет 35 HTTP timeout

Файлы Данных

OpenLinear читает три JSON-файла:

  • settings.json управляет шириной, лейблами, категориями и алиасами.
  • projects.json содержит опциональные метаданные проектов.
  • issues.json содержит карточки задач.

Смотри examples/basic и docs/ru/schema.md.

Команды

openlinear init --data-dir openlinear
openlinear validate --data-dir openlinear
openlinear render --data-dir openlinear
openlinear render --data-dir openlinear p
openlinear sync --data-dir openlinear
openlinear run --data-dir openlinear

Путь Внедрения

  1. Держи данные OpenLinear в openlinear/.
  2. Генерируй или редактируй JSON-файлы.
  3. Запускай openlinear validate.
  4. Проверяй Telegram UI через openlinear render.
  5. Добавь Telegram secrets через env, Doppler, GitHub Actions secrets, systemd или свой secret manager.
  6. Один раз выполни sync, чтобы создать статус-сообщение.
  7. Держи run живым для inline-навигации.
  8. Вызывай sync из CI или cron для scheduled refresh.

Навигация В Telegram

На главной странице только минимальные действия: refresh и menu. В меню находятся категории. Внутри категории показываются карточки раздела. Нажатие на карточку открывает полную страницу задачи, по логике похожую на просмотр PR в GitHub.

На каждой внутренней странице есть переход на главную и шаг назад, где это применимо.

Разработка

make fmt
make test
make vet
make check

CI запускает тот же quality gate в GitHub Actions.

Безопасность

Не коммить .env, .openlinear/state.json и реальные экспортированные данные, если в них есть секреты. Данные в примерах синтетические.

Лицензия

MIT

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages