taxtrace

taxtrace

Every number on your return, traced to its page.

For anyone who does their own US taxes from a pile of PDFs: W-2s, 1099s, K-1s (partnership income statements), a rental, a foreign bank account. taxtrace reads them on your own computer and builds the sheet you type into your tax software, with the file, page and exact text behind every value. It never files anything and never guesses: what it can't settle becomes a question for you. Free and open source.

Mac / Linux
Install uvcurl -LsSf https://astral.sh/uv/install.sh | sh
Thenuv tool install taxtrace
Then runtaxtrace ui
Windows
Install uvpowershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Thenuv tool install taxtrace
Then runtaxtrace ui

Run taxtrace ui and your workspace opens in the browser. Built and tested on a Mac: the Keychain passwords and the on-device AI model are macOS only.

Already have Python? pipx install taxtrace works too.

The old way

Forty PDFs from six places.

Numbers retyped, never checked.

Carryovers buried on page 71.

What taxtrace does for you

Read

Reads what you already have

W-2s, 1098s, brokers' 1099s, partnership K-1s and K-3s, a rental's statements, foreign bank statements and last year's filed return. Scanned pages are read on your computer too.

Trace

Every number has a source

Each value keeps the file, the page and the exact text it was read from. A check throws out any value whose quote isn't on that page.

Check

The arithmetic is verified

A partnership K-1's capital account has to add up, a rental's income schedule (Schedule E) has to tie out, last year's carryovers have to roll forward. A miss is shown, not smoothed over.

Ask

Questions instead of guesses

A receipt that could be a repair or an improvement, a missing 1099, a rate to choose: each is a question for you, with the evidence next to it.

Plan

The year, ahead of time

Quarterly estimated-tax payments checked against the amount that avoids a penalty, tax-saving moves ranked by the dollars each saves, IRA limits, and stock sales with the 30-day wash-sale rule (a loss is disallowed if you rebuy).

Agents

Works with your AI assistant

Ask Claude (or another assistant that supports MCP, the standard way to plug tools into AI chat) what's in your workspace and what's left to do. It only ever gets masked text.

See it work

From a folder of documents to an entry sheet, in about two minutes.

Demo data: the people, employers and amounts shown are invented.

Read the narration

Tax season often starts with a folder of PDFs and a quiet worry. Which page did that number come from? Is a form missing? And do you really want to hand all of it to a chatbot?

Every number, traced to its page.

This is taxtrace, running in your browser, on your own Mac. At the top, what your workspace holds, then your to-do list, and the year's tax-saving moves, ranked by the dollars each one saves.

When your preparer sends more documents, open the Import tab and choose the files. taxtrace shows what it makes of each one: its form, its tax year and its owner. A passport, or a copy you already have, is skipped.

One button files the rest. The page then lists your documents by folder, sorted by tax year, each tagged with the form it holds, and none of them has left your computer.

Then the entry sheet: everything your tax software will ask, in the order it asks. Each value shows whether it is ready, an estimate or missing, and the document and page it was read from.

Switch to estimates and missing, and only the rows that need you are left. Each section links to the to-do items that mention it, so nothing waits unnoticed.

Last, the chat, for questions about tax rules and forms. Before anything goes to a cloud model, digits become pound signs and names and towns become stars, and the page shows exactly what was sent.

And a question with an amount in it never leaves your Mac. The model here answers it, and the page says why.

How it works

Four parts of taxtrace ui, each with a short video.

1

Import

On the Import screen, choose files or a folder, or drop a preparer's portal zip. taxtrace shows each file's form, tax year and owner before anything is filed. Documents are sorted by tax year, filed returns go to their own folder, and identity documents and repeats are skipped. taxtrace import does the same from the terminal.

2

Read the forms, get the entry sheet

The Entry sheet screen lists everything your tax software will ask, in its order, from forms taxtrace read box by box (taxtrace w2, 1099, k1, 1098 and more). Each value shows the document and page it came from and whether it is ready, an estimate or missing, and each section links to the to-do items that mention it. Names, Social Security numbers and bank numbers are left for you to type. taxtrace entry writes the same sheet to a file.

3

Plan the year

The Overview shows what your workspace holds, your to-do list grouped by due date, and the year's tax-saving moves ranked by what each saves. The list is a plain todo.md in your workspace, and ticking an item on the page marks it done there. taxtrace moves works the moves out.

4

Ask in the chat

The chat answers questions about tax rules, forms and what a document is for. Under each answer from a cloud model, the page shows exactly what was sent: digits as #, names and towns as *. taxtrace redact masks a document the same way, to study a form without its values. The chat can't open a document or file anything.

Private by design

Your documents are read on your computer. One optional feature can reach a cloud model, and it only gets text with the values taken out.

  • Your documents never leave your computer. Reading, text recognition on scanned pages, the checks and the entry sheet all run locally. Your workspace is a plain folder on your disk, and taxtrace refuses to put it inside a git repository (a folder of tracked code), where it could be published by mistake.
  • Passwords stay in the Keychain. A locked PDF's password is kept in the macOS Keychain (your Mac's password vault), never in a file or on a command line, and taxtrace keychain setup makes each read ask for your Touch ID or Apple Watch.
  • Any AI model that sees your real values runs on your Mac. Reading the documents is plain code and text recognition, not an AI model. In the chat, the model that answers a question holding your amounts is a local one on your own computer (MLX, Apple's AI software, for example), never a public API.
  • The one exception is the optional chat. By default it tries Claude's API, then Google's Antigravity (its command-line AI assistant), then a model on your Mac, and a cloud model is used only if you gave it a key or installed it. Cloud models see masked text only: digits become #, and names, streets and towns become *s. A question with an amount in it is answered on your Mac and never sent. Run taxtrace ui --models local to keep the chat on your computer entirely.
  • The MCP server is read-only and masked. A locked document is never opened and the Keychain is never asked.
  • No accounts, no usage data. Apart from the optional chat, the only outside lookup is public exchange rates for foreign amounts, from the Federal Reserve, the IRS and the Treasury. Each request names only a currency and a date, nothing about you.

Ready to trace your return?

Install takes about a minute, and your documents stay on your computer.

Read more

Join in

Star it on GitHub

taxtrace collects no usage data, so a star is how I know it helped.

Star on GitHub

Issues and PRs welcome

Found a bug, a form that won't read, or want to add something? Open an issue or send a pull request.

Issues · The repo

Buy me a coffee

If it saved you an evening of retyping, a coffee says thanks.

Buy a coffee