TeleCal
A Telegram bot for conversational calorie tracking with AI-powered food estimation.
Describe what you ate in natural language, and TeleCal estimates the calories and protein using AI (OpenAI, Anthropic, or Google Gemini).
Features
- Conversational logging - Multi-turn conversations with AI clarification when needed
- Multiple AI providers - Choose between OpenAI, Anthropic Claude, or Google Gemini
- Statistics - View daily, weekly, and monthly calorie summaries
- Landing page - Public page at
/ with a Request access button that deep-links into the bot
- Mini App - Interactive charts via Telegram Web App, served at
/app
- Daily reminders - Optional notifications to log meals
- Estimation caching - Faster responses for repeated foods
- Access control - Allowlist, plus in-bot access requests that admins approve with one tap
Requirements
- Bun runtime
- Telegram Bot Token (from @BotFather)
- At least one AI provider API key
Installation
# Clone the repository
git clone https://github.com/yourusername/telecal.git
cd telecal
# Install dependencies
bun install
# Copy environment template
cp .env.example .env
# Edit .env with your configuration
Configuration
Edit .env with your settings:
# Required
TELEGRAM_BOT_TOKEN=your_bot_token
# Admin users (comma-separated Telegram IDs)
ADMIN_USERS=123456789
# AI Providers (at least one required)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...
# Web server for Mini App
APP_URL=http://localhost:3000
PORT=3000
# Feature flags
FEATURE_CACHING=true
FEATURE_LOCAL_FOOD_DB=false
Usage
# Development (with hot reload)
bun run dev
# Production
bun run start
Bot Commands
| Command | Description |
|---|
/start | Welcome message and command list |
/log | Start logging food |
/today | View today's calories and protein |
/week | View past 7 days |
/month | View past 30 days |
/edit | Edit a logged entry |
/delete | Delete a logged entry |
/settings | Change AI provider, calorie and protein goals, reminders |
/pending | View entries awaiting AI processing |
/usage | View your own AI token usage |
/admin | Manage allowed users and access requests, view AI usage and cost, backfill protein (admin only) |
Privacy
Food descriptions are sent to whichever AI provider the user has selected in
/settings (OpenAI, Anthropic, or Google) to estimate calories and protein.
The one-off /admin backfill-protein command sends the descriptions of items logged before protein tracking existed to the admin's selected provider, not each user's.
TeleCal disables server-side retention where the provider offers the option —
OpenAI calls are made with store: false, so requests are not kept in the
OpenAI organization's logs. Providers may still retain request content
separately for abuse monitoring under their own policies.
Calorie data itself is stored in TeleCal's local SQLite database.
Analytics (PostHog)
TeleCal uses PostHog Cloud (US region) for error
tracking and analytics. Decisions and reasoning are in
ADR 0001. PostHog receives:
- Error reports, with stack traces. They can include message text, for
example an AI reply that failed to parse.
- One event per AI call: the full prompt (including the food description)
and the AI's output, plus provider, model, token counts, cost and latency.
- Page views from the landing page (cookieless) and the Mini App, and
totals for access requests and approvals.
Users are identified by an HMAC-SHA256 of their Telegram ID, keyed with a
server-side secret (POSTHOG_ID_SECRET). Raw Telegram IDs, usernames and names
are never sent, and no person properties are set. Every event carries an
environment tag (production or development).
Meal text opt-out. /settings → Meal Text Sharing (on by default,
users.analytics_content) keeps a user's text out of PostHog: their
$ai_generation events drop $ai_input, $ai_output_choices and
$ai_error, and their error reports keep the error type and stack frames but
not the message. Token counts, cost and latency are still sent. Errors not
tied to a user (process-level crashes) are sent as they are.
Existing users were told with a one-time message (/admin announce-privacy);
/start and the landing page FAQ link to the same summary.
Deleting a user's data. On request, run /admin posthog-id <telegram_id>
to get the user's PostHog ID, then in PostHog open People, search for that
ID, and delete the person. Deleting a person also deletes their events.
Logging Flow
- Send
/log to start a session
- Describe what you ate (e.g., "2 eggs and toast with butter")
- AI estimates calories and protein and may ask clarifying questions
- Tap ✅ Log to save it, or ✏️ Change to describe it again (typing "yes" / "no" also works)
- Tap ✖️ Cancel, or send "cancel" at any point, to exit
Landing page assets
src/web/public/ holds the landing page's images. To regenerate them (macOS, needs Google Chrome):
- Put raw phone screenshots in
scripts/screenshots/ as shot-log, shot-today and shot-charts (any image format).
- Run
bash scripts/build-landing-assets.sh. It renders og.png from scripts/og.html and writes 720 px JPEGs.
- Commit the files in
src/web/public/.
Testing
# Run all tests
bun test
# Run tests in a specific directory
bun test src/ai
# Run a specific test file
bun test src/db/repositories/users.test.ts
Project Structure
src/
├── index.ts # Entry point
├── config.ts # Environment configuration
├── bot/ # Telegram bot
│ ├── commands/ # Command handlers
│ ├── conversations/# Log flow state machine
│ └── middleware/ # Allowlist access control
├── ai/ # AI service layer
│ ├── service.ts # Provider abstraction
│ └── providers/ # OpenAI, Anthropic, Gemini
├── db/ # SQLite database
│ ├── schema.sql # Database schema
│ └── repositories/ # Data access layer
├── web/ # Landing page and Mini App web server
│ ├── server.ts # Bun HTTP server
│ ├── auth.ts # Telegram auth validation
│ ├── public/ # Landing page images (served at /assets/*)
│ └── views/ # landing.html, app.html
└── jobs/ # Background jobs
├── reminders.ts # Daily notifications
└── retry-pending.ts # Retry failed AI calls
License
MIT
