itr-wala: Indian ITR filing from your terminal, with the tax math kept out of the model

The problem itr-wala was built around

Most AI tax demos this season shared a structural flaw: the language model did the arithmetic. The README states the reasoning plainly, that LLMs read a Form 16 well and apply s.87A marginal relief badly, and that one transposed digit turns free filing into a notice. itr-wala is aimed at the individual filer who would otherwise pay a CA roughly ₹3,000 for a return they could prepare themselves, and who is willing to run Python locally rather than trust a web form. It is scoped to AY 2026-27 and covers both regimes. The README also notes the primary due dates for ITR-1/2 and non-audit ITR-3/4 have passed, and that a belated return can still be filed until 31 December 2026, with a ₹1,000 late fee under section 234F if income is up to ₹5 lakh and ₹5,000 otherwise, plus interest on unpaid tax.

How the AI and the engine divide the work

The split is explicit in the README's table. The agent reads your Form 16, AIS and broker P&L, interviews you for missed deductions, and explains numbers. The Python engine computes every slab, rebate, surcharge and cess, compares old against new regime, and handles 87A marginal relief, 111A/112A/VDA special rates, 234A/B/C interest and the 234F late fee. A validator sits in front of the engine and rejects malformed, mistyped or PAN-bearing inputs, and cross-checks TDS against 26AS/AIS totals. Three test layers ship in the repository and run in CI on every commit: 47 golden tests with expected values hand-derived from the statute, a 104-test suite for the input validator, and a seeded property-based fuzzer in scripts/fuzz_engine.py that asserts invariants such as more income never meaning less tax in the new regime and cess being exactly 4%. The README reports the fuzzer caught a one-in-350,000 floating-point rounding edge where ₹52,880 more salary computed ₹10 less tax, and that both that and an earlier surcharge marginal-relief bug are pinned as regression tests.

Installing itr-wala and running a first return

The README gives four install paths. The recommended one is review-first: clone the repository, read it, then run install.sh from the checkout, which the README states never touches the network and copies the files you just read.

git clone https://github.com/karanb192/itr-wala.git
cd itr-wala && ./install.sh

The script also accepts codex, gemini or all as arguments, and a --here flag scopes the install to the folder your tax documents live in.

cd ~/tax-2026 && ~/itr-wala/install.sh --here

Claude Code and Codex each have a plugin route, and there is a skills.sh one-liner that fetches the default branch head.

/plugin marketplace add karanb192/itr-wala
/plugin install itr-wala@itr-wala
codex plugin marketplace add https://github.com/karanb192/itr-wala
codex plugin add itr-wala@itr-wala
npx skills add karanb192/itr-wala

Before trusting any of it with a salary figure, run the engine's own suite. The README shows this command and the output it produces: 47 dots, then Ran 47 tests in 0.002s, then OK.

python3 skills/itr-wala/scripts/test_tax_engine.py

Then open your agent and say "file my ITR". The session runs in seven stages: self-test, documents, extract and validate into income.json, a deduction interview covering 80C, 80D, NPS, HRA and home loan, both regimes computed with a rupee comparison, a filing pack mapping each portal field to its value, and finally the portal itself, which the agent narrates while you type. The README is explicit that it never sees your password or OTP, and that you alone click Pay, Submit and e-Verify. To see the shape of the output without your own documents, run the engine against the bundled fictional example.

python3 skills/itr-wala/scripts/tax_engine.py skills/itr-wala/assets/example-income.json

The README shows that example producing a new-regime total tax of 3,00,350 with 720 net payable, an old-regime total of 3,39,730 with 43,530 net payable, and a recommendation of the new regime saving Rs. 42,811.

Where itr-wala is the wrong tool

The engine is deterministic, which also means it is only as good as the inputs and the rules it encodes. The validator rejects unknown keys and flags TDS that does not match 26AS, but it cannot adjudicate a position the statute leaves arguable, and nothing in the README suggests it takes over audit defence or representation. If your situation needs a professional's judgement on characterisation rather than arithmetic, this is not a replacement for a CA. The privacy section is candid about the other boundary: the Python scripts run entirely on your machine, but documents you ask the AI to read are processed by the model, so the confidentiality of a Form 16 depends on which agent and provider you point at it. The install.sh path exists precisely because the tool handles salary and bank data, and the README frames the choice of repository as a choice of what you trust. There is also a coverage boundary worth naming: the README describes ITR-1 through ITR-4 due dates and non-audit ITR-3, and does not claim support for audited cases. And the README does not document rollback or uninstall steps for a plugin install, so if you need a clean removal path, plan for it before you install rather than after.

How this differs from a CA-prepared return or a portal-only filing

The meaningful difference is not that itr-wala files for you, because it does not. You still type into the portal and you still e-verify. The difference is where the arithmetic happens and whether you can inspect it. A CA-prepared return gives you a professional's judgement and accountability, and in exchange you see a summary rather than the slab-by-slab derivation. A portal-only filing gives you the department's own computation, but the portal will not proactively interview you about 80C, 80D, NPS, HRA or a home loan, and it will not show you a side-by-side regime comparison with the exact rupee gap. itr-wala's contribution is the comparison table plus a test suite you can run in front of yourself. That is a real trade: you take on the verification work, and you get to see the working. The README's line about asking your CA to show their test suite is the honest framing of that trade, not a claim that the tool replaces professional advice.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-02. The GitHub licence field reads NOASSERTION, which means GitHub could not classify the LICENSE file automatically; the file is present at the repository root, so read it directly rather than treating the label as the answer, and note that nothing here is legal advice. Upgrade cost is low by design for the review-first path: install.sh copies files from a checkout and does not touch the network, so updating means pulling the branch and re-running the script. The plugin and skills.sh routes behave differently, and the README notes the skills.sh one-liner fetches the default branch head, which means you get whatever is current rather than a pinned revision. CI runs the golden suite on every commit, so a pull that breaks the math should fail before you run it, but that only holds if you actually run the suite after updating. The README lists no releases, so there is no version tag to pin to; the branch is the unit of upgrade.

Editorial conclusion

itr-wala fits a salaried or capital-gains filer with a Form 16 and AIS in hand who wants both regimes compared in rupees and a deterministic engine they can read before trusting. It is the wrong tool if your return needs audit-grade judgement, if you will not read the code you install, or if you expected a hosted portal with a login and a status page. Before filing, run the golden suite yourself and confirm the bundled example reproduces the documented numbers, then check the AY 2026-27 belated-return window against your own income level.

Frequently asked questions

Official sources

1. Issues
2. karanb192/itr-wala on GitHub
3. Project website
4. README