Vink — lichtgewicht ZZP-administratie met Claude Code

English: Vink is a Claude Code plugin for Dutch freelancers (ZZP'ers): invoices, receipts, quarterly VAT returns and year-end figures, kept as plain CSV/JSON files in your own folder. The skills decide what to record; a deterministic Node CLI does the invoice numbering, VAT math, currency conversion and PDF rendering. Docs and skills are in Dutch; invoices and the dashboard render in Dutch or English.

Een lichtgewicht administratie voor Nederlandse ZZP'ers/freelancers, volledig op platte bestanden (CSV + JSON) en aangedreven door Claude Code. Je praat in gewone taal ("maak een factuur voor klant X", "verwerk deze bon"); de skills redeneren en stellen voor, en een klein deterministisch programma (lib/admin.mjs) doet het exacte rekenwerk en schrijft naar de bestanden.

Kernprincipe: AI bepaalt WAT, deterministische code bepaalt HOE. Factuurnummers, BTW-berekening, koersconversie en PDF-generatie lopen nooit "uit het hoofd" van de AI, maar altijd via code. Zo blijft de administratie reproduceerbaar en controleerbaar.

Deze repo is een Claude Code plugin: hij levert alléén de skills + code. Jouw administratie (facturen, bonnen, CSV's) blijft in je eigen map staan — die bezit je zelf, kun je backuppen, en blijft staan als de plugin een update krijgt.

Wat kun je ermee?

Commando	Wat het doet
/setup-vink	Eenmalige onboarding: je map initialiseren + bedrijfsgegevens en standaard betaaltermijn instellen.
/factuur	Een verkoopfactuur maken (omzet). Vult tarief/omschrijving aan op basis van eerdere facturen, kent het juiste oplopende factuurnummer toe en genereert een PDF.
/zelffactuur	Een factuur importeren die je opdrachtgever namens jou maakte (self-billing). Telt óók als omzet.
/bon	Een bon of inkoopfactuur als kostenpost verwerken. Classificeert de BTW (aftrekbaar / verlegd / niet-aftrekbaar) en rekent vreemde valuta om op de ECB-dagkoers.
/betaald	Een verkoopfactuur op betaald zetten (status + betaaldatum).
/aangifte	Een kwartaal-BTW-overzicht samenstellen (rubrieken 1a t/m 5g + ICP-opgaaf) ter voorbereiding van je aangifte.
/dashboard	Een HTML-dashboard met de stand van zaken: openstaande facturen (met dagen te laat/over datum), omzet en kosten van dit jaar en per kwartaal, en de eerstvolgende aangifte-deadline.
/jaaropgave	Je jaarcijfers ter voorbereiding van de aangifte inkomstenbelasting: winst-en-verliesrekening, afschrijvingen, KIA, ondernemersaftrek en MKB-winstvrijstelling tot de belastbare winst, plus BTW-jaaroverzicht en balansposten.

In het slash-menu heten de skills vink:factuur, vink:bon, enz. (de plugin-naam is de prefix). De korte vorm /factuur werkt ook gewoon — Claude herkent de bedoeling, ook midden in een zin.

⚠️ Dit is een voorbereidend hulpmiddel. De skills berekenen en ordenen; de daadwerkelijke aangiftes (BTW en inkomstenbelasting) dien je zelf in bij de Belastingdienst. Geen vervanging voor een boekhouder of fiscaal advies — controleer de uitkomsten.

Vereisten

• Claude Code (CLI, desktop of VS Code-extensie).
• Node.js 18 of nieuwer (node --version). Géén npm-packages nodig.
• Google Chrome (of Chromium/Brave/Edge) voor het genereren van PDF's. Staat Chrome niet op de standaard macOS-locatie, zet dan de env-var ADMIN_CHROME:

  export ADMIN_CHROME="/Applications/Chromium.app/Contents/MacOS/Chromium"

• macOS. Vink is gebouwd en getest op de Mac. Op Linux en Windows werkt het rekenwerk, maar moet je ADMIN_CHROME zelf zetten en opent een PDF niet vanzelf (de skills gebruiken open).

Installeren (voor gebruikers)

Eenmalig, in Claude Code:

/plugin marketplace add mathijs-oord/vink-plugin
/plugin install vink@vink-plugin

Daarna:

1. Maak (of kies) een map voor je administratie, bv. ~/Administratie, en open die map in Claude Code (cd ~/Administratie en start Claude Code daar). Hier komt jouw data te staan.
2. Typ /setup-vink. Dat zet bij eerste gebruik de lege templates klaar in je map (data/-CSV's, business.example.json, een project-CLAUDE.md en de uitvoer-mappen) en vraagt vervolgens je bedrijfsgegevens (naam, adres, KvK, BTW-id, IBAN) + standaard betaaltermijn.
3. Probeer het uit, bijvoorbeeld:
   • /factuur → "Maak een factuur voor Acme B.V., 20 uur consultancy à €100."
   • /bon → "Verwerk deze bon" (+ pad naar een PDF/foto).
   • /aangifte → "Stel de aangifte voor dit kwartaal samen."

Werk je voor meerdere administraties? Maak per administratie een aparte map en draai /setup-vink in elk. De plugin is overal beschikbaar; de data blijft per map gescheiden.

Updates ontvangen

Bij third-party marketplaces staat auto-update standaard uit. Twee opties:

• Handmatig (altijd de nieuwste versie ophalen):

  /plugin marketplace update vink-plugin
  

• Auto-update aanzetten: open /plugin → tabblad Marketplaces → kies vink-plugin → Enable auto-update. Updates komen dan bij het opstarten van Claude Code binnen.

Updates raken alleen de plugin-code/skills/regels — nooit je data. Je data/, facturen/, bonnen/, aangiftes/ en jaaropgaven/ blijven onaangeroerd.

Hoe het is opgebouwd

De plugin (deze repo — wordt geüpdatet):

vink-plugin/
├── .claude-plugin/
│   ├── marketplace.json     marketplace-definitie (deze repo = marketplace)
│   └── plugin.json          plugin-manifest (naam: vink)
├── skills/                  de skills: setup, factuur, zelffactuur, bon, betaald, aangifte, dashboard, jaaropgave
├── lib/admin.mjs            deterministische kern (factuurnr, BTW, FX, PDF, CSV-I/O)
├── templates/               HTML-templates voor de factuur-, aangifte- en jaaropgave-PDF's + het dashboard
├── rules/                   Nederlandse BTW- en IB-regels in markdown — de kennisbron van de skills
└── seed/                    lege templates die /setup-vink naar je eigen map kopieert

Jouw map (per gebruiker — blijft van jou):

~/Administratie/
├── CLAUDE.md                projectconventies (door /setup-vink neergezet)
├── data/                    je administratie (CSV's + business.json)
├── facturen/<YYYY-QN>/      gegenereerde + geïmporteerde factuur-PDF's, per kwartaal
├── bonnen/<YYYY-QN>/        kopie van je bonbestanden, per kwartaal (bewaarplicht)
├── aangiftes/               de aangifte-PDF's per kwartaal
└── jaaropgaven/             de jaaropgave-PDF's per jaar

Je data & privacy

• Alles staat lokaal in je eigen map. Er gaat niets naar een externe administratie-dienst.
• De plugin-repo bevat nooit jouw administratie — alleen generieke code + lege templates.
• Twee externe aanroepen. Bij vreemde valuta haalt /bon de ECB-dagkoers op via de open frankfurter.app-API. En één keer per maand stuurt de plugin een anonieme ping naar vinkapp.nl, zodat de maker ziet hoeveel mensen Vink gebruiken: geen ID en niets uit je administratie, alleen of het de eerste keer is.
• De ping uitzetten: zet "telemetry": false in data/business.json, of gebruik de omgevingsvariabele VINK_TELEMETRY=0 of DO_NOT_TRACK=1.
• De volledige privacyverklaring: Privacy.

Veiligheid by design

De skills verwijderen of overschrijven nooit automatisch een factuur of bon. Corrigeren of verwijderen doe je bewust met de hand in de CSV-bestanden. Zo kan een verkeerd begrepen opdracht nooit stilletjes je administratie wissen.

---

Voor de maintainer (updates uitbrengen)

Deze repo is tegelijk de marketplace én de plugin (één-repo-opzet, plugin op de root via "source": "./").

Een update uitbrengen = pushen naar de default branch:

git add -A
git commit -m "..."
git push

Het version-veld is bewust weggelaten uit plugin.json, dus elke commit telt als een nieuwe versie. Gebruikers halen 'm op met /plugin marketplace update vink-plugin (of automatisch als ze auto-update aan hebben). Wil je later vaste releases (semver), zet dan version in plugin.json en hoog die per release op.

Lokaal testen vóór je pusht — in een aparte testmap, niet in deze repo:

/plugin marketplace add /pad/naar/deze/repo
/plugin install vink@vink-plugin

Daarna in een lege testmap /setup-vink draaien. Een marketplace op een lokaal pad laadt de plugin rechtstreeks uit je werkmap: wijzigingen (ook ongecommitte) zijn actief na /reload-plugins of bij een nieuwe sessie — committen of marketplace update is daarvoor niet nodig.

Validatie:

claude plugin validate .

Gebruikscijfers: lib/admin.mjs stuurt per administratie-map één anonieme ping per maand naar /api/ping op vinkapp.nl (het telpunt staat in de vink-website-repo). De tellers lees je uit via https://www.vinkapp.nl/api/stats?token=…. Zet bij het testen VINK_TELEMETRY=0 in je shell, anders telt elke testmap mee als nieuwe gebruiker.

Architectuur kort: code/skills/regels/templates leven in de plugin en worden via ${CLAUDE_PLUGIN_ROOT} aangeroepen; data wordt door lib/admin.mjs weggeschreven relatief aan de map waar Claude Code draait (process.cwd() / CLAUDE_PROJECT_DIR, te overriden met ADMIN_DATA_DIR). Zo overleeft gebruikersdata elke plugin-update.

Herkomst

Afgeleid van de business-logica van Vink, een Mac-boekhoud-app waarvan de ontwikkeling is gestopt. De fiscale rekenregels (BTW-routing, rubrieken, factuureisen) komen daaruit voort.

---

Gebruik op eigen verantwoordelijkheid; dit is geen fiscaal advies.