IRS open-sources Direct File free tax filing code, with a warning not to run it in production

The IRS has published the source code for Direct File, the government-run service that lets US taxpayers file federal returns for free directly with the tax agency. The repository, hosted on GitHub under the IRS-Public organization, drew attention after reaching the Hacker News front page. It documents much of the code behind the service, along with a prominent caveat: the repo is archived, unmaintained, and should not be deployed anywhere.

What Direct File does

According to the repository's README, Direct File is an interview-style filing tool. Rather than presenting blank tax forms, it walks taxpayers through questions written in plain language, designed so that answers should be known without consulting external instructions or IRS publications. The service was built to work as well on a phone as on a desktop, is offered in English and Spanish, and was designed to accommodate a wide range of abilities and access needs.

Answers are converted into standard tax forms and submitted through the IRS's Modernized e-File (MeF) API, which the README notes is available for authorized public use. The question set and its logic were developed with the IRS Office of Chief Counsel and reflect US tax law as of Tax Year 2024. The README suggests the accompanying test cases and scenarios could be useful to anyone building products that need to interpret US tax law accurately.

The Fact Graph

The most technically distinctive component is what the README calls the Fact Graph: a declarative, XML-based knowledge graph built to draw conclusions from partial data, such as a return that is only half completed. It is written in Scala, runs on the JVM on the backend, and is transpiled with Scala.js so the same logic can also execute in the browser during a filing session.

The README points out that the Fact Graph is not specific to taxation, and says it may be useful to other revenue agencies or serve as a reference for anyone implementing business rules engines.

Handing off state returns

Direct File files federal returns only, but US taxpayers typically owe state and local taxes as well. To bridge that gap, the service exposes a State API that lets taxpayers move their federal data into a third-party tool capable of filing state or local returns without re-entering information. According to the README, the transfer includes standard MeF XML plus an enriched JSON format carrying additional data elements that state revenue agencies identified as useful for simplifying the state filing experience.

An archive, not a product

The GitHub repository is explicitly archived and no longer maintained. The README warns that the code may contain unpatched or unknown vulnerabilities and should not be used in production systems, framing the release as a historical reference rather than a live open-source project.

It is also incomplete by design. Code and data classified as personally identifiable information, federal tax information, sensitive but unclassified material, or National Security Systems source code, categories defined under 40 U.S.C. § 11103, are exempt from publication, and the IRS says certain functionality was removed or rewritten as a result. An onboarding file remains in the repo for anyone who wants to run Direct File locally.

Legal grounding and the team behind it

The README lists the legal authorities behind the release, most notably the Source Code Harmonization and Reuse in Information Technology Act of 2024, Public Law 118-187, which directs federal agencies to share certain source code. It also cites OMB Memorandum M-16-21 on federal source code policy, the Federal Acquisition Regulation's patents and data provisions, and earlier statutes such as the E-Government Act of 2002 and the Clinger-Cohen Act of 1996.

The service itself was developed by an in-house team of technologists at the IRS, a blended cross-agency group that included support from the US Digital Service and the General Services Administration, along with vendor teams from TrussWorks, Coforma and ATI.

Why it matters

Even in archived form, this is an unusual release. It exposes the actual question logic a national tax authority uses to translate the Internal Revenue Code into language an ordinary taxpayer can answer, complete with test scenarios, which is valuable reference material for tax software developers and anyone studying how such systems are validated. The Fact Graph offers a reusable pattern for rules engines that must tolerate incomplete data, an idea relevant well beyond tax filing. And as one of the more visible code drops under the 2024 federal source-code sharing law, it illustrates how agencies may fulfill such mandates: publish for transparency and reuse, while clearly separating reference code from production systems. For taxpayers, the practical payoff is Direct File itself, a free direct channel for federal filing; the open-sourced code is the documentation of how that channel works.