common-cents-tui/README.md

Common Cents

A keyboard-driven spending tracker that runs in your terminal. Built with Python and Textual; your data is stored locally in SQLite — no cloud, no account.

Install & run

You'll need Python 3.13 and uv.

uv sync --all-extras
uv run common-cents

That's it — the database is created automatically the first time you launch.

Install the app system-wide:

uv tool install .

What you can do

From the main menu:

• Spending — record what you spent, where, and on what. Categories, merchants, and tags autocomplete as you type, and any new ones can be created on the fly. Filter by date, amount, category, merchant, tag, or a substring of the notes. Press space to mark rows, * to mark them all, then b to apply a single change (a new category, a tag set, a date) to the whole batch. Just deleted something by accident? u puts it back.
• Metadata — manage your categories, merchants, and tags in one place. Give a category a monthly budget and Common Cents will track how close you are to it.
• Reports — see where your money went, broken down by category, with progress bars and budget targets. Period selector covers This Month / Last Month / YTD / Last 12 Months, plus a custom from-month / to-month range.
• Dashboard — month-by-month totals for the year, a top-categories list with budget progress and how this month compares to last, and your most recent activity.
• Import / Export — bring in spending from a CSV (with a built-in browser, preview, and duplicate detection), or export everything back to CSV.
• Options — point the app at a different database file, or create a new one. Useful if you want to keep separate ledgers — household vs. side hustle, for example.

Categories with subcategories

Categories use a Parent:Child convention with arbitrary depth — Food, Food:Groceries, Food:Restaurants:Lunch, and so on. Reports and the dashboard roll subcategories up into their parents automatically, so a budget on Food covers everything underneath it.

Keyboard cheat-sheet

Most screens share these keys:

Key	Action
a / e / d	Add / Edit / Delete
j k g G	Vim-style cursor movement
escape	Back
q	Quit (from the main menu)

Spending screen extras: space toggles row selection, * toggles all visible rows, b opens bulk-edit, u undoes the last delete.

Where your data lives

The database file is stored at:

• $XDG_DATA_HOME/common-cents/common-cents.db — or
• ~/.local/share/common-cents/common-cents.db if $XDG_DATA_HOME isn't set.

To use a different file, either pick it from the in-app Options screen (o from the main menu) or pass --db /path/to/file.db on launch. The Options screen remembers your choice across runs.

CSV format

Both import and export use this format. Headers are case-sensitive.

Column	Required	Notes
DATE	yes	YYYY-MM-DD
CENTS	yes	Integer cents — commas allowed ("14,901")
CATEGORY	yes	Use Parent:Child for subcategories
MERCHANT	no	May be blank
NOTES	no	Free-form
TAGS	no	Comma-separated within the field — quote it: "work,lunch"

See sample_spending.csv for a working example.

Development

If you want to hack on Common Cents, the architecture, dev workflow, and code conventions are documented in CLAUDE.md.