explaingit

dominatos/actual-expense-logger

Analysis updated 2026-05-18

★ 4TypeScriptAudience · developerComplexity · 3/5Setup · moderate

TLDR

A Telegram bot that lets you quickly log expenses into a self-hosted Actual Budget instance by sending a chat message.

Mindmap

mindmap
  root((actual-expense-logger))
    What it does
      Logs expenses via Telegram chat
      Parses US and European numbers
      Picks category via chat buttons
    Tech stack
      TypeScript
      Docker and Docker Compose
      Actual Budget API
    Key features
      Multiple account support
      Automatic backups before writes
      Duplicate submission guard
    Use cases
      Log expenses on the go from Telegram
      Run a private self hosted budgeting bot
      Restrict bot access to specific users
    Audience
      Actual Budget users
      Self hosting hobbyists
      Developers wanting a Telegram bot example

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Log everyday expenses into Actual Budget by chatting with a Telegram bot.

USE CASE 2

Manage expenses across multiple named budget accounts from one bot.

USE CASE 3

Restrict who can use the bot to a specific list of Telegram users.

USE CASE 4

Self host the bot with Docker alongside an existing Actual Budget server.

What is it built with?

TypeScriptNode.jsDockerDocker Compose

How does it compare?

dominatos/actual-expense-logger0labs-in/vision-linkalfons-fhl/cursor-plan2api
Stars444
LanguageTypeScriptTypeScriptTypeScript
Setup difficultymoderatemoderatemoderate
Complexity3/53/53/5
Audiencedeveloperdeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · moderate Time to first run · 30min

Requires a self-hosted Actual Budget server and a Telegram bot token from BotFather, Node.js 22+ needed if not using Docker.

The README does not state a license, so terms of use are not specified.

In plain English

This project is a Telegram chat bot that lets someone quickly log an expense into Actual Budget, a self hosted personal budgeting tool, just by sending a message. A user simply types an amount like 15 or 15.50 into the chat, and the bot understands both US style numbers and European style numbers written with a comma. The bot then shows a set of clickable category buttons so the user can pick which budget category the expense belongs to, and it records the transaction into a chosen budget account. The bot supports setting up either a single default account, which requires no extra selection step, or multiple named accounts a user can choose between per transaction. It is written in TypeScript and has 66 automated tests. To protect against mistakes like double tapping a button and creating the same expense twice, it uses a guard that blocks a second submission while one is still being processed. Before saving any new transaction, it makes a backup copy of the budget data, and it keeps only the five most recent backups to avoid filling up disk space. If the bot is shut down, it makes sure to finish saving and syncing data first rather than losing anything mid operation. Running the bot requires a Telegram bot token, obtained for free from Telegram's official bot creation account, a working self hosted Actual Budget server, and a set of configuration values such as the server address, password, and sync ID, all placed in a configuration file. Access can be restricted to specific Telegram user accounts by listing their IDs, and the bot refuses all messages if that list is left empty. Sensitive values like passwords can also be supplied through Docker secrets rather than a plain configuration file, which is the recommended approach for real deployments. The project can be run either with Docker and Docker Compose, which is the suggested method and includes persistent storage for cached budget data, or run directly on a machine with Node.js version 22 or newer by installing dependencies and building the TypeScript code.

Copy-paste prompts

Prompt 1
Walk me through setting up the .env file for actual-expense-logger.
Prompt 2
Help me deploy actual-expense-logger with Docker Compose and secrets.
Prompt 3
Explain how the bot's backup and sync process works before saving a transaction.
Prompt 4
Show me how to configure multiple Actual Budget accounts for this bot.

Frequently asked questions

What is actual-expense-logger?

A Telegram bot that lets you quickly log expenses into a self-hosted Actual Budget instance by sending a chat message.

What language is actual-expense-logger written in?

Mainly TypeScript. The stack also includes TypeScript, Node.js, Docker.

What license does actual-expense-logger use?

The README does not state a license, so terms of use are not specified.

How hard is actual-expense-logger to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is actual-expense-logger for?

Mainly developer.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.

Alternatives & similar repos