itr-wala: a deterministic Indian tax engine wrapped in an agent skill
File your Indian income tax return (ITR) from your terminal. Deterministic tax engine, both regimes, AY 2026-27. Claude Code / Codex / Gemini skill.
At a glance
- What is it?
- itr-wala splits ITR filing into two jobs: an AI reads your Form 16 and AIS, and a Python engine computes every slab, rebate and interest figure. It targets AY 2026-27 filers who will not pay a CA but also will not let a language model do arithmetic.
- Who is it for?
- itr-wala fits a salaried or capital-gains filer with Form 16 and AIS in hand, comfortable running Python from a terminal, and willing to type the portal entries themselves. It does not fit anyone who wants the tool to submit or e-verify on their behalf, or whose income needs a schedule the engine does not model.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 13 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is not reading Form 16, it is applying s.87A
The README states the motivation directly: in most AI tax demos of the season, the model was doing the arithmetic. Reading a Form 16 is a language task and models handle it well. Applying the s.87A rebate cliff, its marginal relief, the surcharge tiers, and s.234A/B/C interest is not a language task. The README gives a concrete failure it caught in its own history: an early build denied surcharge marginal relief on capital-gains-heavy incomes, and a fuzzer run found a rounding edge where 52,880 rupees more salary computed 10 rupees less tax.
The intended user is an Indian taxpayer filing ITR-1, ITR-2, ITR-3 or ITR-4 (non-audit) for AY 2026-27 who has a Form 16 and an AIS, does not want to pay a CA, and is willing to run commands. The README frames the saving against a 3,000 rupee CA fee and roughly three hours on the portal. The project also carries a topic list aimed at agent-skill users: claude-skills, codex, gemini-cli, agent-skills. Both audiences matter, because the install story is really an agent install story.
Two processes, one boundary: the model reads, the engine computes
The split is stated as a table in the README. The AI reads Form 16, AIS and broker P&L, interviews you for missed deductions, explains numbers, and narrates the portal. The Python side computes every slab, rebate, surcharge and cess, compares old versus new regime, handles 87A marginal relief and the 111A/112A/VDA special rates, computes 234A/B/C interest and the 234F late fee, validates the input schema, and cross-checks TDS against 26AS and AIS totals.
The data flow is a file called income.json. Every number is transcribed verbatim into it, then a validator cross-checks totals against the source documents. The README says an unknown key is rejected outright, and a TDS figure that does not match 26AS is flagged. That rejection behaviour is the load-bearing part: a typo cannot reach the engine because the validator sits in front of it.
Three test layers back the math. There are 47 golden tests, each expected value hand-derived from the statute first, covering the 87A rebate cliff and marginal relief, capital-gains exemption ordering, s.71 loss set-off, the surcharge tiers including the exclusive-income tests for the 25% and 37% slabs and the 15% ceiling on capital-gains tax, and interest down to month-counting and challan-date edge cases. There is a second suite of 104 tests for the input validator. There is a property-based fuzzer at scripts/fuzz_engine.py that generates randomized boundary-biased returns and asserts invariants: more income can never mean less tax in the new regime, cess is exactly 4%, rounding follows s.288A/288B, and the recommendation matches the cheaper legal option. The README says CI replays 3,000 cases per commit and that 350,000+ were swept before release.
Install paths, and why the checkout path is the one that matters
The README offers four routes. The recommended one is review-first:
git clone https://github.com/karanb192/itr-wala.git cd itr-wala && ./install.sh
The install script also accepts codex, gemini or all as arguments. A second form scopes the install to a folder: cd ~/tax-2026 && ~/itr-wala/install.sh --here. The README states that when run from a checkout, install.sh never touches the network and copies the files you just read.
The other three routes fetch code you have not read. Claude Code uses /plugin marketplace add karanb192/itr-wala followed by /plugin install itr-wala@itr-wala. Codex uses codex plugin marketplace add https://github.com/karanb192/itr-wala and codex plugin add itr-wala@itr-wala. The skills.sh one-liner is npx skills add karanb192/itr-wala, which the README notes fetches the default branch head.
After install, you open your agent and say "file my ITR". The README is explicit that three actions stay with you: pay, submit, e-verify. The tool never sees your password or OTP. The self-test is a plain command: python3 skills/itr-wala/scripts/test_tax_engine.py. The README notes that if you installed as a plugin and cannot find the path, you can ask the agent to run the itr-wala self-test instead. The engine itself runs as python3 skills/itr-wala/scripts/tax_engine.py skills/itr-wala/assets/example-income.json.
The session, in the order the README gives it
Seven steps. Self-test first, so the engine proves its arithmetic before you trust anything downstream. Then documents: you drop Form 16 and AIS as JSON into a folder, and the README says the tool tells you where to download each one. Then extraction and validation into income.json. Then a deduction interview covering 80C, 80D, NPS, HRA and home loan, on the argument that the portal will never prompt you for these. Then both regimes computed into a comparison table with the rupee gap. Then a filing pack that maps every portal field to its value in order, plus the final payable or refund figure. Then the portal itself, narrated while you type.
The bundled example is fictional and the README prints its output. Running the engine on skills/itr-wala/assets/example-income.json yields gross total income of 26,06,700 under the new regime against 22,09,300 under the old, total tax of 3,00,350 against 3,39,730, net payable of 720 against 43,530, and a recommendation of the new regime saving Rs. 42,811. Treat that as a format sample, not a benchmark. It is one fictional return, and the README presents it as reproducible from the bundled example rather than as a performance claim.
Where the design breaks down
The privacy section is the clearest trade-off, and the README does not hide it. The Python scripts run entirely on your machine, so the tax math never leaves. But documents you ask the AI to read are processed by the model. The README's own sentence trails into "that part does de" in the supplied text, so the full caveat is not visible here. What is visible is enough to state the boundary: the arithmetic is local, the document reading is not. If your Form 16 or AIS cannot leave your machine, the extraction step is the part you have to think about, not the engine.
There is a second constraint. The engine is a calculator and a validator, not a filing interface. The README repeats that you alone pay, submit and e-verify. Anyone expecting end-to-end automation will be disappointed, and that is deliberate: the tool refuses the part of the job where a mistake is unrecoverable.
The licence is listed as NOASSERTION, which means the repository's licence metadata does not resolve to a recognised SPDX identifier. The README does not discuss licensing terms. Before you redistribute the skill or bundle it into anything, read the LICENSE file in the checkout yourself. Nothing here is legal advice.
The README also states that the AY 2026-27 due dates for ITR-1/2 (31 July) and ITR-3/4 non-audit (31 August) have passed, and that a belated return is still possible until 31 December 2026 with a late fee of 1,000 rupees under section 234F if income is up to 5 lakh, otherwise 5,000, plus interest on unpaid tax. The engine computes 234F, so the cost of lateness is part of the output rather than a footnote.
The alternative is a CA, and the difference is not price
The obvious comparison is a chartered accountant, and the README frames it that way with the 3,000 rupee fee and the three hours on the portal. The real difference is not cost. A CA carries professional judgement about whether a position is defensible, and takes on the correspondence if the department asks questions. itr-wala carries a test suite and a validator, and takes on nothing after you submit. The README's own line is that if your CA can show you their test suite, hire them. That is a fair summary of what the tool does and does not replace.
Against a prompt-only tax assistant, the difference is narrower but sharper. A prompt-only tool can read your Form 16 just as well. What it cannot do is run 47 golden tests and a seeded fuzzer in front of you, or pin a discovered rounding bug as a regression test. The README makes that point explicitly: the find-fix-pin loop is the thing a prompt-only tool cannot run. That is the actual product boundary, and it is a testable claim rather than a marketing one. You can run the suite yourself in under a second according to the README's own transcript, which reports 47 tests in 0.002s.
Maintenance cost and what to verify before you file
Tax engines rot on a schedule. Slabs, rebate thresholds and surcharge tiers change with each Finance Act, and the repository is scoped to AY 2026-27. Nothing in the supplied material describes a policy for prior or future assessment years, so treat the engine as valid for the year it names and check the repository before reusing it next season. The last push recorded is 2026-09-02, and no releases were retrieved, so there is no tagged version to pin. If you clone, you are tracking main.
Verification is cheap and the README hands you the commands. Run python3 skills/itr-wala/scripts/test_tax_engine.py and confirm the 47 tests pass on your machine. Run the engine against skills/itr-wala/assets/example-income.json and check that the printed figures match what the README shows. Then, and only then, point it at your own documents, and read income.json line by line before the engine consumes it, because that file is the one place where a transcription error can still enter. The validator catches unknown keys and TDS mismatches against 26AS, but it cannot know that a number you typed is the wrong number from the right document.
Editorial conclusion
itr-wala fits a salaried or capital-gains filer with Form 16 and AIS in hand, comfortable running Python from a terminal, and willing to type the portal entries themselves. It does not fit anyone who wants the tool to submit or e-verify on their behalf, or whose income needs a schedule the engine does not model. Before you trust it, run python3 skills/itr-wala/scripts/test_tax_engine.py, then run the engine against skills/itr-wala/assets/example-income.json and confirm you can reproduce the printed figures by hand.
Community notes