workbench-ynab

workbench-ynab

Tax-aware YNAB budget review and approval-gated write-back for Claude Code. Part of the claude-workbench marketplace.

Status: pre-release / under construction. This repo is being built sprint-by-sprint by the workbench dev team (Lestrade triage → Watson development → Holmes review). Some commands and the MCP launcher referenced below ship in later sprints — each is marked with the sprint it lands in. See docs/ROADMAP.md for the full plan and issue backlog.

What this is

A productized weekly financial review for YNAB. It speaks as your own Claude agent by default — or as Hobbes, the shipped default persona, when no agent is configured (the name is configurable). Each run reads your budget, categorizes transactions, flags duplicates, surfaces tax-aware insights, and proposes ledger-only fixes inside YNAB for your approval.

It productizes a proven prototype: a hand-run, deeply tax-aware review that has run as an ad-hoc scheduled task since April 2026. This plugin turns that into a first-class, shareable tool — a formalized persona, a reusable tax-aware methodology, a frozen HTML report template, and approval-gated write-back.

Two things make this plugin unusual among workbench plugins, and both are front and center — not buried:

• It writes back to YNAB. Beyond reading, it can categorize, allocate, fix duplicates, and reconcile inside your budget. Every write waits for your explicit approval, and the plugin never moves real money — see The read / propose / approve loop.
• It handles a financial access token. Your YNAB Personal Access Token is stored only in the macOS Keychain — never in the repo, never in a config file, never logged. See Privacy / where the token lives.

Not tax advice. This tool organizes financial data and surfaces tax-relevant signals to help you and your tax professional. It is not a substitute for professional tax advice.

Architecture

Mirrors the sibling workbench plugins: a single entry point dispatches a read-only orchestrator that plans the review, the main conversation drives the interactive review + propose/approve protocol via skills, and a vendored YNAB MCP is the only thing that ever talks to the YNAB API.

                      ┌──────────────────────────────┐
                      │  /workbench-ynab:ynab-review  │  ← entry point
                      │   (or the scheduled task)     │     (Sprint 3)
                      └───────────────┬──────────────┘
                                      │ dispatches
                                      ▼
                      ┌──────────────────────────────┐
                      │  ynab-orchestrator           │  ← read-only sub-agent
                      │  • inspects budget state     │     returns a structured
                      │  • plans which analyses run  │     review PLAN — it never
                      │  • sizes the data pull       │     writes to YNAB
                      └───────────────┬──────────────┘
                                      │ plan
                                      ▼
   You ↔ assistant (main)  ◁───────── drives the interactive review protocol
            │                         (12-section methodology, change-set,
            │                          propose → approve → apply)
            │
            │  reads config           ┌────────────────────────────────────┐
            ├───────────────────────▶ │  budget · tax-profile · persona    │
            │  (skills ONLY)          │  config — lives OUTSIDE the repo    │
            │                         └────────────────────────────────────┘
            │
            │  dispatches YNAB verbs
            ▼
   ┌──────────────────────────────┐
   │  vendored YNAB MCP           │   the ONLY thing that talks to the
   │  bin/launcher.sh → node      │   YNAB API. Receives the token +
   │  @dizzlkheinz/ynab-mcpb      │   its package-native env — never
   │  (frozen bundle)             │   this plugin's config.
   └───────────────┬──────────────┘
                   │ HTTPS
                   ▼
              💰  YNAB API

The config split is deliberate and load-bearing:

Layer	Reads	Never sees
🧠 Skills (main conversation)	budget id, tax profile, persona config	the YNAB token
🔌 Vendored YNAB MCP (tool server)	the YNAB token (YNAB_ACCESS_TOKEN) + its package-native env	budget / tax / persona config

The skills do all the tax and persona reasoning from config; the MCP does all the API talking from the token. Neither crosses into the other's lane — the token never reaches a skill, and the config never reaches the MCP.

Prerequisites