Skip to content

CLAUDE.md

Latest commit

 

History

History
105 lines (82 loc) · 4 KB

CLAUDE.md

File metadata and controls

105 lines (82 loc) · 4 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Telegram bot for task scheduling and calendar management, built with TypeScript and deployed on Vercel. It integrates with Google Calendar and Google Sheets for task storage and scheduling.

Architecture

Core Components

  • Telegram Webhook Handler (api/telegram-webhook.ts) - Processes incoming Telegram messages and commands
  • Task Parser (lib/task-parser.ts) - Uses OpenAI GPT-4o-mini to parse natural language task descriptions into structured tasks
  • Scheduler (lib/scheduler.ts) - Manages Google Calendar integration and time slot scheduling

Key Flow

  1. User sends natural language message to Telegram bot
  2. Webhook receives message, validates chat ID for security
  3. TaskParser uses OpenAI to extract structured task data (title, duration, priority, energy level, timing preferences)
  4. Scheduler finds optimal time slots within working hours (9-5 EST, Mon-Fri by default)
  5. Task is added to Google Calendar and logged to Google Sheets
  6. User receives confirmation with formatted task details

Development Commands

Since this is a simple TypeScript project without build scripts:

  • Install dependencies: npm install
  • Type checking: npx tsc --noEmit (no tsconfig.json present)
  • Local development: Vercel CLI for serverless function testing

Environment Variables Required

  • TELEGRAM_BOT_TOKEN - Bot token from @BotFather
  • TELEGRAM_CHAT_ID - Authorized chat ID for security
  • OPENAI_API_KEY - For natural language parsing
  • GOOGLE_SERVICE_ACCOUNT_KEY - JSON credentials for Google APIs
  • GOOGLE_CALENDAR_ID - Target calendar ID
  • GOOGLE_SHEET_ID - Task logging spreadsheet ID

Key Implementation Details

Security

  • Only responds to messages from whitelisted TELEGRAM_CHAT_ID
  • Always returns 200 to Telegram to prevent retry loops

Time Handling

  • Works in America/New_York timezone
  • Converts EDT times to UTC for calendar storage
  • Working hours: 9 AM - 5 PM, Monday-Friday (unless weekend explicitly mentioned)
  • 30-minute scheduling intervals (buffer removed as of Aug 2025 for conservative time estimates)

Task Intelligence

  • AI determines energy level based on task type (high: creative work, medium: admin, low: meetings)
  • Priority scoring combines urgency (1-5), impact (1-5), and confidence (0.1-1.0)
  • Intelligent time slot selection based on energy requirements and user preferences

Error Handling

  • Comprehensive error messages sent back to user via Telegram
  • All errors logged to console with full stack traces
  • Graceful degradation when AI parsing fails

File Structure

api/           # Vercel serverless functions
├── hello.ts                 # Simple health check endpoint
└── telegram-webhook.ts      # Main webhook handler
lib/           # Core business logic
├── task-parser.ts          # OpenAI-powered task parsing
└── scheduler.ts            # Google Calendar/Sheets integration

Future Enhancements

Multi-User Support

Goal: Extend application to support multiple users with individual preferences

User Profile Schema:

interface UserProfile {
  telegramUserId: string;
  telegramChatId: string;
  preferences: {
    bufferMinutes: number; // 0-60 minutes between events
    workingHours: { start: string; end: string };
    timezone: string;
    allowWeekends: boolean;
    defaultEnergyLevel: "high" | "medium" | "low";
    schedulingLookahead: number; // days
  };
  googleCalendarId: string;
  googleSheetId: string;
  createdAt: Date;
  updatedAt: Date;
}

Implementation Plan:

  1. Add database layer for user profiles
  2. Replace single TELEGRAM_CHAT_ID with user-based authentication
  3. Modify Scheduler.filterConflictingSlots() to accept configurable buffer from user preferences
  4. Add Telegram commands for preference management (e.g., /settings buffer 5)
  5. Design migration strategy from single-user env vars to multi-user database