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.

⏳ AY 2026-27 due dates (ITR-1/2 → 31 July, ITR-3/4 non-audit → 31 August) have passed. You can still file a belated return until 31 December 2026: late fee ₹1,000 if income is up to ₹5 lakh, else ₹5,000 (section 234F), plus interest on any unpaid tax.

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.

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.

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 AI does	Deterministic Python does
Reads your Form 16, AIS, broker P&L	Every slab, rebate, surcharge, cess calculation
Interviews you for missed deductions	Old vs new regime comparison
Explains every number in plain language	87A marginal relief, 111A/112A/VDA special rates
Walks you through the portal	234A/B/C interest, 234F late fee
	Schema validation that rejects typo'd inputs
	Cross-checks your TDS against 26AS/AIS totals

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

1. 51 golden tests - every expected value hand-derived from the statute first: the 87A rebate cliff and its marginal relief, capital-gains exemption ordering, s.71 loss set-off, the surcharge tiers (including the exclusive-income tests for the 25%/37% slabs and the 15% ceiling on capital-gains tax), and 234A/B/C/F interest down to the month-counting and challan-date edge cases.
2. A 104-test suite for the input validator - the gate that rejects malformed, mistyped, or PAN-bearing inputs before they can reach the engine.
3. A property-based fuzzer (scripts/fuzz_engine.py) - generates thousands of randomized, boundary-biased returns and asserts invariants the law implies: more income can never mean less tax in the new regime, cess is exactly 4%, rounding follows s.288A/288B, recommendations match the cheaper legal option. Seeded and deterministic; CI replays 3,000 cases on every commit, and 350,000+ were swept before release.

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

$ python3 skills/itr-wala/scripts/test_tax_engine.py
...................................................
Ran 51 tests in 0.003s
OK

(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. Self-test - the engine proves its math before you trust it.
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 - FY 2025-26 (AY 2026-27)
================================================================
[NEW REGIME]
  Gross total income               26,06,700
  Total incom