Indian income tax return with Claude Code: itr-wala lets the agent read Form 16 and AIS while tested Python computes every rupee

In two sentences

Karan Bansal, Head of AI at the application-security company ArmorCode, published itr-wala, a free skill for Claude Code, Codex and Gemini CLI that prepares an Indian income tax return (ITR): the AI agent reads Form 16 and the Annual Information Statement, interviews the taxpayer about deductions and guides them through the portal, while a tested Python engine computes every rupee. It is a first-hand account (the author says he files his own taxes with it) with no independent filer reports yet, but the whole method is in an MIT-licensed repository that anyone can read, test and adapt.

Who does it and why it matters

India’s individual taxpayers file their ITR on the government’s e-filing portal. Most salaried people start from Form 16 (the employer’s certificate of salary and tax withheld), then cross-check the Annual Information Statement (AIS) and Form 26AS, which show what banks, brokers and employers have reported. The README frames the alternative bluntly: a chartered accountant’s fee of around ₹3,000 or about three hours on the portal. Those are the author’s figures, not ours.

The interesting part is the thesis. In the README’s “Why this exists” section, Bansal argues that the AI tax demos of the season shared a silent flaw: the model was doing the arithmetic. Language models read a Form 16 well and apply rebate and marginal-relief rules badly, and one transposed digit becomes a tax notice. itr-wala therefore splits the work: the AI reads, interviews and explains; deterministic Python computes slabs, rebates, surcharge, cess, interest and late fees, validates inputs and cross-checks withholding against the official statements.

Bansal’s background explains some of the design choices. His personal site describes ten years in security engineering and his current role leading AI at ArmorCode; the README adds that he has spoken at DEF CON and OWASP. That shows up as a review-first installer, a validator that refuses identity numbers and “blind extraction” scripts that keep payer names and account numbers out of the model’s context. He has no tax product to sell. The only self-interest we found is an optional invitation, after a successful filing and only with explicit consent, to star the repository.

We contrasted the repository with the author’s Show HN post on Hacker News, the project landing page and his personal site, and we ran the bundled tests ourselves. What we could not find is independent confirmation: the issue the author opened in August asking filers to share two lines about their experience had no replies on 21 October 2026.

Tools and architecture

The repository is a skill in the format used by Anthropic’s skills conventions: one SKILL.md with the workflow and “iron rules”, ten reference files the agent reads when needed, and a scripts/ folder. Everything runs on Python 3.9+ with the standard library only.

Layer	Who does it	Files
Reading documents, interviewing, explaining	The AI agent	SKILL.md, references/*.md
Structured extraction of AIS, TIS and 26AS	Python, without exposing identities	decrypt_ais.py, redact_ais.py, parse_26as.py, extract_tis.py
Input contract	Python validator	validate_income.py, references/input-schema.md
All tax arithmetic, both regimes	Python engine	tax_engine.py, tax_years.py
Proof that the arithmetic is right	Tests in CI	test_tax_engine.py, test_validate_income.py, fuzz_engine.py
Pay, submit, e-verify	The person	e-filing portal

Three choices stand out. First, the agent is forbidden from doing arithmetic, even to sanity-check: if it needs a number, it writes the inputs to income.json and runs the engine. Second, the validator is a gate: mismatches between the claimed withholding and Form 26AS are hard errors, unknown keys are rejected because a typo would silently lose a deduction, and any PAN-shaped or Aadhaar-shaped string blocks the file. Third, the person keeps the irreversible steps: the agent never sees the portal password or OTP and never clicks Pay, Submit or e-Verify, even with a browser tool.

How it works, step by step

SKILL.md describes eleven steps (0 to 10). Condensed:

1. Year, purpose and self-test. The agent confirms the financial year (FY 2025-26 for returns, FY 2026-27 for advance-tax planning) and runs the golden test suite; if it does not end in OK, it stops.
2. Workspace. It creates a folder per year and purpose with docs/, work/ and output/, and a .gitignore that keeps tax documents out of any repository.
3. Documents. Form 16 and the AIS in JSON are the minimum; the AIS download is encrypted and a script decrypts it. Form 26AS, TIS, bank certificates and broker statements improve the cross-checks.
4. Extraction. Every figure is copied verbatim into income.json, with its source recorded in work/extraction-notes.md, and document totals go into source_totals.
5. Validation. The validator must exit with 0 errors; warnings are explained to the user one by one.
6. Deduction interview. The agent asks about the usual deductions proactively; only items with proof in hand go into the return.
7. Computation. The engine compares both regimes; the agent pastes the table verbatim and explains it without recomputing.
8. Form and dates. It selects ITR-1, 2, 3 or 4, sets the due and filing dates and reruns the engine, since late-filing interest can change the figures.
9. Reconciliation and filing pack. A field-by-field map of the portal, in order, with the payable or refund figure the portal must match.
10. Portal and post-filing. The person types, compares the portal preview with the pack, pays, submits and e-verifies within 30 days.

Copy and adapt

Everything in this section marked “from the repository” is copied from karanb192/itr-wala at commit 7d10b18, MIT License, Copyright (c) 2026 Karan Bansal (reference material partly adapted from the MIT-licensed file-itr). Anything labelled “Agents Finance template” is ours.

Prerequisites

• A resident individual return within the supported scope (no F&O trading, audit cases, foreign tax credit or non-resident status).
• Python 3.9+ and git; Claude Code, Codex CLI or Gemini CLI.
• Form 16 and the AIS (JSON), ideally also Form 26AS and TIS.
• Accepting that the documents the agent reads are sent to the model provider; redact PAN, Aadhaar and account numbers first.

Install, review-first (from the repository README)

# 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

To pin the exact commit you reviewed on another machine, the README documents ITR_WALA_REF=<sha> ./install.sh all and ITR_WALA_NO_FETCH=1 to forbid network access.

The iron rules (excerpt of SKILL.md, from the repository)

1. **Never do tax arithmetic yourself.** Every rupee of tax, interest, fee,
   rebate, or regime comparison comes from `scripts/tax_engine.py` output.
   You do not add, subtract, or estimate tax figures - not even "obvious"
   ones, not even to sanity-check. If you need a number, put the inputs in
   `income.json` and run the engine. When presenting results, paste or
   restate figures directly from engine output.
2. **Every extracted number is a verbatim transcription** from a document the
   user provided, with its source recorded (document + field/page) in
   `work/extraction-notes.md`. Fill `source_totals` so the validator can
   cross-check. Never write a model-derived or guessed number into `income.json`.
3. **`scripts/validate_income.py` must pass (exit 0)** before the engine runs.
   Fix every error; show every warning to the user.
4. **Credentials are untouchable.** Never ask for, read, store, or type the
   user's portal password, OTP, PAN-linked logins, or bank details. If a
   browser is involved, the user logs in themselves.
5. **The user performs the three final acts: Pay, Submit, e-Verify.** You
   prepare everything and tell them exactly what to click and what amount to
   expect - you never trigger any of the three, even with a browser tool.

The full file also covers the lowest-legal-tax rule, the income-year guard, the scope guard and the privacy rule (rules 6 to 9).

The workspace .gitignore (patterns listed in SKILL.md, from the repository)

docs/
work/
output/
*AIS*
*TIS*
*26AS*
*Form16*
*form16*
*ITR*json
*ACK*
*Challan*

The input contract: fictional example (assets/example-income.json, from the repository)

{
  "financial_year": "2025-26",
  "purpose": "return",
  "name": "Example Filer (fictional)",
  "regime": "both",
  "age_category": "regular",
  "residential_status": "resident",
  "due_date": "2026-07-31",
  "filing_date": "2026-07-28",
  "income": {
    "salary": {
      "gross": 2400000,
      "exempt_allowances": 240000,
      "professional_tax": 2400,
      "basic_plus_da": 1200000,
      "form16_17_1": 2300000,
      "form16_17_2": 100000,
      "form16_17_3": 0
    },
    "house_property": [
      { "type": "self_occupied", "interest_paid": 180000 }
    ],
    "capital_gains": {
      "stcg_111a": 45000,
      "ltcg_112a": 160000,
      "stcg_slab": 12000
    },
    "other_sources": {
      "savings_interest": 14500,
      "fd_interest": 42000,
      "dividends": 8200
    }
  },
  "deductions": {
    "80c": 150000,
    "80ccd_1b": 50000,
    "80ccd_2": 100000,
    "80d": 25000
  },
  "taxes_paid": {
    "tds": 280000,
    "advance_tax": [
      { "date": "2025-12-14", "amount": 20000 }
    ]
  },
  "source_totals": {
    "form16_gross_salary": 2400000,
    "form16_total_tds": 265000,
    "form26as_total_tds": 280000,
    "ais_total_tds": 280000,
    "ais_savings_interest": 14500,
    "ais_dividends": 8200
  }
}

The identity guard in the validator (excerpt of validate_income.py, from the repository)

PAN_RE = re.compile(r"\b[A-Z]{5}[0-9]{4}[A-Z]\b")
AADHAAR_RE = re.compile(r"\b\d{12}\b")

Example: what we got when we ran it

We ran the three commands from the README against the fictional example, on Python 3.13, at commit 7d10b18:

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

Ran 88 tests in 0.027s

OK
WARNING TDS claimed (280,000) differs from form16_total_tds (265,000) by 15,000 - reconcile before filing (multiple deductors?)

OK - 0 error(s), 1 warning(s)
...
  RECOMMENDED: NEW regime (saves Rs. 42,811)
  New: 3,00,716   Old: 3,43,527

The warning is the useful part: the example deliberately claims ₹15,000 more withholding than Form 16 shows (a bank also deducted tax), and the validator asks for the explanation instead of letting it pass silently. The ₹42,811 matches the README.

Agents Finance template based on itr-wala: an AGENTS.md for the same pattern in another country

This is our own adaptation of the pattern, not code published by the author. It assumes you write (or already have) a tested calculation script for your jurisdiction.

# AGENTS.md — personal tax return, deterministic engine pattern
# Agents Finance template based on itr-wala (MIT). Untested proposal.

## Roles
- You read documents, ask questions and explain. You never calculate tax.
- `engine/compute.py` calculates. `engine/validate.py` checks inputs.
- The taxpayer logs in, pays, submits and signs. You never do any of these.

## Rules
1. No arithmetic in chat. Every amount you show comes from engine output,
   pasted verbatim. If you need a number, add inputs and rerun the engine.
2. Every input figure is copied verbatim from a document in `docs/`, with
   its source (document, page, box) written to `work/sources.md`.
3. `python3 engine/validate.py work/input.json` must exit 0 before
   `engine/compute.py` runs. Show every warning to the taxpayer.
4. Fill `source_totals` with document totals (withholding, interest,
   dividends) exactly as printed; never adjust them.
5. Never ask for or store passwords, one-time codes, tax ID numbers or
   bank account numbers. Ask the taxpayer to redact them first.
6. Out of scope (non-residents, business audits, foreign tax credits,
   anything the engine does not model): say so and recommend an adviser.

## Workflow
0. Confirm tax year and purpose. Run `python3 -m unittest engine.tests`.
   Stop if it does not end in OK.
1. Create docs/, work/, output/ and a .gitignore that blocks all three.
2. Extract to work/input.json. 3. Validate. 4. Ask about deductions.
5. Compute and paste the comparison table. 6. Write output/filing-pack.md
   with every form field in order and the final amount the tax portal
   must show. 7. The taxpayer compares, files and signs.

Agents Finance template: kick-off prompt

Use the itr-wala skill. I am a resident individual filing for FY 2025-26.
My documents are in ./docs (Form 16 and the decrypted AIS JSON; I have
redacted PAN, Aadhaar and account numbers). Before reading anything, run the
self-test and show me the result. Then follow SKILL.md step by step, update
work/progress.md after each step, and stop after the filing pack: I will
enter the values in the portal and pay, submit and e-verify myself.

Results stated by the author

The README claims the tool replaces a fee of around ₹3,000 and about three hours on the portal, and says the author files his own taxes with it. It reports 88 hand-derived tax tests, 131 validator tests and a property-based fuzzer that runs 3,000 cases per year and purpose in CI, plus a 360,000-case sweep that passed on the revised engine. It also describes two bugs caught by that process: an early build that denied surcharge marginal relief on incomes heavy in capital gains, and a rounding edge case where ₹52,880 more salary computed ₹10 less tax. It cites an Instagram reel that, according to the README, reached 1.2 million views in a week. We could not find a single independent filer report: the feedback thread had no replies on 21 October 2026.

Limitations and risks

• A tested engine can still be wrong. The project disclosed itself that installs before 1.3.0 could understate new-regime tax when special-rate income was present; in its own example the difference is ₹62,400. Anyone who filed with an old version needs to recompute.
• Transcription is the residual risk. The model reads the documents, so a misread digit is possible; cross-checks against Form 26AS and the AIS catch many, but not all, errors.
• Privacy. The Python runs locally, but the documents the agent reads go to the model provider. The redaction and blind-extraction scripts reduce what the model sees; they do not remove that tradeoff.
• Narrow scope. Resident individuals only; F&O and intraday trading, audit cases, foreign tax credit, ESOP deferral and several capital-gains edge cases are excluded, and FY 2026-27 return forms still need official verification.
• Responsibility stays with the filer. It is not a chartered accountant and not tax advice; the README itself suggests handing the filing pack to a CA for a cheap review.

Common mistakes

• Letting the agent “just check” a total in chat. The rule exists because that is where errors creep in.
• Using a stale AIS: it fills in over the season, and the skill asks for a fresh download.
• Treating validator warnings as noise. A TDS mismatch usually means a second deductor or a missing document.
• Installing with a one-liner from the default branch instead of a reviewed, pinned commit, for a tool that reads salary and bank data.
• Mixing years or purposes in one folder; the skill expects one workspace per financial year and purpose.

Conclusions

itr-wala is a clear example of the pattern that keeps recurring in this directory, from household returns to month-end close: let the model read, ask and explain, and give every number to code that is tested and can be audited. What makes it practical is that the contract is written down — iron rules in SKILL.md, a strict schema, a validator that fails closed and a test suite you can run before trusting it. The evidence is still a builder’s own account, so treat the time and cost savings as claims; the architecture, however, is reusable in any country where you can write the calculation as code.