A YAML-based system for preparing US federal and state tax returns with an AI agent. You provide your tax documents, the agent extracts the data, builds your return, checks for errors, and presents the results — all in plain text files you can read, edit, and version.
Taxdown works like a build system for tax returns:
- Source files (YAML) hold raw data from your W-2s, 1099s, and other forms
- Input files (YAML) capture things like business expenses and deduction choices
- A manifest (
manifest.yaml) defines the dependency graph - A build step computes all schedules and Form 1040, with full provenance on every line
Every piece of data enters the system in exactly one place. Downstream outputs are derived artifacts with every value traced back to its origin.
| Form | Coverage |
|---|---|
| Form 1040 | Complete federal individual return |
| Schedule C | Self-employment business income and expenses |
| Schedule SE | Self-employment tax (Social Security + Medicare) |
| Schedule A | Itemized deductions (SALT, mortgage, charitable) |
| Schedule D | Capital gains and losses from investments |
| Schedule E | Rental income and expenses |
| Form 8829 | Home office deduction |
| Form 8889 | Health Savings Account (HSA) |
| CA Form 540 | California state return |
Uses 2025 tax law: current brackets for all filing statuses, standard deductions, SALT cap, child tax credit, QBI deduction, SE tax rates, and HSA limits.
California (Form 540) is fully supported with 2025 tax law:
- All 9 CA tax brackets for every filing status
- CA standard deduction and itemized deductions (no SALT cap, no CA income tax self-deduction)
- Exemption credits with AGI phase-out
- CalEITC (California Earned Income Tax Credit)
- Young Child Tax Credit (YCTC)
- Child and Dependent Care Expenses Credit
- Renter's Credit
- Behavioral Health Services Tax (1% over $1M)
The state module system (cli/states/) is designed so additional states can be added by implementing a single compute() function per state.
- Python 3.10+
- An AI agent that can read files, write files, and run shell commands (Claude Code, Cursor, etc.)
uv sync- Give your AI agent a prompt like this:
I want to prepare my 2025 tax return. Read AGENT-WORKFLOW.md and AGENT-GUIDE.md
for instructions, then walk me through the process. I'll drop my tax documents
into the workspace once you set it up.
- The agent creates a workspace under
returns/and asks you to drop in your tax documents (PDFs, images, or TurboTax.taxfiles). - The agent processes everything — extracting data, creating source files, and drafting input files.
- The agent presents what it found and asks you to confirm. It only asks questions about things it genuinely couldn't determine from your documents.
- The agent builds and validates your return:
python cli/taxdown.py build returns/2025-return/
python cli/taxdown.py validate returns/2025-return/- You iterate — ask what-if questions, fix issues, explore optimizations — until you're satisfied.
A complete working example (fictional Smith household) is included:
python cli/taxdown.py build example-returns/mfj/Check example-returns/mfj/build/summary.md for the results.
Tax forms you received: W-2s, 1099-NECs, 1099-INTs, 1099-DIVs, 1099-Bs, 1098s, 1099-Rs, and any others.
Records you have: Business expenses, estimated payment confirmations, property tax bills, charitable receipts, HSA statements, home office measurements.
Prior year return (recommended): Your 2024 federal return lets the agent infer filing status, dependents, income sources, deduction method, and carryforward items — answering most questions before they're asked.
taxdown/
├── cli/
│ ├── taxdown.py # Build and validate tool
│ └── states/ # State tax computation modules
│ └── ca.py # California (Form 540)
├── templates/ # Blank YAML templates for all file types
│ ├── source-documents/ # W-2, 1099-NEC, 1099-INT, 1099-DIV, 1098, 1099-B, 1099-R (.yaml)
│ └── inputs/ # taxpayer, expenses, deductions, payments, HSA, home office, rental, state (.yaml)
├── example-returns/ # Working examples (mfj, single, mfs filing statuses)
├── views/ # Auto-generated markdown views (gitignored)
├── returns/ # Your returns go here (gitignored)
├── tests/ # Test suite (75 tests)
├── AGENT-WORKFLOW.md # Step-by-step procedure for AI agents
├── AGENT-GUIDE.md # Technical reference for the format
├── extraction/ # Prompts and tools for extracting data from tax documents
└── GETTING-STARTED.md # Detailed getting started guide
- SSNs and EINs are stored as last-4-digits only — never in full
- Your return data lives in
returns/, which is gitignored and never committed - Raw documents in
documents/contain sensitive information — keep them secured - Build output is also gitignored
AMT, education credits, premium tax credit, Schedule K-1 (partnerships/S-corps), foreign income, Form 8949 individual transaction detail, complex QBI phase-outs. State returns other than California are not yet implemented. For unsupported items, consult a tax professional or use tax software for that portion of your return.
This project is provided as-is for personal use. Taxdown is not tax advice — it's a tool to help you organize and compute your return. Always verify results before filing.