TUI Expense Tracker Using Textual in Python

Introduction:

Managing money is a very important skill in life. But many people still use old methods like writing their expenses on paper, or they use big, confusing apps that are hard to understand.
This is where Bagels comes in — a simple and smart solution. It is a TUI Expense Tracker Using Textual in Python – Bagels App that is built specially for people who love using the terminal but still want a clean and easy experience.

Bagels is not just about writing down your spending. It is a full tool to help you manage your money better.
Here’s what makes Bagels special:

Full Budgeting System:
Bagels lets you plan your budget by category — like food, rent, entertainment, travel, shopping, and more.
You decide how much you want to spend in each category, and Bagels helps you stay on track.
Customizable Spending Templates:
We all have different habits and needs. Bagels allows you to create your own templates based on your regular spending.
This saves you time and makes adding expenses very quick and easy.
Insightful Graphs:
Looking at numbers can be boring, but graphs make it simple to understand where your money goes.
Bagels turns your spending into simple and clear graphs.
You can easily spot if you are spending too much in one area.
Smooth Terminal Interface:
Bagels is built using Textual, a modern Python framework that makes terminal apps look beautiful and work smoothly.
It is clean, fast, and easy to use, even if you are not a tech expert.
It gives you the power of a full app, but inside the terminal.

Who is Bagels for?

Bagels is made for two types of people:

Minimalists – People who want a simple tool without extra junk.
Power Users – People who love having full control, fast input, and a clean, fast experience without heavy apps.

By mixing simplicity with powerful features, Bagels becomes a great choice for anyone.
Whether you are a student, a working professional, or just someone who wants to manage their money better, Bagels is perfect for you.

In this article, we will go deep into how the TUI Expense Tracker Using Textual in Python – Bagels App works.
You will learn:

What tools and modules are needed.
How to install and run Bagels.
How each part of the code works.
What the output looks like.

By the end, you will not only understand how Bagels is built but also get ideas to create or customize your own version.

Required Modules or Packages:

Bagels is built using Python and relies heavily on Textual, a modern TUI framework. Here’s a list of required dependencies:

🐍 Python Version:

Python 3.10+ (Textual requires Python 3.10 or above)

📦 Required Python Packages:

				
					pip install textual rich

Optional (if you’re planning to extend functionality):

				
					pip install matplotlib pandas

📁 Folder Structure:

The Bagels project is modular, with a clean codebase spread across multiple files:

				
					bagels/
├── begal.py
├── home.py
├── manager.py
├── main.py
├── textualrun.py
├── data/
│   └── expenses.json
├── config/
│   └── settings.json
└── README.md

How to Run the Code:

Running Bagels on your local machine is super simple. Just make sure you have the required packages installed.

Step 1: Clone the repository

				
					git clone https://github.com/yourusername/bagels.git
cd bagels

Step 2: Install Dependencies

				
					pip install -r requirements.txt

Or, manually:

				
					pip install textual rich

Step 3: Run the Application

				
					python main.py

You’ll now see a full-screen terminal application load up with menus like:

💸 Budgets
🧾 Spending
📊 Insights
⚙️ Settings

Code Explanation:

Let’s understand the main logic of the project, one file at a time.

1. main.py – The Starting File

This file starts the app and sets up all the important parts. It loads the settings, connects to the database, and takes the app to the home screen.

				
					from begal import BagelsApp

if __name__ == "__main__":
    app = BagelsApp()
    app.run()

The app starts by importing the main class from begal.py.
app.run() launches the TUI using Textual’s event loop.
This file is intentionally kept minimal to separate UI logic from app bootstrapping.

2. begal.py – Main App Class

This file has the main class called BagelsApp, which is based on the App class from Textual. It controls navigation, events, and how the app runs.

It designs the TUI layout with a sidebar and a main content area.
It manages moving between screens (like from Home to Insights).
It handles keyboard shortcuts that work across the whole app.

				
					class BagelsApp(App):
    CSS_PATH = "styles.css"
    BINDINGS = [("ctrl+c", "quit", "Quit")]

    def on_mount(self):
        self.push_screen(HomeScreen())

CSS_PATH links to your app’s custom styling.
BINDINGS define keyboard shortcuts like Ctrl+C to quit.
on_mount() runs when the app loads and pushes the initial screen — the home screen.
It acts like the router/controller of your app, transitioning between views like SpendingScreen, BudgetScreen, etc.

3. home.py – Home Screen & Dashboard UI

This file creates the home screen layout showing a welcome message, monthly budget, and quick actions. It uses Textual widgets to render components visually.

				
					class HomeScreen(Screen):
    def compose(self) -&gt; ComposeResult:
        yield Static("💰 Welcome to Bagels!", classes="heading")
        yield Static("Budget: ₹10,000 | Spent: ₹6,450", classes="info")
        yield Button("➕ Add Expense", id="add-expense")

In the compose() function, it creates things like text blocks (Static) and buttons.
It builds a simple dashboard with buttons you can click.
Buttons are linked to actions or screen changes using event handlers.
You can change how things look using class names and CSS.

4. manager.py – Expense Data Manager

Handles all backend logic related to adding expenses, loading data, saving budgets, and returning analytics. It abstracts file I/O operations and provides clean interfaces for other modules.

				
					def add_expense(date, category, description, amount):
    data = load_data()
    data["expenses"].append({
        "date": date,
        "category": category,
        "description": description,
        "amount": amount
    })
    save_data(data)

add_expense() appends a new expense to the list and saves it to a JSON file.
load_data() reads from expenses.json, while save_data() writes to it.
Centralizing logic in this file keeps UI components free from data-related complexity.

Another function example:

				
					def get_monthly_summary():
    data = load_data()
    return sum(exp["amount"] for exp in data["expenses"])

This function helps calculate the total spending in a given month.

5. textualrun.py – Screen Routing & Navigation

Handles navigation between screens. You define and push different views here like a mini frontend router for your TUI.

				
					class Router:
    def __init__(self, app):
        self.app = app

    def go_to_spending(self):
        self.app.push_screen(SpendingScreen())

    def go_to_insights(self):
        self.app.push_screen(InsightsScreen())

Router encapsulates screen transitions.
push_screen() is a method provided by Textual to change the current view.
This decouples screen logic from UI logic and keeps code more organized.

You can think of these as routes like:

				
					Router(self).go_to_insights()

6. data/expenses.json – Local Data Storage (JSON)

This is where your data gets stored. Here’s an example of what the file might look like:

				
					{
  "expenses": [
    {
      "date": "2025-04-08",
      "category": "Food",
      "description": "Dinner with friends",
      "amount": 800
    },
    {
      "date": "2025-04-12",
      "category": "Travel",
      "description": "Uber ride",
      "amount": 250
    }
  ]
}

This simple JSON structure keeps your app lightweight and fast.
You don’t need a database or external dependency.
Ideal for offline usage and portability.

7. config/settings.json – User Preferences

Stores settings like monthly budget limit, currency, or UI preferences.

				
					{
  "monthly_budget": 10000,
  "currency": "INR",
  "theme": "dark"
}

You can allow users to tweak these settings from the UI later.
Also useful for storing user state or UI customization.

Source Code

To explore the full source code, click the button below to download the ZIP file and run it on your local machine:

Your download is starting now...

Output:

When you run the application, you’ll get a beautifully styled terminal interface like this:

Conclusion:

Building a TUI Expense Tracker Using Textual in Python – Bagels App is not just about writing code — it’s about solving real-world problems in a simple, beautiful, and efficient way. Bagels proves that even without fancy graphics or complicated software, you can still create a powerful, elegant tool that helps users manage their money smartly.

Throughout this project, we saw how modular design can make a project more organized and easy to maintain. Files like main.py, begal.py, home.py, manager.py, and textualrun.py each have their own clear responsibilities. This separation of tasks makes the code cleaner and easier to improve in the future. If you ever want to add new features, like setting goals or visualizing savings graphs, you can do it without breaking the rest of the app.

One of the best parts of building with Textual is how much control it gives you over the terminal interface. You can design screens, layouts, buttons, and even theme your app — all inside the command line! It feels modern, yet it stays lightweight. This means your TUI Expense Tracker Using Textual in Python – Bagels App will work even on low-end computers, servers, or cloud environments where a full GUI is not possible.

Another thing we learned is how important it is to manage data properly. With simple JSON files like expenses.json and settings.json, Bagels makes it easy to store and load user data. You don’t need a heavy database or external tools. This approach keeps the app portable — you can copy your entire Bagels folder to another device and your data will still be there.

From a beginner’s perspective, working on a project like Bagels is a fantastic way to grow as a Python developer. You practice concepts like:

Object-oriented programming (OOP) by creating classes and methods.
File handling by reading and writing JSON files.
Event-driven programming with Textual’s screen and button interactions.
Modular coding by splitting logic across multiple files.

If you are new to Python or building terminal apps, don’t worry if some parts seem complex at first. The more you work with projects like this, the more comfortable you will become. Step by step, your coding skills will improve naturally.

In the end, Bagels is not just a TUI app — it’s a complete, working product. You can add expenses, track your monthly spending, and view insights. With just a few more improvements, such as better graphs, custom categories, or budget alerts, Bagels can become a full-fledged personal finance manager for everyday use.

So whether you are building this for fun, for learning, or even for your portfolio — remember this: small projects like Bagels are the stepping stones to becoming a great developer.

Keep coding, keep experimenting, and most importantly — keep building tools that are useful and simple.
That’s how the best software in the world starts — with small ideas, turned into beautiful creations.

If you found this guide helpful, I encourage you to try building your own version of the TUI Expense Tracker Using Textual in Python – Bagels App — maybe you’ll add some unique features that even surprise yourself!

If you are interested in more cool Python projects, you should definitely check out our Django-based Gym Management System!