A Telegram bot that analyzes links, messages, images, and files with AI, then saves them as structured Obsidian notes.

CI License: BSL 1.1 Python 3.10+

한국어 README

Screenshots and demo GIF coming soon. See Usage for details.

• URL Analysis -- Scrapes web pages + AI analysis to generate Obsidian notes (supports YouTube, Instagram, Threads, and other social media)
• Text Analysis -- AI organizes text into structured notes
• Image Analysis -- AI reads and analyzes images; originals are attached to the vault
• Batch File Processing -- Upload .txt files for queue-based parallel processing (3 concurrent by default)
• KakaoTalk Chat Parsing -- Auto-detects KakaoTalk chat export format and parses messages individually
• My Thoughts -- Append 내생각: to save your personal thoughts in a dedicated section with #my-thought tag
• Message Auto-Merge -- Split long texts across messages; bot waits 5s and merges them automatically (/merge to toggle)
• Content Deduplication -- Compares against existing notes to determine new/duplicate/supplement status
• Original Content Preservation -- Stores raw source content in collapsible Obsidian callouts alongside the analysis
• Structured Logging -- Rotating file logs (logs/bot.log + logs/error.log) with full stack traces
• 6-Criteria Note Evaluation -- Freshness, Practicality, Reliability, Depth, Developer Relevance, Claude Code Applicability (30 points, A-D grades)
• Claude Code Tips Extraction -- When tips are found, choose via Telegram inline buttons: Apply Globally / Create Skill / Save to Pool / Skip
• Tip Pool + Tag Matching -- Saved tips can be applied to projects via /apply-tips with tag-based matching
• Multi-language Output -- Supports Korean and English output
• Multiple AI Engines -- Choose between Claude Code CLI, Anthropic API, or OpenAI API
• Access Control -- Restrict bot usage to whitelisted Telegram user IDs
• Security Hardening -- SSRF protection, prompt injection defense, error sanitization, log masking

Telegram Message/File
 |
 v
[bot.py] Telegram Handler + Queue Processing
 |
 v
[scraper.py] Web Scraping (if URL)
 |
 v
[analyzer.py] AI Analysis (Claude CLI / Anthropic API / OpenAI API)
 |
 v
[obsidian_writer.py] Save to Obsidian Vault (with original content)
 |
 v
[evaluator.py] 6-Criteria Evaluation + Claude Code Tips Extraction
 |
 v
[Telegram Inline Buttons] Tip Processing
 |
 +--[Apply Globally]---> ~/.claude/CLAUDE.md
 +--[Create Skill]-----> ~/.claude/commands/{name}.md
 +--[Save to Pool]-----> ~/.claude/tips/{date}_{seq}.md (with tags)
 +--[Skip]-------------> Kept in Obsidian only

• Python 3.10+
• One of the following AI engines:
  • Claude Code CLI installed and authenticated (default)
  • Anthropic API key
  • OpenAI API key

git clone https://github.com/YOUR_USERNAME/telegram-obsidian-bot.git
cd telegram-obsidian-bot
pip install -r requirements.txt

Copy the example environment file and fill in your values:

cp .env.example .env

See Configuration for all available variables.

python bot.py

Or run as a background daemon with PM2 (recommended):

pm2 start ecosystem.config.cjs
pm2 save # Persist process list
pm2-startup install # Auto-start on Windows reboot

Or run in background on Windows (no console window):

start_hidden.vbs

docker compose up -d

1. Start a conversation with your bot on Telegram (/start)
2. Send any of the following:
   • URL -- Analyzes the web page and generates a note
   • Text -- Organizes the content into a structured note
   • Image -- Analyzes the image and generates a note (original attached)
   • .txt file -- Splits into items and processes in parallel (auto-detects KakaoTalk export format)
3. Add 내생각: at the end to save your personal thoughts alongside the analysis
4. Long texts split across messages are auto-merged (5s wait; /merge to toggle)
5. The bot saves a markdown note to your Obsidian vault's configured folder
6. If a Claude Code tip is detected, you get 4 inline buttons:
   • Apply Globally -- Appends to ~/.claude/CLAUDE.md
   • Create Skill -- Creates a slash command in ~/.claude/commands/
   • Save to Pool -- Saves to ~/.claude/tips/ with tags for later matching
   • Skip -- Keeps the tip in the Obsidian note only
7. Run /apply-tips in any project to get tag-matched tip recommendations from the pool

Each note is automatically evaluated on 6 criteria (1-5 points each, 30 points total):

Grades: A (25+) / B (19-24) / C (13-18) / D (12 or below)

telegram-obsidian-bot/
├── bot.py # Main bot: Telegram handlers + queue processing
├── analyzer.py # AI analysis engine (Claude CLI / Anthropic / OpenAI)
├── scraper.py # Web scraping (httpx + BeautifulSoup)
├── obsidian_writer.py # Obsidian markdown writer + original preservation + image copy
├── evaluator.py # 6-criteria evaluation + Claude Code tips + tip pool/skill creation
├── kakao_parser.py # KakaoTalk chat export parser
├── config.py # Configuration (tokens, vault path, engine selection)
├── prompts/ # Multi-language prompt templates
│ ├── __init__.py
│ ├── ko.py # Korean prompts
│ └── en.py # English prompts
├── tests/ # Tests
│ ├── __init__.py
│ └── conftest.py
├── fix_existing_notes.py # Batch cleanup of existing note frontmatter
├── backfill_originals.py # Backfill original content into existing notes
├── backfill_tags.py # Backfill tags into existing tip files
├── Dockerfile # Docker image build
├── docker-compose.yml # Docker Compose configuration
├── ecosystem.config.cjs # PM2 daemon configuration
├── start.bat # Windows startup script (with console)
├── start_hidden.vbs # Windows background startup (no console)
├── logs/ # Runtime logs (bot.log + error.log, git-ignored)
├── requirements.txt # Python dependencies
├── .env.example # Environment variable template
└── README_ko.md # Korean README

Contributions are welcome! Please open an issue or submit a pull request.

This project is licensed under the Business Source License 1.1.

• Personal and non-commercial use is permitted.
• Commercial use requires a separate license from the author.
• On 2030年04月05日, the license automatically converts to Apache 2.0.