nex-expenses

name	nex-expenses
description	Track and categorize all business expenses with automatic Belgian tax deduction rules and VAT recovery optimization. Use optical character recognition (OCR) with Tesseract to scan receipt images and automatically extract vendor names, transaction amounts, dates, and BTW rates from physical receipt photographs. Intelligently categorize expenses into Belgian tax deduction categories (beroepskosten 100%, representatie 50%, autokosten with fuel/other subcategories, kantoorkosten 100%, kledij/werkkledij, verzekeringen, opleiding, telecom, huurkantoor, etc.) with automatic deductible portion calculation per category following Belgian tax regulations. Generate quarterly summaries organized by tax category with total amounts, deductible amounts, effective deduction percentages, and BTW collected for convenient filing with your boekhouder (accountant). Track input VAT (BTW inkomsten) separately by rate (21%, 12%, 6%, 0%) for quarterly aangifte submissions and maintain complete payment method records (cash, bank transfer, credit card, debit card, cheque). Create professional CSV/JSON exports with Belgian-friendly column headers for import into accounting software. Ideal for freelancers, eenmanszaken, and kleine ondernemingen who need to manage expenses, optimize tax deductions, prepare quarterly accounting documents, and stay compliant with Belgian tax law. All expense data remains local.
version	1.0.0
metadata	{"clawdbot":{"emoji":"🧾","requires":{"bins":["python3","tesseract"],"env":[]},"primaryEnv":"","homepage":"https://nex-ai.be","files":["nex-expenses.py","lib/*","setup.sh"]}}

Nex Expenses

Track business expenses with automatic Belgian tax categorization. OCR receipts, auto-categorize into Belgian deduction categories, generate quarterly summaries for your boekhouder, and track BTW for aangifte. All data stays on your machine.

When to Use

Use this skill when the user needs to:

• Add a business expense (receipt, invoice, or manual entry)
• Scan receipts and automatically extract vendor, date, and amount via OCR
• Categorize expenses using Belgian tax deduction rules (beroepskosten, representatie, autokosten, etc.)
• Track BTW (input VAT) for quarterly aangifte filings
• Generate quarterly expense summaries for their boekhouder (accountant)
• Search or list expenses by vendor, category, date, or tag
• Export expenses in CSV or JSON for accounting software
• View category breakdowns and top vendors by spending
• Calculate deductible amounts per expense based on Belgian tax law

Trigger phrases: "add expense", "scan receipt", "business expense", "tax category", "quarterly summary", "export for accountant", "BTW aangifte", "deductible amount", "boekhouder", "representatie", "beroepskosten"

Quick Setup

If the database does not exist yet, run the setup script:

bash setup.sh

This creates the data directory, installs dependencies in a virtual environment, initializes the database, and creates the CLI wrapper script.

Available Commands

The CLI tool is nex-expenses. All commands output plain text with consistent formatting.

Add Expense

Three modes for adding expenses:

Mode 1: Scan Receipt (OCR)

nex-expenses add --receipt /path/to/receipt.jpg
nex-expenses add --receipt ~/Downloads/bonnetje.png

Automatically extracts vendor, date, amount, and BTW rate from the receipt image. Suggests a category based on vendor recognition.

Mode 2: Manual Entry with Flags

nex-expenses add --vendor "Shell" --amount 65.30 --btw 21 --category autokosten_brandstof --date 2026-04-03
nex-expenses add --vendor "Adobe" --amount 15.99 --btw 21 --category kantoorkosten_100
nex-expenses add --vendor "Restaurant De Vita" --amount 45.50 --btw 21 --category representatie_50 --description "Lunch with client A"

Mode 3: Natural Language (Dutch/English)

nex-expenses add "lunch bij De Vitrine 45.50 BTW 21%"
nex-expenses add "Shell tanken 65,30 21% VAT"
nex-expenses add "Adobe subscription 15,99 no BTW"

Parses vendor, amount, and BTW rate from free-form text. Auto-categorizes based on vendor.

Common flags for all modes:

• --category: Belgian tax category (see nex-expenses categories)
• --date: Date in YYYY-MM-DD format (default: today)
• --description: Additional description
• --payment-method: cash, bank_transfer, credit_card, debit_card, cheque
• --notes: Internal notes

List Expenses

View your recorded expenses with various filters:

nex-expenses list
nex-expenses list --quarter Q1 --year 2026
nex-expenses list --category representatie_50
nex-expenses list --vendor "Shell"
nex-expenses list --since 2026-01-01 --until 2026-03-31
nex-expenses list --tag "project-echo"
nex-expenses list --limit 50
nex-expenses list --output json

Filters:

• --quarter: Q1, Q2, Q3, or Q4 (with --year)
• --year: Year (e.g., 2026)
• --category: Tax category ID
• --vendor: Vendor name
• --since / --until: Date range (YYYY-MM-DD)
• --tag: Filter by tag
• --limit: Max results (default: 100)
• --output: text (default) or json

Show Single Expense

Display full details of an expense by ID:

nex-expenses show 42

Shows date, vendor, amounts, BTW, deductible percentage, and category.

Edit Expense

Modify an existing expense:

nex-expenses edit 42 --category kantoorkosten_100
nex-expenses edit 42 --amount 55.00 --btw 21
nex-expenses edit 42 --vendor "Updated Vendor" --description "Corrected description"

Automatically recalculates BTW amounts and deductible portions when you change amount or category.

Delete Expense

Remove an expense from the database:

nex-expenses delete 42
nex-expenses delete 42 --force

Prompts for confirmation unless --force is used.

Search Expenses

Full-text search across vendor names, descriptions, and notes:

nex-expenses search "Adobe"
nex-expenses search "Shell fuel July"
nex-expenses search "client meeting" --limit 50

Summary Commands

Generate financial summaries for different time periods:

nex-expenses summary quarterly Q1 2026
nex-expenses summary yearly 2026
nex-expenses summary monthly 2026-04
nex-expenses summary categories --year 2026
nex-expenses summary vendors --top 20
nex-expenses summary btw Q1 2026

Quarterly Summary: Lists all expenses by category with totals, deductible amounts, and BTW reclaimable.

Yearly Summary: Aggregates all quarters, shows category and quarterly breakdowns.

Monthly Summary: Expenses for a specific month (format: YYYY-MM).

Categories: Breakdown of total spending by tax category for a year.

Vendors: Top N vendors by total spending.

BTW Summary: Input VAT grouped by rate for BTW-aangifte filing.

Export for Accountant

Export expenses in formats your boekhouder can import:

nex-expenses export csv Q1 2026
nex-expenses export csv 2026
nex-expenses export json 2026

Generates files in ~/.nex-expenses/exports/ with Belgian-friendly column headers:

• Datum
• Leverancier
• Omschrijving
• Bedrag incl. BTW
• Bedrag excl. BTW
• BTW bedrag
• BTW%
• Categorie
• Aftrekbaar%
• Aftrekbaar bedrag
• Betaalwijze
• Notities

List Available Categories

View all Belgian tax deduction categories:

nex-expenses categories

Shows category ID, name, deduction percentage, and description for each category.

Test OCR on Receipt

Debug OCR results without saving:

nex-expenses ocr /path/to/receipt.jpg

Displays vendor, date, amounts, BTW rate, confidence score, detected items, and raw OCR text.

Overall Statistics

View aggregate statistics:

nex-expenses stats
nex-expenses stats --year 2026

Shows total expenses, total deductible amount, total BTW, and expense count.

Configuration

Manage configuration settings:

nex-expenses config show
nex-expenses config set-btw-status vrijgesteld
nex-expenses config set-btw-status plichtig

• show: Display current configuration
• set-btw-status: Mark yourself as BTW-exempt (vrijgesteld) or VAT-liable (plichtig)

Example Interactions

User: "I just bought lunch with a client. It was 45.50 euros including 21% VAT at De Vitrine." Agent runs: nex-expenses add "lunch bij De Vitrine 45.50 BTW 21%" Agent: Shows the parsed expense, suggests representatie_50 category, confirms it was saved.

User: "Ik heb net getankt bij Shell voor 65 euro." Agent runs: nex-expenses add "Shell tanken 65 euro" Agent: Parses vendor and amount, suggests autokosten_brandstof category with high confidence.

User: "Hoeveel heb ik dit kwartaal aan representatiekosten uitgegeven?" Agent runs: nex-expenses summary categories --year 2026 or filters by category Agent: Shows total representatie_50 expenses with deductible portion.

User: "Scan dit bonnetje en voeg het toe." Agent runs: nex-expenses add --receipt /path/to/receipt.jpg Agent: Performs OCR, shows extracted data, suggests category, saves expense.

User: "Exporteer Q1 voor mijn boekhouder." Agent runs: nex-expenses export csv Q1 2026 Agent: Exports to CSV with professional accounting headers and confirms the file location.

User: "Hoeveel BTW kan ik terugvorderen dit kwartaal?" Agent runs: nex-expenses summary btw Q1 2026 Agent: Shows total reclaimable BTW grouped by rate (21%, 6%, 0%) for aangifte filing.

User: "Wat waren mijn top 10 meeste bezochte restaurants?" Agent runs: nex-expenses summary vendors --top 10 (or filtered by category) Agent: Lists top vendors by spending, showing total amount spent at each.

User: "Hoeveel gaf ik uit aan kantoorbenodigdheden vorig maand?" Agent runs: nex-expenses list --category kantoorkosten_100 --month 2026-03 (or summary monthly) Agent: Shows all kantoorkosten expenses for March 2026 with total.

User: "I need to correct expense ID 42. It should be 55 euros not 50." Agent runs: nex-expenses edit 42 --amount 55.00 Agent: Updates the expense, recalculates BTW and deductible amount automatically.

User: "Search for all Adobe expenses." Agent runs: nex-expenses search "Adobe" Agent: Lists all matching expenses with IDs, dates, and amounts.

Output Parsing

All CLI output is plain text, structured for easy parsing:

• Section headers followed by --- separators
• Currency formatted as €12,34 (with comma as decimal)
• Percentages shown as 21% or 50%
• Amounts are always shown with two decimal places
• ID references formatted as ID 42 for easy extraction
• Every command output ends with [Nex Expenses by Nex AI | nex-ai.be]

When presenting output to the user, strip the footer line and present the information naturally in Dutch or English depending on the context.

Important Notes on Belgian Tax Rules

• Beroepskosten (100%): General professional expenses fully deductible (office supplies, software, internet, etc.)
• Representatiekosten (50%): Entertainment, restaurants, client gifts - only 50% deductible
• Autokosten: Vehicle-related expenses - varies:
  • Brandstofkosten (Fuel): 75% deductible
  • Andere autokosten: 50-120% depending on CO2 emissions
• Kledij (0%): Regular clothing is NOT deductible
• Werkkledij (100%): Work uniforms or safety gear - fully deductible
• Verzekeringen (100%): Professional insurance - fully deductible
• Opleiding (100%): Training, courses, professional development books - fully deductible
• Huur kantoor (100%): Office rent - fully deductible
• Thuiskantoor (20%): Home office portion - typically 20% of rent/mortgage
• Telecom (100% or 75%): Phone/internet fully deductible if 100% professional use, otherwise 75% if mixed use
• Niet aftrekbaar (0%): Personal expenses, groceries, etc. - not deductible

All expenses include calculated deductible amounts based on these percentages. Always verify with your boekhouder for edge cases.

BTW (VAT) Notes

• Input BTW is tracked separately from deductible amounts
• BTW is on the expense amount BEFORE deduction percentage is applied
• For aangifte quarterly filing, use nex-expenses summary btw Q1 2026 to get totals by rate
• If you're BTW-exempt (kleine onderneming), use nex-expenses config set-btw-status vrijgesteld
• Default assumption is 21% BTW unless specified otherwise

Data Privacy

All expense data is stored locally at ~/.nex-expenses/. No telemetry, no analytics. No external API calls are made unless you explicitly configure them. OCR via Tesseract runs locally on your machine.

Troubleshooting

• "Tesseract not installed": Install tesseract-ocr:
  • Linux: sudo apt-get install tesseract-ocr
  • macOS: brew install tesseract
  • Windows: Download from https://github.com/UB-Mannheim/tesseract/wiki
• "Database not found": Run bash setup.sh to initialize
• "OCR gives poor results": Try improving image quality, ensure receipt text is clearly visible and not at an angle
• "Category not found": Run nex-expenses categories to see all available categories
• "Amount parsing failed": Use explicit flags like --vendor "X" --amount 50.00 --btw 21 instead of natural language

Expenses Directory

• Data: ~/.nex-expenses/expenses.db
• Receipts: ~/.nex-expenses/receipts/ (receipt images are stored here)
• Exports: ~/.nex-expenses/exports/ (generated CSV/JSON files)
• Config: ~/.nex-expenses/config.json (user settings)

Credits

Built by Nex AI (https://nex-ai.be) - Digital transformation for Belgian SMEs and freelancers. Author: Kevin Blancaflor License: MIT-0