First Steps¶

Your first steps with tg-note after installation.

1. Get Your Telegram Bot Token¶

Create a Bot with BotFather¶

Open Telegram and search for @BotFather
Start a chat and send /newbot
Follow the prompts:
Choose a name for your bot (e.g., "My Knowledge Bot")
Choose a username (must end in "bot", e.g., "my_knowledge_bot")
BotFather will give you a token - save it securely!

Example token format:

1234567890:ABCdefGHIjklMNOpqrsTUVwxyz12345678

Add Token to Configuration¶

Add your token to .env:

TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz12345678

2. Get Your User ID (Optional)¶

If you want to restrict bot access to only yourself:

Open Telegram and search for @userinfobot
Start a chat and send any message
Bot will reply with your user info
Copy your User ID

Add to config.yaml:

ALLOWED_USER_IDS: "123456789"  # Your user ID

3. Setup Knowledge Base¶

Option A: Local Knowledge Base¶

Create a new local Git repository:

mkdir my-knowledge-base
cd my-knowledge-base
git init
git add .
git commit -m "Initial commit"
cd ..

Update config.yaml:

KB_PATH: ./my-knowledge-base
KB_GIT_ENABLED: true
KB_GIT_AUTO_PUSH: false  # No remote yet

Option B: GitHub Knowledge Base¶

Create a new repository on GitHub (e.g., my-kb)
Clone it locally:

git clone https://github.com/yourusername/my-kb.git

Update config.yaml:

KB_PATH: ./my-kb
KB_GIT_ENABLED: true
KB_GIT_AUTO_PUSH: true
KB_GIT_REMOTE: origin
KB_GIT_BRANCH: main

4. Start the Bot¶

poetry run python main.py

Expected output:

INFO - Starting tg-note bot...
INFO - Configuration validated successfully
INFO - Processing tracker initialized
INFO - Repository manager initialized
INFO - Telegram bot started successfully
INFO - Bot initialization completed
INFO - Press Ctrl+C to stop

5. Initialize Bot in Telegram¶

Open Telegram, find your bot, and send:

/start

Bot should reply with a welcome message!

6. Configure Knowledge Base in Telegram¶

Tell the bot where to save notes:

/setkb my-notes

Or use a GitHub repo:

/setkb https://github.com/yourusername/my-kb

7. Send Your First Message¶

Send or forward any message to the bot. Examples:

Plain text message
Forwarded message from a channel
Article link
Multiple messages

The bot will process and save it to your knowledge base!

8. Check Your Knowledge Base¶

Look in your KB directory:

ls -la my-knowledge-base/

You should see:

topics/
├── general/
│   └── 2025-10-03-your-first-note.md
└── index.md

9. Verify Git Commits¶

cd my-knowledge-base
git log --oneline

You should see automatic commits!

10. Explore Bot Commands¶

Try these commands:

/help      # Show all commands
/kb        # Show KB info
/status    # Show statistics
/settings  # Open settings menu

Next Steps¶

Learn All Commands

Master all bot commands and features

Bot Commands
Upgrade Your Agent

Install Qwen Code CLI for better AI processing

Agent Setup
Customize Settings

Configure bot behavior via Telegram

Settings Guide
Organize Your KB

Learn KB structure and organization

KB Setup