Repository: ai-bot | Telegram bot: Kalverion_bot
Tired of finance apps that only tell you how you already spent your money? I built Kalverion Bot to focus on what happens next. Unlike most trackers, this is a self-hosted tool you run on your own infrastructure (like DigitalOcean), giving you control over your financial data.
⭐ If you find this project useful, please consider giving it a star ⭐
|
📉 Overdraft Warnings: Predictive alerts based on upcoming bills and current balance. |
📖 Commands • 💬 Natural Language • ⚡ Install • ⭐ Star the repo
/add coffee 5
/transfer 100
/debts_list
/debt_compare_graph 100
/forecast_graph
/future_graph 24
/milestones_graph
I started this project after getting hit with overdraft fees and realizing I did not have a clear picture of my short-term cashflow.
Most finance apps are good at showing what already happened. This bot focuses on what will happen next — forecasting balances, warning about danger windows, tracking recurring expenses, and helping you make better decisions before problems happen.
Clone the repo and install dependencies:
git clone https://github.com/bisbeebucky/ai-bot
cd ai-bot
npm install
Open Telegram and search for @BotFather, then run:
/newbotBotFather will give you a bot token.
export TELEGRAM_BOT_TOKEN=YOUR_TOKEN
export OPENROUTER_API_KEY=YOUR_KEY
If running on Digital Ocean set these in ecosystem.config.cjs
node index.js
For DigitalOcean / OpenClaw deployment notes, see INSTALL.md.
OpenClaw can connect your Telegram bot without pairing in some setups.
In the current deployment flow, the important piece is making your Telegram token available to the runtime, often through ecosystem.config.cjs.
The bot can interpret plain English messages and convert them into balanced double-entry ledger transactions.
I got paid 5000 windfall
bought groceries for 35
paid rent 1200
5 on coffee
It also supports read-only natural-language shortcuts for common finance questions. See NATURAL_LANGUAGE.md.
Kalverion_bot uses AI as a natural-language interpretation and response layer, not as the source of accounting truth.
The model helps with things like:
- understanding plain-English finance messages
- mapping messages to known bot actions
- sorting expenses into categories
- answering read-only finance questions
- generating clearer explanations
The bot’s actual financial state and calculations still come from the app itself:
- ledger-backed balances and transactions
- SQLite data
- forecast logic
- recurring cashflow logic
- debt logic
- shared query and service-layer code
In other words:
- AI handles interpretation
- the bot’s code handles accounting truth
This keeps the system more predictable, auditable, and trustworthy than letting a model write directly to the database or generate raw SQL.
Kalverion_bot simulates your future balance based on current transactions, recurring bills, and debt payments.
⚠️ Danger Window
Current Balance: $576.05
Lowest Balance: $3.67
Date: 2026-04-03
Trigger: Rent
Status: ⚠️ Tight
The bot warns you before an overdraft occurs.
Current release: v1.3.0
- Added natural-language read-only prompts for common finance questions
- Refactored shared query logic into service layers
- Added shared forecast and recurring query services
- Added automated tests for query, forecast, recurring, and simulation logic
See RELEASE.md for release history.
⭐ If this project helps you manage your finances or avoid overdrafts, consider giving it a star.
📖 Commands • 💬 Natural Language • 🏷 Release Notes • ⭐ Star the repo