# itr-wala

Claude Code, Codex and Gemini skill that prepares an Indian income tax return with a tested tax engine.

itr-wala is an agent skill: the model reads Form 16, AIS and broker statements, a deterministic Python engine computes both regimes, surcharge, interest and late fees for AY 2026-27, and the agent walks you through the government portal. It never pays, submits or e-verifies. Installs as a skill or plugin with zero dependencies; MIT.

Alternative to: ClearTax

- Capabilities: adaptable, operable
- Vertical: invoicing-finance
- Shape: skill
- Form factor: skill
- Execution model: hybrid
- Provenance: unknown (recorded, never ranked)
- Repo: https://github.com/karanb192/itr-wala (MIT), 846 stars, last commit 2026-09-02
- Last activity: 2026-09-02
- Page: apps/karanb192--itr-wala.html
- JSON: apps/karanb192--itr-wala.json

## Use it when

- I file my own Indian return and want every rupee computed by tested code before I touch the portal
- I am a CA who wants a zero-cost first draft and filing pack from a client's Form 16

## Gotchas

- India only, resident individuals, AY 2026-27 only; refuses other years
- Documents you hand the model leave your machine; redact PAN and Aadhaar first (the validator enforces it)
- Original due dates have passed; belated filing until December 31, 2026 with a late fee

## Editions

- Free: Free, open source
  - source: https://github.com/karanb192/itr-wala
  - installable: npx skills add karanb192/itr-wala

## Adaptable: make it yours

Effort: light-edit (5 things to edit)

Fork, review, and pin: DEFAULT_REPO in install.sh points the installer at your fork, ITR_WALA_REF pins a commit. The behavior you would change is in SKILL.md (interview flow, portal notes) and the rate constants block in scripts/tax_engine.py, each change shipping with a hand-derived test by project rule.

- Env vars: ITR_WALA_REF, ITR_WALA_NO_FETCH, ITR_WALA_REPO
- Config files: install.sh (DEFAULT_REPO)
- Prompt files: skills/itr-wala/SKILL.md
- Accounts you'll need: Claude Code, Codex or Gemini CLI; Income Tax e-filing portal account (you file; the tool does not)

## Operable: what an agent can drive

Operability: native. Interface: cli at https://github.com/karanb192/itr-wala (published by the builder, local).

### Reach (partial coverage)

- Self-test the tax engine: reachable. scripts/test_tax_engine.py, 47 golden tests run at session start
- Extract figures from Form 16, AIS and broker P&L: reachable. the model transcribes into income.json (README session step 3)
- Validate inputs and cross-check TDS against 26AS/AIS: reachable. validate_income.py; rejects PAN-shaped strings
- Hunt for missed deductions: reachable. proactive interview step in SKILL.md flow
- Compute both regimes and recommend: reachable. tax_engine.py output shown in README
- Select the ITR form and build a filing pack: reachable. README: ITR-1/2/3/4 selection, portal field mapping
- Walk through the portal schedules: reachable. README: it narrates each schedule; you type
- Pay, submit and e-verify: not reachable. hard boundary by design: never clicks Pay, Submit or e-Verify
- Non-resident, F&O, audit cases, foreign tax credit: not reachable. README out-of-scope list; it refers you to a CA

## Code stack

- Languages: Python, Shell
- Frameworks: none
- Package manager: none
- Database: none
- Hosting target: local machine (~/.claude/skills, ~/.codex/skills, ~/.gemini/skills)

## Model stack

- Providers: whichever agent runs the skill (Claude Code, Codex, Gemini CLI)
- Models: none
- Keys you need (names only): none
- Prompts live in: skills/itr-wala/SKILL.md
- Tools: scripts/tax_engine.py, scripts/validate_income.py, scripts/test_tax_engine.py

## Skills

pure: Repo is one tax-filing skill packaged as a Claude Code and Codex plugin; scripts/ are helpers the skill invokes.
- Paths: skills/itr-wala/SKILL.md, .claude-plugin/
- Install: npx skills add karanb192/itr-wala

## Evidence and confidence

- formFactor: skills/itr-wala/SKILL.md plus scripts; installs into agent skill directories (confidence 0.95)
- executionModel: model reads documents and interviews; Python does every calculation (README table) (confidence 0.95)
- operability: built as a skill for the agent; the agent is the primary interface (confidence 0.9)
- effort: SKILL.md and tax_engine.py constants are the editable files; env vars only affect install (confidence 0.8)
- editions: LICENSE file is MIT (GitHub shows NOASSERTION) (confidence 0.95)
- active: GitHub pushedAt 2026-09-02; Show HN 2026-07-28; Instagram reel drove 1.2M views
- reach:  (confidence 0.9)

## Open questions

- Whether the constants block is a separate file or inline in tax_engine.py

## Sources

- https://github.com/karanb192/itr-wala (sourcing:invoicing-finance:community)
- https://github.com/karanb192/itr-wala/blob/main/LICENSE (analysis:invoicing-finance)