IRS Direct File on GitHub
329 comments
·June 4, 2025tomhow
See also:
Saying Goodbye - https://chrisgiven.com/2025/06/saying-goodbye/
hydrogen7800
I figure that the source code is not the hard part of the IRS making this available to the public, but the interoperability with the revenue system, and its verified adherence to the current tax code. Couldn't those things still be killed by the administration even if the source code is available publicly?
BryantD
Yeah, absolutely. FWIW, the repo notes:
"Direct File interprets the United States' Internal Revenue Code (26 USC) as plain language questions, the answers to which should be known to taxpayers without need of external instructions or publications. Taxpayers' answers are then translated into standard tax forms and transmitted to the IRS's Modernized e-File (MeF) API, which is available for authorized public use."
So in theory it's useful now, but as you say it could easily change.
kevin_thibedeau
The tax code is riddled with euphemisms like EITC that don't mean what it says on the tin. There's no way normies can manage that without instructions.
kccqzy
I thought OP's point is that normies who have no idea what EITC is can simply answer a series of simpler questions that don't mention EITC, and the software figures out whether they can claim the EITC.
onlyrealcuzzo
~30-50% of the population has a pretty simple tax return that they could probably do by filling out the form directly by hand...
jandrese
There are also ambiguous edge cases that can't be answered until someone is audited and the IRS and the Tax attorney hash it out in court.
For example I installed Solar panels many years ago and read the exact wording on the Solar Tax Credit to try to figure out if you could include roof repairs under the panels in the credit. The wording was something like "all costs associated with a solar install". Every installer I talked to said yes, but it seemed dubious so I tried calling the IRS help line to get the answer and the help line was no help at all. A few years later and some court battles lost and that answer is now firmly a "no", making me glad I ignored the installer's advice.
How is tax prep software supposed to handle a situation like that? Some of the for pay options include "audit protection", but I don't know how far that goes. I guess you can attempt to pass all liability on to the customer, but even that seems a bit risky.
And definitely the IRS has its own jargon that doesn't always make sense to the layperson. Why, for example, is a form that you fill out once per tax year called a "schedule"? It doesn't organize anything by date or time!
gleenn
Yes but there are plenty of companies or people that may want to know how the code works and would be motivated enough to read through the code to understand it and having it there in the public makes that possible.
raverbashing
While this seems to apply to a good amount of people, it seems the IRS has an informative enough page https://www.irs.gov/credits-deductions/individuals/earned-in...
However, it is most likely that the people claiming EITC are the least likely to understand the information there
null
rights_reminder
[dead]
fitsumbelay
Piggybacking, I think the "hard part" also includes the decades of success that the tax prep lobby's had in protecting its business interests at the cost of US citizen's welfare. Although the number of states that provide free direct filing has grown from last year -- which I only remember to be substantially less than the 25 who do so today -- it's unclear what the problem is with the remaining 25 including DC where I live
xhevahir
Right, politicians and officials working on behalf of the tax-filing lobby could introduce lots of changes to the tax code with a view to making this software useless.
glookler
The point of open sourcing from a dying ship is that the groups that can modify this software and resell it all start from it as a baseline. Is TurboTax all lean mean code available at a low enough price while still meeting profit expectations if it needs drastic changes?
mrguyorama
What is this repo's marketing budget by any chance?
Intuit's was big enough to pervert American tax policy for decades.
bee_rider
I mean… in some sense, it might be nice is the company doing your tax preparation is not too lean and mean, their whole point is to eat the hit if they screw it up, right? The math is not actually hard.
But, realistically, I guess if a self-service tax prep company messed up your taxes, they’d make sure you end up in arbitration.
sowbug
Imagine this source code becoming the unit tests for the legal code. Future tax-code changes would be accompanied by corresponding changes in GitHub. Inconsistencies would surface as new code and tests break the old ones. As courts introduce new nuances to the law's interpretation, new unit tests would follow.
This wouldn't replace human judgment; nobody in power would allow that. But even the capriciousness of politics can be expressed as Boolean logic (var isDeductible = taxpayerIsMe && !taxpayerIsYou). The tests could at least memorialize all the pork.
naikrovek
good luck with that; interpretation make things like this very difficult, if not impossible.
I agree that this would be nice, however. as a non-lawyer and someone who considers themself to be not a "real" developer (even though I write software every day) I have often wondered how alike law and code are, really, when it comes to defining intent via a keyboard.
robertlagrant
I would prefer it if any change to the IRS rules must be accompanied by a reference implementation and lots of tests.
NoahZuniga
> Taxpayers' answers are then translated into standard tax forms and transmitted to the IRS's Modernized e-File (MeF) API, which is available for authorized public use
The interoperability with the revenue system is provided by a different project, and this API is also used by turbotax and the like. It won't be going away.
The interoperability is not the hard part.
bbarnett
It could easily go away, if there are claims of people abusing the API, or using "unlicensed software to use the API" causing errors. By licensed, I mean "approved to use the API".
There could also be pushes to monetize the API, "Why is this service free!?". Meaning they'd likely require a need to be incorporated, setup a commercial account with them, and have payment method on file, and on and on.
My point is, I can think of dozens of sneaky ways to make that pesky API go away, and I'm not even trying.
NoahZuniga
What I'm getting at is that the interoperability is not the hard part of this project.
freeone3000
I do not know of this capability currently, but if it has enough for eFile, it can also be used to generate a paper return.
yencabulator
For years prior to last good commit. The rules change every year.
HPsquared
Sounds like a business opportunity.
mystified5016
I wouldn't say interop is a huge deal, the main time and cost sink is translating the recursive Gordian knots of tax law into a logically cohesive structure that can be evaluated programmatically. And then you (ideally) must prove its correctness.
Imagine pair programming with a tax lawyer. I'd rather eat my own hands.
rsti0000
DirectFile wasn’t meant to handle complicated edge cases. Most filers have a w2 and a few 1099s, use the standard deduction, and claim a few common credits (e.g., child and earned-income). They could file for free in a few minutes with directfile.
90s_dev
Is this common in Java?
https://github.com/IRS-Public/direct-file/blob/9dd76a786ea69...
mattgreenrocks
That's reactive programming in Java, where you return a callback to be run when an operation completes.
The giveaway is the Mono<T> return type.
deepsun
My eyeballs bleed, and I'm pretty comfortable with Java for many years.
I see the most of it stems from reactive-style programming (reactor.core.publisher.Mono).
Maybe they just tried to fit into one screen? Anyway I'd ask to simplify it, if I was a their team lead.
Hilift
100% test coverage (fingers behind back).
pjc50
Is this what people have to do when they don't have the C# async/await autogenerated state machine?
winrid
Yup. Although to be honest it probably doesn't need to be reactive.
contextfree
I don't really know Java, but .flatMap(...) seems to be equivalent to C# .SelectMany(...) which famously can be interpreted as a monadic bind operator.
The C# query syntax
from x in xs
from y in GetYs(x)
from z in GetZs(y) ...
is equivalent to xs.SelectMany(x => GetYs(x).SelectMany(y => GetZs(y).SelectMany(z => ...)))
which is similar to monadic do-notation in Haskell.So since there is monadic Scala code elsewhere in the project, I wonder if this is a result of someone thinking in Scala and translating it into Java in their head.
jryan49
I can tell you as a person working in a spring boot webflux shop that is pretty bad code. You really don’t want to nest that much. Using atomic references outside the reactive flow is a huge red flag that they don’t know how to program in webflux properly. Not that webflux is easy to use at all and the dx is garbage.
maeln
> Not that webflux is easy to use at all and the dx is garbage
My experience with pretty much any Java framework ... It's sad because I do think (especially since Java 8) that Java is a great language for many things. But the community as this insane tendency to create incredibly convoluted pattern-on-top-of-pattern tooling.
jryan49
Yes. I think micronaut is kind of the sweet spot right now.
mcv
I've seen similar things, in Java as well as some other languages. It's obviously not the preferred way of doing it.
readthenotes1
Unreadable+undebuggable has been the preferred way of doing it for as long as I have seen software
seattle_spring
Seems perfectly readable to me, and I haven't used Java professionally in over a decade. What specifically do you find problematic?
koolba
It is if you’re doing government style work and you want have a job for life creating code that nobody else can read.
Or if you’re in the business of selling extremely wide aspect ratio monitors.
tempest_
It is nested sure but the entire thing fits on 1080p monitor
timewizard
Well... depending on your default level of zoom.
After staring at code for 12 hours a day for a few decades my zoom is 125% by default.
CivBase
So long as you abandon the concept of windows and run your text editor in full screen mode. Good luck with side-by-side diffs.
null
77pt77
Better make those monitors curved
PeeMcGee
It's very common to see from devs that don't really grasp reactive programming. You often see similar things in Angular projects because of RxJS.
pimlottc
Aside from the code, there's also a ton of great design documents and notes under /docs/design [0], including detailed process diagrams for many of the user flows (unfortunately not directly viewable online since they're within zip files; see flow1.zip and flow2.zip)
0: https://github.com/IRS-Public/direct-file/tree/main/docs/des...
ronbenton
Favorite quote(s)
>But as I told the team as the end closed in, “We took a pipedream, and made it a policy choice.” No one can claim with a straight face that Direct File is impossible anymore; bringing it back requires only that our elected leaders make a different choice.
>What I mourn the most, though, is the dissolution of the team, the disregard for the vast impact they were poised and eager to deliver. The team itself is what I am proudest of from my time working on Direct File. Their manic dedication to the mission. The care they consistently took to get it right. The trust and love they had for each other.
tomhow
I moved this from https://news.ycombinator.com/item?id=44187512
null
jmisavage
Found the repo over here if anyone is curious.
anigbrowl
Better fork it quick before some ideologue deletes it and threatens to imprison anyone who looks at it.
dylan604
This is a service. What happens if some ideologue turns off whatever is listening on the government's end? Unless this forked version will then print out a bunch of forms for someone to physically mail in, owning this software without being able to communicate to a digital host is useless.
BHSPitMonkey
> Unless this forked version will then print out a bunch of forms for someone to physically mail in
Well yes, this is in essence what tax return preparation software has always been; The end result is a completed set of values to fill into the boxes of form 1040 (and whatever additional forms are deemed to be required), which can then be filed electronically or written/printed on paper to be returned at an office or by mail.
rsti0000
The IRS accepts efilings in a prescribed format so that isnt a danger. If you look at a tax transcript produced from efiling vs a paper return, there is no material difference besides the fields related to how they were submitted.
dataflow
If you're actually worried about this, you should be cloning locally, not forking.
90s_dev
Or just glance at the code out of idle curiosity and move on with our lives?
timewizard
Never turn down an opportunity to spew breathless hyperbole into Hacker News!
timerol
Who among us has not accidentally made a new repo as just a submodule pointer instead of actually committing the files? https://github.com/IRS-Public/direct-file/commit/2f3ebd66932...
It's also fun that, because this is from the US, they can't just use CC0, but instead need to clarify that this must be public domain, separately from the worldwide CC0.
runako
Another way of saying this: Creative Commons, based in California, USA, did not publish a license that can be used by one of the largest domestic authors of software.
Less snarkily, I do wonder about the discrepancy there.
gowld
Category Error. Public Domain is not a license. It is a state of being.
Creative Commons is a worldwide organization, not a jurisdiction-specfic organization. Creative Commons does not have the authority to harmonize laws worldwide.
deepsun
In other words, think of Copyright. A Copyright holder can apply any license they like, and change the licenses for new versions whenever they like. Public Domain is explicit forfeiting the Copyright, which means authors cannot enforce any license (and anyone can just take their work and declare it it's theirs, apply licenses etc).
PS: AFAIK, however, Authorship rights are different from Copyright, and cannot be given/passed as Copyrights, at least in US.
globular-toast
It's not that they can't, it's just pointless to offer a licence for something that's in the public domain.
Also it's important to remember these works are not in the public domain because someone declared them to be, they are simply because they are works carried out by the US government. Similar to how copyright is automatic, it's not applied only when you put the copyright symbol, that's just informational.
timhigins
> Exempted Code
> Not all source code, documentation and metadata used in the development of Direct File is included in this repository. Specifically, any code or data that is considered Personally Identifiable Information (PII), Federal Tax Information (FTI), Sensitive But Unclassified (SBU), or source code developed for National Security Systems (NSS), as defined in 40 U.S.C. § 11103, is exempt. Due to these restrictions, certain pieces of functionality have been removed or rewritten.
Very curious about what these pieces are that were removed
dlcarrier
It's probably a boilerplate notice put on all releases. Sometimes they aren't even allowed to explicitly state that something was excluded, so they have to put that notice on all releases, so there's no way to infer which releases have exclusions.
Zambyte
Why was the IRS-Public[0] group created for this, instead of using the existing irsgov[1] group?
ronbenton
Sadly this program is being killed by the current admin. This repo looks great. The scala fact graph is super neat and there is clearly a lot of care that went into making the tutorial for it.
ryandrake
I'm sure everyone working on this knew it was doomed before the first line of code was written, and that it would be killed as soon as the next (R) was in charge. It was a great accomplishment to get working software released before that happened, but I'm sure nobody was kidding themselves into thinking it would last. The pay-to-file tax lobby is too strong and corrupt.
afavour
I don't know about that. Inertia is a strong force but it goes in both directions. Had this administration been a Democratic one four years might be long enough to establish it strongly enough that it would be very difficult to remove. Look at the Affordable Care Act. Imperfect though it was, Republicans have pledged over and over that they're going to get rid of it but when it power it seems they just can't.
ryandrake
I hope you're right, but this administration so far has found almost no limit to the number of projects, lives, roles and institutions it can destroy or at least attempt to destroy. And the party that is supposed to be acting as the Opposition is basically letting them do whatever they want unhindered. Unless you consider "holding up little signs and making frowny-faces" to count as "doing something."
PaulDavisThe1st
The House budget bill is likely to separate more people from health insurance coverage than the ACA increased it by. It may not be an explicitly "repeal the ACA" act, but practically speaking, it will have a similar effect.
analogwzrd
A couple of decades ago tax code transparency and making it easier and cheaper to file your taxes would have been a very Republican policy. Point taken that the current administration is particularly destructive, but I wouldn't expect Democrats to be very staunch in support this either. The tax/accountant lobby would influence both parties.
shigawire
But Democrats created the program? Why do you expect they wouldn't support it?
paleotrope
Tax return on a postcard is still in the Republican area of ideas, but they can't seem to get enough actual Congressional Republicans to come on board. It's frustrating. The problem to me is that the Democrats have become so uncompetitive in large swathes of the country, that too many center/moderates/status quos adapt Republican cover to get into office.
I'm sure Democrats can complain about their Senators in the same language.
zbentley
> it was doomed before the first line of code was written
The Direct File system was live more than a year ago, I thought: https://www.usds.gov/impact-report/2024/directfile/
…or did you mean “eventually doomed” rather than “doomed to not ship at all”?
standardUser
It is not typical for an (R) administration to aggressively reverse every decision made by their predecessor. Historically, citizens, businesses and government agencies could all expect significantly more stability from one administration to the next.
pjc50
I don't think so - the destructiveness of the current administration is really unprecedented.
90s_dev
All software has an expiration date.
andreygrehov
The bill was introduced by the Republican party (Nick Langworthy, co-sponsored by William Timmons). Don't spread misleading/fake information.
junar
No, I think you have it mixed up. It's quite clear that the authority came from the 2022 Inflation Reduction Act, which was was well known to have passed without a single Republican vote. It's also quite clear that in the context of the top-level comment, "this program" mentioned means the Direct File as it operates, not the release of source code.
> The Inflation Reduction Act (IRA) was signed into law in August 2022.1 Section 10301(1)(B) of the IRS provided the Internal Revenue Service (IRS) with $15 million to establish a task force to design an IRS-run, free direct electronic filing (e-file) system commonly referred to as “Direct File” ...
https://www.tigta.gov/sites/default/files/reports/2025-03/20...
You're bringing up an unrelated law that didn't even exist at the time of the launch of Direct File in early 2024.
andreygrehov
I was under the impression that the OP was talking about the SHARE It Act.
aquova
That would be the current ruling party
andreygrehov
That is the current ruling party. Nobody is trying to kill the SHARE It Act. The Direct File was a pilot program. There are other options: https://www.irs.gov/filing/irs-free-file-do-your-taxes-for-f...
divbzero
Related discussion from last week:
IRS Direct File - https://news.ycombinator.com/item?id=44131901 - May 2025 (62 comments)
adamdecaf
There's quite the mix of languages involved!
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
YAML 452 158 693 161655
JSON 396 1 0 155975
JavaScript 7 21 4513 123150
TypeScript 741 7913 19645 80869
XML 66 5208 1006 60935
Java 725 7380 2283 37863
Scala 272 3275 1423 25395
CSV 146 0 0 25335
Markdown 86 5019 21 9228
SVG 12 5 1749 9130
HTML 39 52 4 4073
Maven 16 61 87 1963
SCSS 47 380 85 1662
Scheme 5 121 0 864
Python 13 185 96 668
Bourne Shell 17 94 127 541
DOS Batch 2 30 0 268
CSS 1 17 0 81
Properties 9 0 24 60
Text 3 1 0 35
TOML 1 6 0 26
Dockerfile 1 8 1 19
INI 1 0 0 7
SQL 4 0 0 5
-------------------------------------------------------------------------------
SUM: 3062 29935 31757 699807
-------------------------------------------------------------------------------
epcoa
Other than the flourish of adding some Scala to enterprisey Java there is absolutely nothing atypical about this bog enterprisey application. It’s a JS/TS/Java app, nothing else stands out.
Listing every config language and a few lines of CI or whatever scripts shit is misleading.
I see nothing other than typical boring enterprise/big gov crap here (which is fine, and expected).
ranie93
off-topic: would you share how you compiled this info?
wonger_
Looks like https://github.com/AlDanial/cloc
https://github.com/IRS-Public/direct-file