Open-source AI Agent tax preparation. Cited facts in, a deterministic return out.
Cade · Canon · Form engine · Sources · Web app · Quickstart
OpenReturn prepares your US federal and California return, or an estimate, on your own machine. Twin agents do the work: Cade, your CPA, interviews you and reads your documents. Canon, your tax attorney, checks each of Cade's decisions against the IRS and FTB text. A deterministic form engine computes every line. No AI touches the math.
Taxes shouldn't be as hard as they are today. An entire industry profits from keeping the U.S. tax system difficult and opaque, but it doesn't have to be that way and this project is an attempt to change that system.
You shouldn't have to pay a private company to help you figure out how much money you have to pay to the government!
This project was going to be a startup, but life changed directions. Now I want this to be a collaborative project that has the greatest impact it can.
- A conversation, not a form. Cade asks one question at a time. It reads W-2s, 1099s and photos of them directly.
- Every fact has a citation. Each value records where it came from: a document, a statement line, or "you told me, on this date".
- Never an invented number. An unknown becomes an open question, not a guess.
- Decisions are checked. In the background, Canon grounds each judgment call in the IRS and FTB instructions. It cites the passage or reopens the question.
- Ask The Tax Code. Ask a tax question and get a short answer with numbered citations into a library of 168 IRS and FTB documents.
- A live draft return. Each new fact runs the engine again. The 1040, the CA 540 and their schedules update as you talk.
- Your data stays local. All data is SQLite files and a documents folder on your machine. No Docker, no Postgres, no hosted services.
- Any model. Use Anthropic, or any OpenAI-compatible server such as Ollama. The smallest model we recommend is Gemma 4 31B; it runs the full flow locally, document reading included. See Evals.
- Your tax data goes to your model. Every conversation turn and every background check sends your tax facts to the model you configured. A local model or your own private infrastructure keeps the data with you; a cloud API (Anthropic, OpenAI) does not.
- This is not tax advice. OpenReturn is in beta and produces drafts. Have a CPA check the work.
- Coverage is narrow — see what OpenReturn supports. Outside it, Cade says "we don't handle that yet" rather than guess.
You need Node.js 22.13 or later, and an Anthropic API key or Ollama with Gemma 4 31B.
git clone https://github.com/captaincole/OpenReturn.git
cd OpenReturn
npm run install:all
npm run dev:all # writes the .env.development files; stop it with Ctrl-C
# set ANTHROPIC_API_KEY (or a local model) in cade/ and canon/.env.development
npm run corpus -- fetch # the IRS + FTB library
npm run dev:all # then open http://localhost:3000The Quickstart guide has the local-model settings and what to explore first.
- You talk to Cade in the web app and upload your documents.
- Cade records tax facts (what you said or what a document shows, with a citation) and decisions (judgment calls, with a rationale).
- The form engine computes the return from the facts and decisions. The inputs it still needs become Cade's next questions.
- Canon checks each decision against the IRS and FTB reference library, and answers your tax-code questions with citations.
Each top-level folder builds and runs on its own, and each has its own README.
| Folder | What it is | Read more |
|---|---|---|
web/ |
The web app: chat, documents, forms, Ask The Tax Code, the reference library. Next.js 16. | web/README.md |
cade/ |
Cade, your AI CPA. The conversational agent: intake, document reading, facts, decisions, form generation. Mastra, port 4111. | cade/README.md |
canon/ |
Canon, your tax attorney. The IRS and FTB reference library, hybrid search, Ask The Tax Code, and the judges that ground Cade's decisions. Mastra and an MCP server, port 4112. | canon/README.md |
engine/ |
The form engine: facts and decisions in, evaluated and filled tax forms out. Pure TypeScript, no AI, no I/O. | engine/README.md |
engine/builder/ |
Dev-time tools that build the engine's assets from blank IRS and FTB PDFs. | engine/builder/README.md |
sources/ |
The documents the IRS and FTB publish, by tax year: blank forms, tax tables and the sidecars for the reference library. | sources/README.md |
docs/ |
Guides for users and contributors, and the model eval reports. | Documentation |
A return. Chat with Cade on the left; the facts, decisions and forms it drafts on the right.
 Home. Your returns, estimates and the tax-code search. |
 Ask The Tax Code. Short answers with numbered citations into the IRS and FTB text. |
Every flow that uses a model has an eval: document ingest (Cade), decision review and Ask The Tax Code (Canon). Each model gets one score per flow. Scores from 2026-10-23; the eval reports have the details.
| Model | Overall | Ingest | Review | Ask |
|---|---|---|---|---|
| Claude Haiku 5.5 | 94% | 100% | 100% | 81% |
| Gemma 4 31B (Q4_K_M) | 85% | 91% | 96% | 69% |
| Gemma 4 26B (Q4_K_M) | 81% | 90% | 81% | 72% |
The smallest recommended model is Gemma 4 31B (ollama/gemma4:31b). Smaller models lose accuracy in decision review.
| Guide | For |
|---|---|
| Quickstart | Run OpenReturn in a few minutes, on a cloud model or a local one |
| Contributing and developer guide | Who can contribute, and how the agents, the corpus, the scenarios and the form engine work |
| Test OpenReturn against your filed return | Check the engine against a return you already filed, privately, and send us the result |
| Add a scenario | Add a new test taxpayer, with new forms or documents, and the tests that check each step |
| End-to-end tests | The Playwright run that drives the whole stack with a real model |
| Model evals | One score per model, by flow: document ingest, review judges and Ask The Tax Code |
OpenReturn computes taxes, so code contributions come from approved contributors. You can also help by checking OpenReturn against a return you already filed. See the contributing guide for both.
AGPL-3.0 — see LICENSE.