$gjoko-ai-agent

gjoko-ai-agent

Personal AI assistant for Telegram, Notion notes, Gmail summaries, weather, and small automations. Self-hosted, open source.

// Deploy, configure env vars, connect the modules you want.
// Cron runs every 30min. Useful updates hit Telegram. * prefix saves to Notion.

→ Get started★ Star on GitHub

## Features

.assistant

Send any message to your Telegram bot and get OpenAI-powered replies for questions, drafting, and brainstorming.

.notion

Prefix any Telegram message with * to save as a note, use `*<name>,` to save to a subpage, or reply with `*` to save the replied message.

.gmail

Connect up to 5 Gmail accounts via read-only OAuth2 and summarize unread messages with OpenAI.

.telegram

Send summaries, assistant replies, notes confirmations, tests, and weather reports back to your Telegram chat.

.weather

At 07:30 and 20:30, sends a short Vransko forecast with practical clothing advice for you and the kids.

.calendar

Every evening at 20:00, sends tomorrow's calendar events, holidays, and birthdays to Telegram. Add events from Telegram with title, date, and time.

.cron

Cron-based automation runs recurring work every 30 minutes. Deploy on Vercel or use any external cron service.

## How it works

Telegram Assistant

Send any message to your bot. It's forwarded to OpenAI, and the reply comes back to you in Telegram. Use it for questions, drafting, or brainstorming.

// example:

You: "Draft a 2-line reply declining the meeting." Bot: "Thank you for the invite. I won't be able to attend..."

Notion Notes

Messages that start with * (asterisk) are saved as notes in your Notion page. Use `*<name>,` to save to a subpage in Notes, or reply with `*` to capture the replied message as a note.

// example:

*Call back John re: project scope by Friday -> appended to main Notes. *Work, Review Q1 roadmap -> saved to subpage "Work" under Notes.

Gmail Summaries

The agent connects to up to 5 Gmail accounts via OAuth2. It reads unread messages from inbox, social, and promotions, skips spam, and summarizes relevant mail.

// example:

A long newsletter becomes: "Q4 Product Launch Recap" - Key features shipped · Beta feedback summary · Next steps.

Telegram Delivery

Summaries are sent to your Telegram chat. Social emails get category prefixes and promotions are marked separately, so you can skim by type at a glance.

// example:

You receive a compact summary in Telegram with sender, subject, title, and a few bullets.

Daily Weather Report

The cron route checks local Ljubljana time and sends today's Vransko forecast at 07:30 and tomorrow's forecast at 20:30.

// example:

Vransko tomorrow: 8-16°C, rain 50%, wind 18 km/h. Dress: warm layers; waterproof jackets for the kids.

Daily Calendar Report

The same cron route reads Google Calendar with read-only OAuth and sends tomorrow's events, holidays, and birthdays to Telegram.

// example:

Tomorrow (2026-05-14) Events: 09:00 Standup. Holidays: Ascension Day. Birthdays: Ana's birthday.

Smart Scheduling

A cron job runs every 30 minutes (or on your schedule). It triggers enabled recurring work, including email checks and weather reports.

// example:

At 9:00, 9:30, 10:00... the agent checks enabled modules and sends useful updates to Telegram.

## Config

Filtering

  • -inbox, social, promotions — unread only
  • -skips spam
  • -skips < 5 char emails
  • -👥 social · 🏷️ promotions
  • -optional LABEL_FILTER, EXCLUDE_CATEGORIES, sender lists

Security

  • -read-only Gmail
  • -password-protected utils
  • -webhook secret validation
  • -MAX_EMAILS_PER_RUN
  • -5 accounts / 1 OAuth client
  • -no DB — env vars only

## Setup & Status

Account Status

▌Checking config...

Quick Actions

Reconnect Google Calendar→Set Telegram Webhook→Telegram Test→Check Mail Now→

## Environment Variables

Set in .env.local or deployment env. See .env.example.

.env
GOOGLE_CLIENT_ID# OAuth client from Google Cloud Console(Email summaries)
GOOGLE_CLIENT_SECRET# OAuth secret from Google Cloud Console(Email summaries)
GOOGLE_REFRESH_TOKEN# One per Google account (use Setup Gmail)(Email & calendar)
GOOGLE_CALENDAR_IDS# Optional comma-separated extra calendar IDs(Calendar report)
GOOGLE_HOLIDAY_CALENDAR_ID# Optional; defaults to Slovenian holidays(Calendar report)
GOOGLE_BIRTHDAY_CALENDAR_ID# Optional; defaults to Google birthdays(Calendar report)
OPENAI_API_KEY# API key from platform.openai.com(Summaries & Assistant)
OPENAI_MODEL# Optional; default gpt-5-nano(AI)
TELEGRAM_BOT_TOKEN# Create via @BotFather on Telegram(Telegram)
TELEGRAM_CHAT_ID# Get from @userinfobot on Telegram(Telegram)
NOTION_API_KEY# Notion integration secret(Notion notes)
NOTION_NOTES_PAGE_ID# Target page ID or URL(Notion notes)
APP_URL# e.g. https://yourdomain.com(Webhook & OAuth)
TEST_PASSWORD# Password for utility pages(Setup pages)
MAX_EMAILS_PER_RUN# Optional; default 5(Email summaries)
LABEL_FILTER# Optional; e.g. IMPORTANT(Email summaries)
EXCLUDE_CATEGORIES# Optional; e.g. promotions or promotions,social(Email summaries)
EMAIL_SUMMARY_ALLOWED_SENDERS# Optional comma-separated sender allow-list(Email summaries)
EMAIL_SUMMARY_IGNORED_SENDERS# Optional comma-separated sender block-list(Email summaries)
TELEGRAM_WEBHOOK_SECRET# Optional header secret for webhook(Webhook)
CRON_SECRET# Optional bearer token for cron(Scheduling)

If you find this useful, star it on GitHub.

★ Star on GitHub