Telegram Goal Accountability Bot

A personal accountability bot that connects your weekly Google Sheet journal to Telegram — with Claude-powered pattern detection, repeat-goal callouts, and daily morning/evening check-ins.

---

Overview

This bot reads your weekly goals and reflections from a Google Sheet, delivers structured morning and evening nudges via Telegram, and uses Claude (Anthropic) to analyze your full multi-week history for patterns, contradictions, and genuine progress. It stores everything locally in SQLite so your data stays under your control.

---

Features

• Monday refresh — automatically pulls the current week's row from Google Sheets, stores it to memory, and sends a Claude-powered pattern analysis before your week begins
• Daily morning messages — surfaces your goals for the week and asks what you'll focus on today
• Daily evening messages — prompts reflection and progress rating on your goals
• Repeat goal detection — flags goals that have appeared 2+ weeks in a row with a direct callout
• Full history analysis — Claude reads your entire multi-week journal (all columns, not just goals) and delivers honest, specific insights
• Notification preferences — choose morning only, evening only, or both
• Pause/resume — temporarily stop all messages without losing your data
• Local SQLite memory — all data stored on your own machine or server, never externally
• Rotating log file — production-ready logging with configurable file rotation

---

Setup Prerequisites

• Python 3.11+
• A Telegram account
• A Google account with Google Sheets
• An Anthropic API key
• A Google Cloud project with the Sheets API enabled

---

Step-by-Step Setup

1. Create a Telegram Bot via BotFather

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts to name your bot
3. BotFather will give you a bot token — save it (looks like 123456789:ABCdef...)
4. Optional: send /setcommands to BotFather to register the command list:

   start - Set up the bot
   goals - See this week's goals
   reflect - Run a fresh pattern analysis
   memory - Browse past weeks
   settings - Change notification preferences
   update - Manually refresh goals from sheet
   pause - Pause all notifications
   resume - Resume notifications
   

2. Set Up Google Cloud Service Account and Enable Sheets API

1. Go to Google Cloud Console
2. Create a new project (or select an existing one)
3. Navigate to APIs & Services > Library
4. Search for "Google Sheets API" and click Enable
5. Go to APIs & Services > Credentials
6. Click Create Credentials > Service Account
7. Give it a name (e.g., goal-bot) and click Create and Continue
8. Skip optional role assignment for now, click Done
9. Click on your new service account in the list
10. Go to the Keys tab, click Add Key > Create new key, choose JSON
11. The JSON file will download automatically — this is your credentials.json
12. Move credentials.json into the project folder (same directory as main.py)
13. Note the service account email address (looks like goal-bot@your-project.iam.gserviceaccount.com)

3. Share Your Google Sheet with the Service Account

1. Open your Google Sheet
2. Click Share (top right)
3. Enter the service account email address from step 2.13
4. Set permission to Viewer (read-only is sufficient)
5. Click Send
6. Copy the Sheet ID from the URL: https://docs.google.com/spreadsheets/d/SHEET_ID_HERE/edit

4. Get an Anthropic API Key

1. Go to console.anthropic.com
2. Sign in or create an account
3. Navigate to API Keys and create a new key
4. Save the key — it starts with sk-ant-

5. Configure the .env File

cp .env.example .env

Open .env and fill in all values:

TELEGRAM_BOT_TOKEN=123456789:ABCdef_your_token_here
GOOGLE_SHEET_ID=1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
GOOGLE_CREDENTIALS_PATH=credentials.json
ANTHROPIC_API_KEY=sk-ant-your_key_here
USER_TIMEZONE=America/Los_Angeles
MORNING_HOUR=8
EVENING_HOUR=20
DB_PATH=bot_data.db
LOG_FILE=bot.log

Common timezones: America/New_York, America/Chicago, America/Denver, America/Los_Angeles, Europe/London, Europe/Paris, Asia/Tokyo

---

Running Locally

Install dependencies

cd /path/to/telegram-goal-bot
python -m venv venv
source venv/bin/activate        # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Start the bot

python main.py

You should see log output confirming:

• Database initialized
• Scheduler started (Monday refresh, morning, evening jobs)
• Bot polling started

Test it

Open Telegram, find your bot, and send /start. Then use /update to do your first sync from the sheet.

---

Optional: VPS or Railway Deployment

VPS (e.g., DigitalOcean, Linode, Hetzner)

1. Upload your project files (excluding .env — set env vars separately on the server)
2. Upload credentials.json securely (via scp or secrets manager)
3. Install Python 3.11+ and set up a virtualenv
4. Use systemd or screen/tmux to keep the bot running:

systemd service example (/etc/systemd/system/goalbot.service):

[Unit]
Description=Telegram Goal Accountability Bot
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/telegram-goal-bot
EnvironmentFile=/home/ubuntu/telegram-goal-bot/.env
ExecStart=/home/ubuntu/telegram-goal-bot/venv/bin/python main.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable goalbot
sudo systemctl start goalbot
sudo systemctl status goalbot

Railway

1. Push your project to a GitHub repo (do NOT commit .env or credentials.json)
2. Create a new Railway project and connect your repo
3. Add all environment variables in Railway's dashboard under Variables
4. For credentials.json: paste the entire JSON content as an environment variable GOOGLE_CREDENTIALS_JSON, then modify config.py and sheets.py to read it from os.getenv("GOOGLE_CREDENTIALS_JSON") and write it to a temp file at startup
5. Railway will auto-deploy on every push

---

Google Sheet Format Requirements

Your sheet should follow this structure:

Week	Goal 1	Goal 2	Goal 3	Reflection	Gratitude	Energy	Lessons
2024-03-18	Exercise 3x	Read 30min	...	...	...	High	...
2024-03-25	Exercise 3x	...	...	...	...	...	...

Key requirements:

• Row 1 must be headers (column names)
• One row per week
• Include a date column with a name containing "week", "date", or "week start" for automatic date-matching (e.g., Week, Week Start, Date, Week Of)
• Date values should be in YYYY-MM-DD or MM/DD/YYYY format
• If no date column is found, the bot will use the last row as the current week
• Goal columns should contain the word "goal" anywhere in the header (e.g., Goal 1, Weekly Goal, Top Goal) for evening rating prompts and repeat-goal detection
• All other columns (Reflection, Gratitude, Energy, Lessons, etc.) are included in the morning message and Claude analysis

Example headers that work well:

Week Start | Goal 1 | Goal 2 | Goal 3 | Reflection | Gratitude | Energy (1-5) | Lesson Learned | Notes

---

Privacy Note

All memory is stored locally in SQLite. Data is only sent to the Claude API transiently for analysis — nothing is stored externally beyond your own machine or server.

Your Google Sheets data is accessed read-only via a service account. The bot does not write anything back to your sheet.

---

Commands Reference

Command	Description
/start	Register with the bot and see the welcome message
/goals	Display this week's goals from the cached sheet data
/reflect	Run a fresh Claude analysis of your full history
/memory	Browse the last 10 weeks of stored journal data
/settings	Change notification preferences (morning/evening/both) with inline buttons
/update	Manually pull the latest data from Google Sheets and re-run analysis
/pause	Pause all scheduled notifications
/resume	Resume scheduled notifications

---

Troubleshooting

Bot doesn't respond to commands

• Confirm TELEGRAM_BOT_TOKEN is correct in .env
• Check bot.log for error messages
• Make sure the bot is running (python main.py is active)

"Missing required environment variables" error on startup

• Ensure .env exists in the project directory and all three required vars are set: TELEGRAM_BOT_TOKEN, GOOGLE_SHEET_ID, ANTHROPIC_API_KEY

Google Sheets returns empty data

• Confirm the sheet is shared with the service account email
• Verify GOOGLE_SHEET_ID matches the ID in the sheet URL
• Confirm the sheet is named Sheet1 (default) — or update the range="Sheet1" in sheets.py
• Check credentials.json is present and valid

"Could not find current week's row by date; using last row"

• This warning means no date column was matched. Either add a date column with a recognized name, format the date as YYYY-MM-DD, or the bot will fall back to using the last row

Claude analysis fails or returns an error

• Verify ANTHROPIC_API_KEY is correct and has available credits
• Check internet connectivity on the machine running the bot
• The /reflect command will show the error; try again after a moment

Scheduled messages not arriving

• Confirm USER_TIMEZONE is a valid IANA timezone string
• Check that MORNING_HOUR and EVENING_HOUR are set correctly (24h format)
• The bot must be running continuously for scheduled messages to fire
• Check bot.log around the scheduled time for any scheduler errors

Messages are too long and getting cut off

• Telegram has a 4096 character limit per message; the bot auto-splits long messages
• If /memory output is truncated, this is expected — only the last 10 weeks are shown and each entry is capped at 120 characters per field

Database errors

• Delete bot_data.db and restart to reinitialize (you will lose stored memory)
• Ensure the process has write permission in the project directory