{"id":21327562,"url":"https://github.com/rare-magma/guitos","last_synced_at":"2026-05-10T03:31:06.243Z","repository":{"id":153993007,"uuid":"617179574","full_name":"rare-magma/guitos","owner":"rare-magma","description":"A personal budgeting app that helps you figure out where your money went, plan your budget ahead of time and analyze past expenditures.","archived":false,"fork":false,"pushed_at":"2025-04-01T23:45:12.000Z","size":9330,"stargazers_count":75,"open_issues_count":5,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-02T11:05:49.237Z","etag":null,"topics":["budget","budget-analysis","budget-app","budget-manager","budget-planner","budget-tool","budgeting","finance","finance-application","finance-management","finance-tracker","guitos","personal-finance","personal-portfolio"],"latest_commit_sha":null,"homepage":"https://guitos.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rare-magma.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-21T21:15:29.000Z","updated_at":"2025-03-31T21:36:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"f7629e60-095b-49f9-b591-6bba52ec6140","html_url":"https://github.com/rare-magma/guitos","commit_stats":null,"previous_names":[],"tags_count":118,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rare-magma%2Fguitos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rare-magma%2Fguitos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rare-magma%2Fguitos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rare-magma%2Fguitos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rare-magma","download_url":"https://codeload.github.com/rare-magma/guitos/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248045230,"owners_count":21038553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["budget","budget-analysis","budget-app","budget-manager","budget-planner","budget-tool","budgeting","finance","finance-application","finance-management","finance-tracker","guitos","personal-finance","personal-portfolio"],"created_at":"2024-11-21T21:18:12.814Z","updated_at":"2026-01-02T01:51:13.680Z","avatar_url":"https://github.com/rare-magma.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 💸 guitos\n\n\u003cdetails\u003e\n\u003csummary\u003eTable of Contents\u003c/summary\u003e\n\n- [About](#about)\n- [Published On](#published-on)\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n- [Usage](#usage)\n- [Notes](#notes)\n- [AI Analysis](#ai-analysis)\n- [Known issues](#known-issues)\n- [Container](#container)\n- [Docker compose](#docker-compose)\n- [Related Projects](#related-projects)\n- [Built With](#built-with)\n- [Hosted On](#hosted-on)\n- [Roadmap](#roadmap)\n- [Support](#support)\n- [Contributing](#contributing)\n- [Authors \u0026 contributors](#authors--contributors)\n- [Security](#security)\n- [License](#license)\n- [Acknowledgements](#acknowledgements)\n\n\u003c/details\u003e\n\n|                                                Horizontal layout                                                 |                                              Vertical layout                                               |\n| :--------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------: |\n| \u003cimg alt=\"guitos horizontal layout screenshot\" src=\"docs/images/horizontal.png\" title=\"Horizontal\" width=\"100%\"\u003e | \u003cimg alt=\"guitos vertical layout screenshot\" src=\"docs/images/vertical.png\" title=\"Vertical\" width=\"100%\"\u003e |\n\n\u003cdetails\u003e\n\u003csummary\u003eAdditional screenshots\u003c/summary\u003e\n\u003cbr\u003e\n\n|                                                               Light theme                                                                |                                                            Light theme                                                             |\n| :--------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------: |\n| \u003cimg alt=\"guitos light theme horizontal layout screenshot\" src=\"docs/images/horizontal-light.png\" title=\"Horizontal light\" width=\"100%\"\u003e | \u003cimg alt=\"guitos light theme vertical layout screenshot\" src=\"docs/images/vertical-light.png\" title=\"Vertical light\" width=\"100%\"\u003e |\n\n|                                             History                                              |                                                        Initial state                                                        |\n| :----------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------: |\n| \u003cimg alt=\"guitos history screenshot\" src=\"docs/images/history.png\" title=\"Tooltip\" width=\"100%\"\u003e | \u003cimg alt=\"guitos initial state screenshot\" src=\"docs/images/initial-state-vertical.png\" title=\"Initial state\" width=\"100%\"\u003e |\n\n|                                                   Charts                                                    |                                                         Charts light theme                                                         |\n| :---------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------: |\n| \u003cimg alt=\"guitos charts page screenshot\" src=\"docs/images/vertical-charts.png\" title=\"Charts\" width=\"100%\"\u003e | \u003cimg alt=\"guitos light theme charts page screenshot\" src=\"docs/images/vertical-charts-light.png\" title=\"Light theme\" width=\"100%\"\u003e |\n\n\u003c/details\u003e\n\n## About\n\nguitos is a personal budgeting app that helps you figure out where your money went, plan your budget ahead of time and analyze past expenditures.\n\nIt stores data in your browser's local storage ([IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)). Your private financial data doesn't leave your browser.\n\nguitos was initially created to replace a spreadsheet and as an opportunity to learn React.\n\nguitos is [portuguese slang](https://en.wiktionary.org/wiki/guito) for money/cash.\n\n## Published On\n\n- [Show HN](https://news.ycombinator.com/item?id=35778328#35786940)\n- [producthunt.com](https://www.producthunt.com/products/guitos)\n- [store.app](https://store.app/guitos-app)\n- [r/SideProject](https://www.reddit.com/r/SideProject/comments/15w7v3g/guitos_a_simple_budgeting_app_that_helps_you/)\n- [r/reactjs](https://www.reddit.com/r/reactjs/comments/12s9yph/guitos_a_simple_budgeting_app_that_helps_you/)\n- [r/selfhosted](https://www.reddit.com/r/selfhosted/comments/1g20dl3/i_containerized_my_budgeting_react_app_guitosapp/)\n- [selfh.st](https://selfh.st/newsletter/2024-10-18/)\n\n## Getting Started\n\n### Prerequisites\n\n1. Any modern browser with javascript enabled.\n\n### Installation\n\nIt's not necessary to install anything in order to use this app.\n\nHowever, if you'd like to use it offline, follow the instructions for your device on:\n[web.dev](https://web.dev/learn/pwa/installation#desktop_installation) or use the [container image](#container)\n\n## Usage\n\n### Use case example\n\nI receive a salary at the end of each month and around that time I create a new budget to plan the expenses/savings goals/etc.\n\nI frequently add a new expense before I purchase it so I can see the impact on the budget and prepare accordingly.\nIf everything went according to plan, once I receive a new salary, I transfer the value in the `savings estimate` field to my bank savings account.\n\nLater, I can compare the budget with previous months to understand where the money is going by hovering the mouse/tapping on a single expense. A tooltip pops up and shows its value in percentage of revenue (see the tooltip screenshot above).\nThe charts page is useful for these kinds of insights.\n\nThere I can see an overview of the evolution of several metrics such as `savings`, `revenue`, etc. If I want to narrow down the chart to a specific type of item I can search for it in the filter searchbox. If I toggle the `strict match` button then only items that are named exactly as the search value are shown in the resulting chart.\n\n### Starting from scratch\n\n1. Visit [guitos.app](https://guitos.app)\n2. Create a new budget and name it according to your preferred budget period\n   - ideally in one of the following formats: `YYYY-MM` or `YYYY-WN`\n3. Input your revenue for the respective period (salary, sales, etc.)\n4. Fill in the expenses (groceries, electricity, etc.)\n5. Change the savings goal to your preference\n6. Update the reserves field with the current value of your emergency fund / cash\n\n### In case you have a backup/would like to import data from another source\n\n1. Visit [guitos.app](https://guitos.app)\n2. Import data from single/multiple CSV files or a single JSON file.\n   Make sure they follow the required structure:\n\n### CSV data model\n\n```csv\ntype,name,value\nexpense,rent,1000.00\nexpense,food,200.00\nincome,salary,2000.00\nincome,sale,100\ngoal,goal,10\nreserves,reserves,0\n```\n\n- Note that the name of the CSV file is parsed as the name of the budget:\n\n  `2023-04.csv` results in a budget with the name of `2023-04`.\n\n### JSON data model\n\n```json\n[\n  {\n    \"id\": \"035c2de4-00a4-403c-8f0e-f81339be9a4e\",\n    \"name\": \"2023-03\",\n    \"expenses\": {\n      \"items\": [\n        { \"id\": 1, \"name\": \"expense1\", \"value\": 10 },\n        { \"id\": 2, \"name\": \"expense2\", \"value\": 20 }\n      ],\n      \"total\": 30\n    },\n    \"incomes\": {\n      \"items\": [\n        { \"id\": 1, \"name\": \"income1\", \"value\": 100 },\n        { \"id\": 2, \"name\": \"income2\", \"value\": 200 }\n      ],\n      \"total\": 300\n    },\n    \"stats\": {\n      \"available\": 270,\n      \"withGoal\": 240,\n      \"saved\": 270,\n      \"goal\": 10,\n      \"reserves\": 100\n    }\n  }\n]\n```\n\n- Note that the ID of each budget inside the JSON file should be a [v4 UUID](\u003chttps://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)\u003e) as created by the `crypto.randomUUID()` [method](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID).\n\n### Keyboard shortcuts\n\nKeyboard shortcuts can be triggered when no input field is selected.\n\n| Action                            | Shortcut |\n| --------------------------------- | -------- |\n| Undo last change                  | U        |\n| Redo last change                  | R        |\n| Clone current budget              | C        |\n| Create new budget                 | A        |\n| Open import/export panel          | O        |\n| Export data as JSON               | S        |\n| Export current budget as CSV      | D        |\n| Export data as AI friendly prompt | H        |\n| Open settings panel               | T        |\n| Go to older budget                | PageDown |\n| Go to current month's budget      | Home     |\n| Go to newer budget                | PageUp   |\n| Rename current budget             | N        |\n| Search                            | F or /   |\n| Focus savings goal                | G        |\n| Focus reserves                    | E        |\n| Toggle charts view                | I        |\n| Dismiss all notifications         | Escape   |\n\n## Notes\n\n- The undo/redo functionality cannot fix every single action. Export frequently to avoid data loss!\n- To undo the deletion of a budget click the undo button in the notification shown just after the action.\n  - As soon as the notification fades (after 60 seconds) the undo action is not possible anymore.\n- guitos tries to load an existing budget when visiting `guitos.app/budget-name`\n  - it will also try to load the budget that was last visited if none is specified in the URL\n- The interface theme is set automatically by your browser and/or operating system's configuration.\n- The currency is initially selected according to your browser's preferred languages.\n  - Example: English (United States) browser language displays values in US Dollars. English (India) uses Indian Rupees.\n  - It's possible to override it by selecting a different currency code based on [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).\n- Querying the search bar finds matching budget/expense/income names, opens the budget that contains the match and highlights it.\n- The list of Revenue/Expenses can be reordered by dragging each item after enabling the toggle button.\n\n## AI Analysis\n\nguitos can export an AI prompt ready file via the export button or the keyboard shortcut which is useful for feeding Large Language Models the necessary context for analysing the information that is stored in the app.\nOnce you've generated a prompt file, you can send it to an AI assistant (like Ollama, ChatGPT, Claude, etc.) with a prompt like this:\n\n```text\nThe attached file is an export from the guitos app which is a personal budgeting app that helps you figure out where your money went, plan your budget ahead of time and analyze past expenditures.\nI want to gather some insights from it, so please review it first.\n```\n\nThe AI will analyze your data and could provide comprehensive insights with follow up instructions:\n\n```markdown\nAnalyze the year to date period and:\n1. Identify potential budgeting issues.\n2. Suggest improvements for decreasing the total expenses per month.\n3. Note areas that follow bad practices.\n\nProvide examples.\n```\n\n## Known issues\n\n- Cannot input decimal separator (comma or full stop signs) on expense/income/reserves values:\n  - guitos uses [react-currency-input-field](https://github.com/cchanxzy/react-currency-input-field/) to format the income/expense values.\n  - `react-currency-input-field` formats these values according to the current browser/phone's locale (language setting). If the locale uses `.` as the official decimal separator, then only this separator is allowed to be input.\n    - See the following Wikipedia article for a reference: [Decimal separator](https://en.wikipedia.org/wiki/Decimal_separator)\n  - Changing the browser/phone's locale to one that uses the preferred decimal separator should mitigate the problem.\n\n## Container\n\nA container image is available for offline use / self-hosting on [ghcr.io](https://github.com/rare-magma/guitos/pkgs/container/guitos).\n\nInstructions:\n\n1. Run the container with docker:\n\n```bash\ndocker run --name guitos --rm --read-only --init --cap-drop ALL --security-opt no-new-privileges:true --cpus 1 -m 64m --pids-limit 10 -p 3000:3000 ghcr.io/rare-magma/guitos:latest\n```\n\n2. Open the following link in the browser: \u003chttp://localhost:3000\u003e\n\n## Docker compose\n\nInstructions:\n\n1. Download the [docker-compose.yaml file](https://raw.githubusercontent.com/rare-magma/guitos/main/docker/docker-compose.yaml)\n2. Run docker compose:\n\n```bash\ndocker compose -f docker/docker-compose.yaml up --detach\n```\n\n## Related Projects\n\n- [guitos-exporter](https://github.com/rare-magma/guitos-exporter): Bash script that uploads the data from guitos JSON backups to influxdb\n\n## Built With\n\n- [React](https://react.dev/)\n- [Bootstrap](https://getbootstrap.com/)\n- [React Bootstrap](https://react-bootstrap.github.io/)\n- [React Bootstrap Typeahead](https://ericgio.github.io/react-bootstrap-typeahead/)\n- [React Icons](https://react-icons.github.io/react-icons/)\n- [Wouter](https://github.com/molefrog/wouter)\n- [React Currency Input Field](https://github.com/cchanxzy/react-currency-input-field)\n- [React Hotkeys Hook](https://github.com/JohannesKlauss/react-hotkeys-hook)\n- [Recharts](https://github.com/recharts/recharts)\n- [Big.js](https://github.com/MikeMcl/big.js)\n- [localForage](https://localforage.github.io/localForage/)\n- [PapaParse](https://papaparse.com/)\n- [Vite](https://vitejs.dev/)\n- [Typescript](https://www.typescriptlang.org/)\n- [Dracula](https://draculatheme.com/)\n- [Dracula.min Light](https://github.com/AshGrowem/Dracula.min#dracula.min-Light)\n- [use-undo](https://github.com/homerchen19/use-undo)\n- [immer](https://github.com/immerjs/immer)\n- [use-immer](https://github.com/immerjs/use-immer)\n- [Framer Motion](https://github.com/framer/motion)\n\n## Hosted On\n\n- [Cloudflare Pages](https://pages.cloudflare.com/)\n\n## Roadmap\n\nSee the [open issues](https://github.com/rare-magma/guitos/issues) for a list of proposed features (and known issues).\n\n## Support\n\nReach out to the maintainer at one of the following places:\n\n- [GitHub issues](https://github.com/rare-magma/guitos/issues/new?assignees=\u0026labels=question\u0026template=04_SUPPORT_QUESTION.md\u0026title=support%3A+)\n- Contact options listed on [this GitHub profile](https://github.com/rare-magma)\n\n## Contributing\n\nFirst off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are **greatly appreciated**.\n\nPlease read [our contribution guidelines](CONTRIBUTING.md), and thank you for being involved!\n\n## Authors \u0026 contributors\n\nThe original setup of this repository is by [Nuno](https://github.com/rare-magma).\n\nFor a full list of all authors and contributors, see [the contributors page](https://github.com/rare-magma/guitos/contributors).\n\n## Security\n\nguitos follows good practices of security, but 100% security cannot be assured.\nguitos is provided **\"as is\"** without any **warranty**. Use at your own risk.\n\n_For more information and to report security issues, please refer to our [security documentation](SECURITY.md)._\n\n## License\n\nThis project is licensed under the **GNU Affero General Public License v3**.\n\nSee [LICENSE](LICENSE) for more information.\n\n## Acknowledgements\n\n- [r/personalfinance](https://www.reddit.com/r/personalfinance/wiki/budgeting/)\n- [cjuega/typescript-fullstack-skeleton](https://github.com/cjuega/typescript-fullstack-skeleton)\n- [Biome](https://biomejs.dev/)\n- [go-semantic-release](https://github.com/go-semantic-release/semantic-release)\n- [testing-library](https://github.com/testing-library)\n- [vite-plugin-pwa](https://github.com/vite-pwa/vite-plugin-pwa)\n- [vitest](https://github.com/vitest-dev/vitest)\n- [Choose a license](https://choosealicense.com/)\n- [Hands on React](https://handsonreact.com)\n- [Playwright](https://playwright.dev/)\n- [@axe-core/playwright](https://github.com/dequelabs/axe-core-npm/blob/develop/packages/playwright/README.md)\n- [Repomix](https://repomix.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frare-magma%2Fguitos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frare-magma%2Fguitos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frare-magma%2Fguitos/lists"}