Tax Brotax document reader
Install it View source All projects

Claude Code skill set

Your tax folder, read once and added up.

A set of Claude Code commands you point at a folder of W-2s, 1099s, foreign bank statements and childcare receipts. It extracts the figures, checks the arithmetic, and builds a dashboard.

Install it View source on GitHub ← Back to all projects
  • US Form 1040 + international schedules
  • Runs in Claude Code or Gemini CLI
  • Repo holds zero personal data
  • Not tax advice
$ git clone https://github.com/kbrovibes/taxbro ~/claude/taxbro
$ cd ~/claude/taxbro && claude

> /taxbro-init ~/taxes/2025/
  walks the folder, builds a document inventory,
  writes TAXBRO/session-notes.md — nothing is copied into the repo

> /taxbro-extract
  reads every document once, extracts facts rather than text,
  runs the arithmetic cross-checks, writes US-knowledge-graph.md

> /taxbro-visualize
  renders the graph as a self-contained US-knowledge-graph.html

> /taxbro-worksheets
  prints form line items in the shape a preparer can type in

— all output lands in {your tax folder}/TAXBRO/, never here —

Not tax advice

Tax Bro is a personal project and an analysis aid. It is not a substitute for a CPA or an enrolled agent, it does not file anything, and it is not affiliated with or endorsed by the IRS. Its totals are estimates using simplified bracket math — a human still has to check every number before it goes on a return.

What it is

Six slash commands and one markdown file

A household with foreign accounts files its taxes out of a folder of thirty-odd PDFs and a spreadsheet nobody fully trusts. W-2s, a consolidated 1099, Indian bank statements, a CAMS mutual fund report, childcare receipts. Every year the same numbers get retyped, and every year one of them is wrong.

Tax Bro is a set of Claude Code commands for that folder. /taxbro-extract reads each document once, stores facts rather than text, runs arithmetic cross-checks, and writes a single markdown knowledge graph with computed totals. Every other command reads that file instead of reopening the PDFs.

Tour

What running it looks like

> /taxbro-init ~/taxes/2025/
  resolves the path and records it in .current-session
  discovers every file, skipping TAXBRO/ and .DS_Store
  writes TAXBRO/file-index.md and TAXBRO/session-notes.md

> /taxbro-init --reset
  moves the previous run aside into
  TAXBRO/.snapshots/YYYY-MM-DD-HHMMSS/ and starts clean

rule the skills may only read files and write into TAXBRO/.
     No rm, no rmdir, no deletion of any kind — ever.

Command 01

Point it at a folder

You give it a path. It reads the folder, writes an inventory, and remembers the path in a gitignored file. Your documents are never copied into the repo, and nothing is ever deleted.

  • Document inventory before any parsing
  • Reset archives, it does not remove
> /taxbro-extract
  pass 1 — read the first page or two of everything, classify:

  W-2 ........................... FULL-PARSE   read every box
  1099-B trade detail ........... SUMMARY-ONLY category totals
  1099-INT / 1099-SA / 1098 ..... HEADER-ONLY  page 1 is all
  Bank statements, 12 months .... FULL-PARSE   first + last page
  CAMS CAS ...................... SUMMARY-ONLY holdings summary
  Childcare receipts ............ HEADER-ONLY  provider, EIN, total
  Duplicates, informational ..... REFERENCE    noted, not read

  pass 2 — deep-parse only what pass 1 flagged for it

Command 02

Read once, then triage

Most tax documents do not need reading in full. A first pass looks at the opening page and sorts each file into full parse, summary, header-only or reference. Only the first two categories get read properly.

  • Facts, not content: a bank statement becomes three numbers
  • Every value cites the file it came from

The shape of it

One file everything reads

Extraction happens once. The knowledge graph is the only thing downstream commands look at, so the dashboard, the compliance summary and the worksheets cannot quietly disagree about what your income was.

  • Computed totals live in one place
  • Same numbers whether Claude or Gemini ran it
## Computed Totals            (placeholder figures — not a real return)

  Wages, W-2 Box 1 .............. $NNN,NNN  ✓ confirmed
  Interest, US + foreign ........ $  N,NNN  ✓
  Capital gain, ST / LT ......... $ NN,NNN  ✓ split is mandatory
  Foreign rental, Schedule E .... $  N,NNN  ~ converted at Pub 54
  ─────────────────────────────────────────
  AGI ........................... $NNN,NNN  ~ calculated
  Deduction used ................ $ NN,NNN  ✓ standard vs itemized
  Estimated total tax ........... $ NN,NNN  ~
  Payments + credits ............ $ NN,NNN  ✓
  Estimated refund / (owe) ...... $  N,NNN  ⚠ estimate only

markers: ✓ read from a document · ~ calculated · ⚠ verify · ✗ missing

The graph

Every figure is marked

Nothing in the graph is presented as more certain than it is. Each value carries a marker — read from a document, calculated, needs checking, or missing — and a citation back to the file it came from.

  • Figures above are placeholders, not a real return
  • Totals are simplified bracket math, flagged as estimates
> /taxbro-visualize
  → US-knowledge-graph.html — waterfall from gross income to
    refund or owe, income mix, payments vs tax, per-item impact

> /taxbro-compliance
  → US-compliance-summary.md — FBAR and Form 8938 thresholds,
    PFIC / Form 8621 holdings, Form 1116 foreign tax credit

> /taxbro-worksheets
  → US-worksheets.md — Form 1040 key lines and schedules,
    laid out so a preparer can enter them directly

> /taxbro-validate-return ~/taxes/2025/draft-return.pdf
  → US-validation-report.md — the draft your CPA sent back,
    line by line against your source documents

Command 03 onward

Deep dives, then a human

The remaining commands are for the awkward parts: foreign accounts, mutual funds treated as PFICs, the foreign tax credit. The last one takes the draft return your preparer produced and checks it against your documents.

  • Compliance analysis, not a filing determination
  • Output is preparer input, not a finished return

How it works

Folder in, worksheet out, human at the end

Four commands, run in this order, on a folder you already have sitting on your disk.

01

Point at the folder

/taxbro-init ~/taxes/2025/ discovers the documents and writes an inventory. Nothing is copied, moved or deleted.

02

Extract once

/taxbro-extract triages, reads, cross-checks and writes US-knowledge-graph.md with a computed totals section at the end.

03

Look at the dashboard

/taxbro-visualize renders the graph as one self-contained HTML file that opens straight from disk. No server.

04

Hand it to a preparer

/taxbro-worksheets prints the form line items. When the draft return comes back, /taxbro-validate-return checks it.

Features

What’s actually in it

One-pass extraction

Each document is read once and stored as facts. A forty-page bank statement becomes a peak balance, a year-end balance and interest earned.

Two-pass triage

The first pass reads a page or two and classifies. The second deep-parses only the documents that actually need it.

W-2 arithmetic checks

Box 4 divided by Box 3 must land on 6.2%, Box 5 must be at least Box 1, Box 3 must sit under the wage cap.

Confidence markers

Every figure is marked confirmed, calculated, uncertain or missing, and cites the source file it was read from.

Foreign accounts

Peak and 31 December balances per account, measured against the FBAR and Form 8938 reporting thresholds.

PFIC and mutual funds

Reads a CAMS consolidated account statement for year-end holdings and flags Form 8621 territory instead of guessing.

Foreign tax credit

Pulls foreign taxes paid and TDS certificates into Form 1116 passive-basket detail, converted at the IRS Publication 54 rate.

Interactive dashboard

One self-contained HTML file: the waterfall from gross income to refund or owe, income mix, and payments against tax.

It never deletes

The skills may only read your files and write into the TAXBRO folder. Reset archives a previous run rather than removing it.

Built with

Markdown, and whatever agent you run it in

  • Claude Code
  • Gemini CLI
  • Markdown skill prompts
  • Self-contained HTML
  • No dependencies
  • No build step

There is no server and nothing to compile — the repo is a set of markdown skill files. Your documents stay on your disk and output goes to {your tax folder}/TAXBRO/. Reading them means sending their contents to whichever model you run, so the usual caution about handing financial documents to an AI provider applies.

git clone https://github.com/kbrovibes/taxbro ~/claude/taxbro
cd ~/claude/taxbro && claude

# then, inside the session:
/taxbro-init ~/taxes/2025/
/taxbro-extract

FAQ

Reasonable questions

Is this tax advice?

No. This is a personal project and an analysis aid — not tax advice, not a substitute for a CPA or an enrolled agent, and not affiliated with or endorsed by the IRS. A human checks every figure before it goes on a return.

Does it file my return?

No. It writes markdown and HTML into a folder on your machine. It does not e-file, does not submit anything, and does not communicate with the IRS or any state agency.

Is it free?

The repo is. You need Claude Code or Gemini CLI and you pay whatever that costs you — a full extraction over thirty-odd PDFs is not a small prompt. Gemini is suggested for the extraction pass because of the context window.

Where do my documents go?

They stay where they are. Output lands in {your tax folder}/TAXBRO/, which you should keep private and out of git. The repo itself holds no personal data, but the agent does read your files, so their contents reach your model provider.

Is it still being worked on?

Not really. The last meaningful change was April 2026. It was written for one household’s returns and left there — treat it as a working example rather than a maintained product.