itr-wala

File your Indian income tax return from your terminal. No CA, no ₹3,000 fee, no 3 hours on the portal. Every rupee of tax math computed by tested code, not by an LLM.

New: plan FY 2026-27 advance tax alongside existing FY 2025-26 filing support.

⏳ Missed filing for income earned April 2025 to March 2026? You can still file by 31 December 2026, unless assessment finishes earlier. Submit and e-verify by then to avoid late verification crossing the cutoff. The late fee is ₹1,000 for income up to ₹5 lakh, otherwise ₹5,000, plus applicable interest. Statutory dates.

Seen in the wild: a reel by @ezsnippet (3.7M followers) walked through this repo: "ab tum bina CA ke bhi Income Tax return bhar sakte ho, ITR-Wala use karke." 1.2M views in a week, and the repo's busiest week so far. Filed with itr-wala? Two lines in this thread help the next filer.

# Review-first (recommended): clone, read it, install the bytes you just read
git clone https://github.com/karanb192/itr-wala.git
cd itr-wala && ./install.sh          # also: codex, gemini, all

# Or scope it to just the folder your tax documents live in
cd ~/tax-2026 && ~/itr-wala/install.sh --here

# Claude Code plugin (name whichever repo you trust)
/plugin marketplace add karanb192/itr-wala
/plugin install itr-wala@itr-wala

# Codex plugin (same repo doubles as a Codex marketplace)
codex plugin marketplace add https://github.com/karanb192/itr-wala
codex plugin add itr-wala@itr-wala

# Or the skills.sh one-liner (fetches the default branch head; pick your agent when prompted)
npx skills add karanb192/itr-wala

Run from a checkout, install.sh never touches the network - it copies the files you just read. See Install from a branch you reviewed for why that matters when the tool handles your salary and bank data.

Historical FY 2025-26 recording (July 2026): the GIF shows the earlier 47-test build. Run the current self-test for the current suite and year selection.

Then open your agent and say "file my ITR". Hand it your Form 16 and AIS. It does the rest - except the three things only you should ever do: pay, submit, e-verify.

Or say "Plan my advance tax for FY 2026-27". It asks for an as-of date, your expected income for the whole year, tax employers and banks will deduct, and receipts for advance tax already paid. Python computes how much to pay next and by when. You approve every estimate. Final documents replace those estimates before preparing a return. The payment target excludes late fees and interest. See the advance-tax workflow.

The agent confirms which financial year and whether you are filing a return or planning advance tax. Each year has its own dates and legal labels; an unknown year is rejected.

For FY 2026-27, final return forms and portal fields must be verified before filing guidance. The bundled AY 2026-27 walkthrough remains for FY 2025-26. See the new-year rules and sources. The government estimator manual also distinguishes these two legal years.

Existing-user calculation correction

Version 1.3.1 corrects more edge cases in both supported years. Recheck outputs with multiple self-occupied loans, a late fee after deductions, a business regime election, house-property losses against capital gains, employer NPS or large medical claims. Slab-income rounding also changes some results by ₹10. The affected-input guide explains the fixes, provisional results and how to check an older return.

Any install before 1.3.0, including plugins 1.2.0 and 1.2.1 or unversioned clone/skills.sh installs, could understate FY 2025-26 new-regime tax. Recheck if you had special-rate gains or winnings, total income above ₹12 lakh, and a rebate or marginal relief in the old output. This includes slab income above ₹12 lakh in the marginal-relief band. Old computation JSON calls the engine 1.2.0. The correction adds ₹62,400 in the illustrated no-surcharge case and more when surcharge applies, before any resulting interest. Update using the instructions for your install route, then recompute and compare with your filed return and any processing intimation. See the affected-input examples and next steps. A model-independent engine can still contain bugs; the tests do not replace review.

Why this exists

Every AI-tax demo you saw this season had the same silent flaw: the model was doing the arithmetic. LLMs are magnificent at reading a Form 16 and terrible at applying s.87A marginal relief. One transposed digit and your "free filing" costs you a tax notice.

itr-wala splits the work the way it should be split:

The math is defended in three layers, all shipped in the repo and run in CI on every commit:

1. 102 tax tests covering hand-derived rupee expectations and output guards: rebates on total income including special gains, marginal relief, both-year rate goldens, surcharge and loss set-off, challan dates, expected credits, senior exemption and mixed presumptive income.
2. 133 validator tests reject malformed, mistyped, PAN-bearing or wrong-year inputs, forecasts mixed into returns, and future payments counted as already paid.
3. A property-based fuzzer (scripts/fuzz_engine.py) checks determinism, rounding, cess, component totals, comparisons, income monotonicity and payment targets. CI runs 3,000 cases for each year/purpose combination, 12,000 per Python version. The 1.3.0 engine passed a 360,000-case sweep (90,000 per combination, seed 42). The earlier FY 2025-26 release also underwent its 350,000+ case sweep.

The skill runs the golden suite in front of you before touching your return:

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

The suite must finish with OK before the workflow continues.

(Installed as a plugin and can't find the path? Just ask the agent to "run the itr-wala self-test".)

If your CA can show you their test suite, hire them.

These layers exist because they catch real bugs. Hand-deriving every scenario caught an early build that denied surcharge marginal relief on capital-gains-heavy incomes, and the fuzzer caught a one-in-350,000 floating-point rounding edge where ₹52,880 more salary computed ₹10 less tax. Both are fixed and pinned as regression tests. That find-fix-pin loop is the thing a prompt-only tax tool cannot run.

What a session looks like

1. Year and purpose, then self-test - confirm which income year and whether this is a return or an advance-tax estimate.
2. Documents - drop Form 16 + AIS (JSON) into a folder; it tells you exactly where to download each one.
3. Extract & validate - every number transcribed verbatim into income.json, then a strict validator cross-checks totals against your documents. Unknown key? Rejected. TDS doesn't match 26AS? Flagged.
4. Deduction hunt - a proactive interview (80C, 80D, NPS, HRA, home loan…), because the portal will never ask you.
5. Both regimes, computed - a comparison table with the exact rupee savings. The regime gap is routinely five figures; this table is where it shows up.
6. Filing pack - every portal field mapped to its value, in order, plus the final payable/refund figure the portal must match to the rupee.
7. The portal, together - it narrates each schedule; you type. It never sees your password or OTP. You alone click Pay, Submit, and e-Verify.

The artifact you actually share

Real output, reproducible from the bundled (fictional) example - python3 skills/itr-wala/scripts/tax_engine.py skills/itr-wala/assets/example-income.json:

Income-tax computation for FY 2025-26 (AY 2026-27)
Income-tax Act, 1961
================================================================

[NEW REGIME]
  Gross total income                                    26,06,700
  Deductions                                             1,00,000
  Total income                                          25,06,700
  Tax on slab income                                     2,75,425
  s.111A STCG (equity)                                      9,000
  s.112A LTCG (equity)                                      4,375
  C