karanb192/itr-wala

itr‑wala – File Indian Income‑Tax Returns from the Terminal

What it is – An open‑source command‑line tool that lets you prepare (but not submit) your Indian individual income‑tax return (ITR‑1/2/3/4) entirely on your own computer. The heavy‑lifting math is done by a tested deterministic Python engine, while a language model is only used to read your Form 16, AIS (annual information statement) PDFs and to explain the numbers.

Why it matters – Most “AI tax‑filers” let a large language model do the arithmetic, which is risky because a single transposed digit can trigger a tax notice. itr‑wala separates concerns:

• AI part – extracts numbers from PDFs and answers your questions.
• Python part – computes every slab, rebate, surcharge, marginal‑relief, capital‑gains exemption, interest, late‑fee, etc., exactly as defined in the Finance Act for Assessment Year 2026‑27.

The math is protected by three layers of testing that run on every commit:

1. 47 hand‑derived golden tests covering every statutory edge case.
2. 104 input‑validation tests that reject malformed or mistyped data (including PAN/Aadhaar strings).
3. A property‑based fuzzer that generates thousands of random returns and checks invariants (e.g., more income never yields less tax).

How a typical session works

1. Self‑test – run the bundled test suite to verify the engine.
2. Drop documents – place your Form 16 and AIS JSON files in a folder.
3. Extraction & validation – the AI reads the PDFs, writes an income.json, and the validator cross‑checks totals against the original documents and against 26AS.
4. Deduction interview – the assistant asks about 80C, 80D, NPS, HRA, home‑loan interest, etc.
5. Regime comparison – it computes both the old and the new tax regimes and shows you the rupee‑wise saving.
6. Filing pack – a plain‑text mapping of every portal field to the computed value, plus the final payable/refund amount.
7. You finish – you manually enter the numbers, click Pay, Submit and e‑Verify on the government portal. The tool never handles passwords, OTPs, or clicks any button.

Installation – The repo ships an install.sh script that never contacts the network when run from a local checkout; it simply copies the files you just read into the appropriate skill directory for Claude, Codex, Gemini, or the generic skills.sh CLI. You can install globally (~/.claude/skills/…) or project‑locally (next to your tax folder) and even pin a specific commit or tag to guarantee you run the exact code you reviewed.

Privacy

• All tax‑math runs locally; no data leaves your machine.
• The only part that reaches an LLM is the text you feed it for extraction. The tool forces you to redact PAN, Aadhaar or bank‑account numbers, and the validator will reject any file that still contains those patterns.
• A generated .gitignore keeps your raw documents out of any repository you might commit.

Scope & limits – Handles resident individuals for AY 2026‑27, covering salary, house‑property, capital‑gains (including crypto/VDA), lottery winnings, family pension, presumptive income, all Chapter VI‑A deductions, and both tax regimes. It explicitly refuses to guess for non‑residents, audit cases, foreign tax credit, ESOP deferral, large agricultural income, etc., and will direct you to a chartered accountant in those cases.

Roadmap highlights – Offline utility‑JSON upload, deeper RSU/ESPP support, revised‑return workflow, native Windows installer, and a one‑click Claude desktop bundle.

License – MIT.

---

Use itr‑wala if you want a transparent, test‑backed way to prepare your Indian tax return while keeping the actual computation off‑line. You still need to file and verify yourself, or hand the generated pack to a CA for review.