gocost is a simple, fast, and keyboard-driven Terminal User Interface (TUI) application for managing your monthly expenses. Built with Go and the Bubble Tea framework, it provides a streamlined way to track where your money is going without ever leaving the terminal.
gocost is an app for tracking your essential monthly bills and recurring costs—like rent, utilities, and subscriptions—to give you a clear picture of your total cost of living each month.
- A tool for monitoring your main monthly payment obligations
- Focused on tracking your essential "cost centers"
- Designed to show whether your bills have been paid
- Perfect for understanding your baseline monthly expenses
- Not a detailed expense tracker for every purchase
- Not meant for tracking daily spending like coffee, meals, or shopping
- Not a budgeting app for discretionary spending
Instead of tracking every single transaction, gocost focuses on the big picture—helping you monitor the recurring costs that make up your monthly financial foundation.
- 📊 Monthly expense tracking with categories and groups
- 💰 Income management
- 📁 Category organization with groups
- 🔍 Category filtering by name or group
- 💾 Local JSON data persistence
- ⌨️ Keyboard-driven interface
- 🎨 Adaptive colors for light/dark terminals
q/Esc- Go back/Quith/l- Navigate between monthsr- Reset to current month (only shown when viewing a different month)t- Toggle expense status (only shown when navigate within month expenses)i- Manage incomec- Manage categoriesg- Manage category groups
j/down- Move downk/up- Move upEnter- Select/Edit/- Filter items (in category view)c- Clear filter (when filtered)a/n- Add new iteme- Edit itemd- Delete itemm- Move category (in category view)p- Populate categories from previous month (when current month is empty)
Tab/Shift+Tab- Navigate between fieldsEnter- SaveEsc- Cancel
/- Start filtering categories (in category view)Enter- Apply filter (while typing)c- Clear current filterEsc- Cancel filter input
The filter searches both category names and group names (case-insensitive). When a filter is active, you can still perform all normal operations (edit, delete, move) on the filtered results.
gocost/
├── cmd/
│ └── gocost/
│ └── main.go # Application entry point
├── internal/
│ ├── app/
│ │ ├── app.go # Main application model and state management
│ │ ├── messages.go # Message handlers for different actions
│ │ ├── status.go # Status message management
│ │ └── status_test.go # Status tests
│ ├── config/
│ │ ├── config.go # Configuration management
│ │ └── config_test.go # Configuration tests
│ ├── data/
│ │ ├── models.go # Data structures (Income, Expense, Category, etc.)
│ │ ├── persistence.go # JSON file load/save operations
│ │ └── persistence_test.go
│ └── ui/
│ ├── overview.go # Monthly overview view
│ ├── income.go # Income list view
│ ├── income_form.go # Income add/edit form
│ ├── category.go # Category management view
│ ├── category_group.go # Category group management
│ ├── expense.go # Expense entry form
│ ├── style.go # UI styling and colors
│ ├── types.go # UI type definitions and messages
│ ├── util.go # Utility functions
│ ├── util_test.go
│ └── validation.go # Input validation
├── go.mod
├── go.sum
└── README.md
- Bubble Tea - TUI framework
- Lipgloss - Style definitions
- Viper - Configuration management
- UUID - Unique ID generation
- Decimal - Precise decimal arithmetic
Download the latest pre-built binary from the GitHub Releases page:
- Go to the releases page
- Download the latest release for your platform
- Extract and run the binary
go install github.com/madalinpopa/gocost/cmd/gocost@v1.1.3git clone https://github.com/madalinpopa/gocost.git
cd gocost
go build -o gocost ./cmd/gocost-
Clone the repository
git clone https://github.com/madalinpopa/gocost.git cd gocost -
Install dependencies
go mod download
-
Run the application
go run ./cmd/gocost
-
Run tests
go test ./... -
Build for development
go build -o gocost ./cmd/gocost ./gocost
The application stores data in your home directory:
- Config:
~/.gocost/config.json - Data:
~/.gocost/expenses_data.json
Currency symbol can be updated in config.json.
-
Fork the repository
-
Create a feature branch
git checkout -b feature/your-feature-name
-
Make your changes
- Follow Go best practices
- Add tests for new functionality
- Update documentation as needed
-
Run tests and ensure they pass
go test ./... -
Commit your changes
git commit -m "Add your descriptive commit message" -
Push to your fork
git push origin feature/your-feature-name
-
Create a Pull Request
- Describe your changes
- Reference any related issues
- Ensure all checks pass
- Use
gofmtfor formatting - Follow Effective Go guidelines
- Keep functions small and focused
- Add comments for exported functions
MIT License
Madalin Popa