opentax.filed.com - Fully open-source federal tax calculation engine. Single binary. Runs on macOS, Linux, and Windows.
Note: This engine calculates taxes accurately for use by AI agents and developers. For filing your taxes, visit irs.gov.
Built and maintained by AI agents using official IRS publications as the sole source of truth.
Covers Form 1040 (TY2025) today. Additional forms and state returns coming.
- Professional tax calculation engines are closed source, expensive, and built for humans — making it hard for AI agents to reliably use one as a calculator
- AI agents have drastically reduced the cost of building and maintaining a tax engine. It only makes sense to do it in the open
- This project aims to be the first truly open-source, up-to-date tax calculation engine that works for everyone
Designed for the AI era:
- Built to be run by AI agents more than humans
- Single binary CLI that AI agents can download and run instantly
- Everything stored locally. Open, secure, and accessible
Inspired by Andrej Karpathy's autoresearch, an autonomous loop where AI agents modify code, measure results, and keep only improvements. OpenTax applies the same idea to tax calculation: agents read IRS instructions, write implementations, generate test cases, and fix regressions in a continuous loop.
Copy-paste this into Claude Desktop app:
Load the skill here using curl or equivalent:
https://raw.githubusercontent.com/filedcom/opentax/main/skills/opentax/SKILL.md
Then run the onboarding flow.
If you use Claude Code, install OpenTax as a plugin so the skill is always available:
- Add the marketplace:
/plugin marketplace add filedcom/opentax
- Install the plugin:
/plugin install opentax@opentax
- Use the skills:
/opentax:opentax # guided onboarding, picks the right skill for you
/opentax:tax-preparer # prepare a return from scratch
/opentax:tax-reviewer # audit a completed return against source docs
One command. No runtime, no installer, no dependencies.
curl -fsSL https://raw.githubusercontent.com/filedcom/opentax/main/install.sh | sh- Detects your OS and architecture automatically
- Downloads the right binary and puts it in your PATH
Or download manually:
| Platform | Download |
|---|---|
| Mac (Apple Silicon) | opentax-macos-arm64 |
| Mac (Intel) | opentax-macos-x64 |
| Windows | opentax-windows-x64.exe |
| Linux (x64) | opentax-linux-x64 |
| Linux (ARM) | opentax-linux-arm64 |
$ opentax return create --year 2025
{ "returnId": "a1b2c3" }
$ opentax form add --returnId a1b2c3 --node_type general '{"filing_status": "single"}'
{ "id": "general_01", "nodeType": "general" }
$ opentax form add --returnId a1b2c3 --node_type w2 '{"box1_wages": 55000, "box2_fed_withheld": 5200}'
{ "id": "w2_01", "nodeType": "w2" }
$ opentax return get --returnId a1b2c3{
"returnId": "a1b2c3",
"year": 2025,
"summary": {
"line1z_total_wages": 55000,
"line9_total_income": 55000,
"line11_agi": 55000,
"line15_taxable_income": 39250,
"line24_total_tax": 4471.5,
"line33_total_payments": 5200,
"line35a_refund": 728.5
},
"lines": {
"filing_status": "single",
"line1a_wages": 55000,
"line12a_standard_deduction": 15750,
"line15_taxable_income": 39250,
"line16_income_tax": 4471.5,
"line24_total_tax": 4471.5,
"line25a_w2_withheld": 5200,
"line33_total_payments": 5200,
"line34_overpayment": 728.5,
"line35a_refund": 728.5
}
}$55,000 in wages, $15,750 standard deduction, $39,250 taxable income, $4,471.50 tax, $728.50 refund. Every line traces back to the IRS instructions.
The catalog currently exposes federal Form 1040 for TY2025. Registered nodes do
not prove complete coverage of every tax situation, other tax years or states.
return get is useful for partial calculations and diagnostics; inspect its
warnings before relying on amounts. return validate checks implemented MeF
business rules, not all tax law or IRS acceptance criteria.
Normal PDF/MeF export blocks on every executor diagnostic, even with --force.
--force overrides only reject-severity business rules. It is not a calculation
repair or evidence that a return is ready to file. Existing callers that used
--force to export incomplete calculations must now opt into --draft.
For diagnostic review, use --draft (and --force separately if business rules
reject). Every draft XML includes a DRAFT/INCOMPLETE comment; every draft PDF is
watermarked on each page. Draft mode does not guarantee that malformed data can
be rendered. Successful non-draft API return types remain XML text or a PDF path.
The new ExportExecutionError exposes executor entries separately from
ExportRejectedError. Shell redirection may create an empty file on failure;
check the command exit status, not just file existence.
CLI export does not perform XSD validation. Optional developer XSD tests need the separate IRS schema bundle and skip when it is absent. The CLI has no transmission or acknowledgement retrieval command. Signatures, authorized transmission, applicable IRS testing/identifiers, state coverage and acceptance handling must be established separately. Export is neither filing nor acceptance; these facts do not establish any commercial product's IRS authorization.
Export offers MeF preparation the files a return names: PDFs from the return's
attachments/ folder, matched by the file name its inputs use, and retained
copies from retained/, matched by reference. A source copy whose bytes an
input needs is stored as "bytes": {"sha256": "<digest>"} (or
{"retained": "<file name>"}) and read from retained/. A missing file is
reported with the path it belongs at.
The CLI stores returns locally. Uploading source documents into a hosted assistant is a separate disclosure to that provider, not local-only processing.
# Validate against IRS MeF business rules
opentax return validate --returnId a1b2c3
# Export as IRS MeF XML for downstream validation or transmitter workflows.
# This does not transmit a return or prove IRS acceptance.
opentax return export --returnId a1b2c3 --type mef > return.xml
# Package it as a Pub 4164 submission ZIP (manifest/, xml/, attachment/) named
# by its Submission ID. Needs the originator EFIN, the IRS-assigned Software ID
# and a reviewed residency JSON (default returns/<id>/residency-review.json).
opentax return export --returnId a1b2c3 --type mef-submission --efin 123456 --software-id 25000000
# Add a PDF filed with the return, under the file name its inputs use;
# --description when the form needs a specific MeF attachment description
opentax return attach --returnId a1b2c3 --file ./policy.pdf --name 2025-leave-policy.pdf
# Add a retained source copy (kept, not transmitted) under the reference its inputs use
opentax return attach --returnId a1b2c3 --file ./notice.pdf --reference "2023 CTC notice copy"
# List entries in a return
opentax form list --returnId a1b2c3
# Update or delete a form entry
opentax form update --returnId a1b2c3 --entryId w2_01 '{"box1_wages": 60000, "box2_fed_withheld": 5800}'
opentax form delete --returnId a1b2c3 --entryId w2_01
# Inspect what fields a node expects
opentax node inspect --node_type w2
# List all registered nodes
opentax node listOpenTax tells you when a new version is available:
$ opentax return get --returnId abc-123
{ ... }
Update available: 0.1.0 → 0.2.0. Run `opentax update` to upgrade.
To update:
opentax updateThat's it. The binary replaces itself with the latest release.
Check your current version anytime:
opentax version131 input nodes covering the full range of 1040 source documents: W-2s, 1099s, all major schedules, credits, capital transactions, and more.
See catalog.ts for the complete list of supported nodes and their schemas. Or from the CLI:
opentax node listThe engine is a directed graph of nodes. Each node is a pure function: validated input in, typed output out. No state, no side effects.
- Schemas defined with Zod, types inferred (never duplicated)
- Immutable data throughout, no mutation anywhere
- Type-safe output routing between nodes enforced at compile time
- 133 real-world benchmark scenarios
AI agents maintain the codebase:
- Read IRS instructions
- Write node implementations
- Generate test cases from official IRS exercises
- Fix regressions
- Prove each change with the harness before it ships
All traced back to the authoritative IRS source.
Requires Bun 1.4. Run bun install once after cloning.
Two CLIs, kept apart: cli/main.ts is the product, and the harness is what you
use while building it. The harness is dev-only and documented in
scripts/testing/README.md; agent instructions live
in AGENTS.md.
# Prove a change before a pull request (what CI runs)
bun run check:structure # nodes placed, registered, reachable
bun run check:cases # benchmark cases fit their node schemas and cite a source
bun run check:oracle # expected values changed only with a cited ledger entry
bun run check:sandbox # the binary reaches the network only through restricted fetch
bun run test:unit # module graph, type check and typed tests
bun run test:forms # node, export and return-processing tests
# Run the full test suite and the accuracy benchmark
bun run test
bun run bench
# Run the CLI in dev mode, or build the single-file binary
bun run tax return create --year 2025
bun run compileThe TY2026 research corpus contains the implementation
plans and the source manifest. The IRS PDFs it cites are not in Git: fetch them
into the gitignored irs/corpus/ty2026/ with python3 docs/ty2026/corpus/download.py
and check them with bun run check:irs (see irs/README.md).
The repo includes four skills that automate the full development lifecycle. Open the project in Claude Code and invoke them with /skill-name.
Run this first. Shows pass/fail counts, pending root causes, and build phase for every form.
/tax-status
Autonomous bug-fixing loop. Reads failing benchmark cases, clusters them by root cause, spawns parallel fixer agents, validates with the harness, and commits net-positive engine fixes only; benchmark cases are never edited to pass. Loops until all cases pass or progress stalls.
/tax-fix f1040:2025
Sources test cases from IRS publications (VITA exercises, Pub 17, MeF test packages) and validates what it writes with bun run check:cases. Run /tax-fix after to see how the engine performs on the new cases.
/tax-cases vita # VITA Pub 4491 training exercises
/tax-cases pub17 # Publication 17 worked examples
/tax-cases "senior with SSA and 1099-R" # free-form scenario
End-to-end form builder. Researches IRS instructions, extracts ground truth, builds all nodes section by section, then runs a validate + fix loop until >= 95% of benchmark cases pass. Resumes if interrupted.
/tax-build 1120
Adding a new form:
/tax-cases f1120:2025 vita # source benchmark cases first
/tax-build 1120 # build nodes, iterate until >= 95% pass
/tax-status # confirm it's green
Fixing a regression:
/tax-status # find what's failing and why
/tax-fix f1040:2025 # autonomous fix loop
Expanding test coverage:
/tax-cases pub17 # pull new IRS examples
/tax-fix f1040:2025 # fix loop against expanded case set
Thanks to everyone who has contributed!
Dual-licensed under AGPL v3 and the Filed Commercial License. For commercial licensing inquiries: otta@filed.com