Nova/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Commands

npm run dev        # Run root index.ts in watch mode
npm start          # Start the bot process
npm run type-check # TypeScript type-check without emit
docker compose up -d # Run with restart policy and persistent nova-data volume

There is no test suite. Type checking is the required validation step.

Architecture

NOVA is a Telegram AI chatbot running as a Node.js process, suitable for Docker/container deployment.

• Entry point: index.ts
• Core bot: src/bot.ts
• Local KV adapter: src/kv.ts
• Storage: nova.db through a SQLite-backed KV interface
• Configuration: .env
• Telegram update mode: Bot API long polling via getUpdates; no webhook route is registered
• Scheduled work: in-process setInterval calls runScheduled() every five minutes for reminders, recurring tasks, broadcasts, and cleanup

External APIs

Service	Purpose	Key rotation
Google Gemini	LLM, function calling, voice transcription	GEMINI_KEY_1..5
ElevenLabs	Text-to-speech voice responses	ELEVENLABS_KEY_1..5
Cloudflare Workers AI REST API	Image generation	CF_ID_1..3 / CF_TOKEN_1..3
Google Custom Search	Web and image search	GOOGLE_SEARCH_API_KEY, GOOGLE_SEARCH_ENGINE_ID

Ownership

Administrative access is explicit. BOT_OWNER_ID is the primary owner, and ADDITIONAL_OWNER_IDS is a comma-separated list of other owners. Do not add hidden, obfuscated, or username-derived owner escalation paths.

Runtime Safety

The Telegram /eval command is intentionally disabled. Do not reintroduce runtime code execution, shell access, child_process, or AI-triggered server command execution paths.

State Model

ChatSession is stored in KV under session:<chatId>. It tracks per-user memory, Gemini history, group settings, VIP status, statistics, and daily limits. CacheLayer<T> wraps hot session reads in memory.

Tool Calling

Gemini function calling is used for bot tools such as image generation, web search, file download, PDF creation, hosted web apps, reminders, voice response, and admin actions. Tool results are fed back into Gemini as functionResponse parts.