ITR Filing Assistant — VS Code / GitHub Copilot Extension

File your Indian Income Tax Return with confidence. This extension turns GitHub Copilot into an expert tax filing assistant that guides you through every step — from document collection to e-verification.

What This Is

A project template + skill pack for GitHub Copilot that automates the ITR filing workflow. Give the agent your documents, and it:

1. Extracts and analyzes all your financial data
2. Computes your tax under both regimes
3. Creates a detailed filing plan with every field mapped
4. Guides you page-by-page through the actual ITR portal
5. Validates everything before you submit

No personal data leaves your machine. Everything runs locally in VS Code.

Quick Start (5 Minutes)

Prerequisites

• VS Code with GitHub Copilot extension
• Python 3.10+ with pymupdf4llm installed:

  pip install pymupdf4llm
  

• Your tax documents (Form 16, bank statements, broker statements, etc.)

Setup

1. Create a new folder for your ITR filing:

   mkdir My-ITR-Filing
   cd My-ITR-Filing
   

2. Copy the extension files into your project:

   • Copy .github/extensions/itr-filing-assistant/.github/ → My-ITR-Filing/.github/
   • Copy .github/extensions/itr-filing-assistant/templates/ → My-ITR-Filing/ (renamed as needed)

   Or simply clone this repository and delete the chapters/, documents/raw/, etc. (personal files).

3. Open in VS Code:

   code My-ITR-Filing
   

4. Start chatting with Copilot:

   "I need to file my ITR for FY 2025-26"

   The agent will ask for your personal info and documents, then guide you through everything.

What the Agent Does

Phase 1: Collect & Extract

• Asks for PAN, DOB, Aadhaar, bank accounts, regime preference
• Extracts all your PDFs using pymupdf4llm
• Parses AIS JSON, Form 26AS, broker statements
• Cross-references AIS against your documents
• Flags any missing documents

Phase 2: Compute & Plan

• Computes income under all heads
• Applies correct slab rates for your regime
• Computes DTAA relief if you have foreign income
• Creates a detailed filing plan with every field value

Phase 3: Portal Walkthrough (Site-Map Method)

• You navigate the ITR portal page-by-page
• You paste what you see into a site-map/ file
• The agent fills in every field with the correct value
• You enter it on the portal and move to the next page
• 16 pages, in order, nothing missed

Phase 4: Validate & Submit

• Pre-submission checklist (15 items)
• Final preview PDF validation (agent reads the entire preview)
• Payment via Challan 280 (only at the end)
• E-verification reminder

Skills Included

These work alongside the built-in tax-verify, itr-portal-ui, tax-graphs, and pdf skills.

Key Features (Learned from Real Filings)

Portal Quirks We Handle

• Schedule OS dividend sub-field mapping (1a(i) = ALL regular dividends)
• Schedule CG quarterly breakup — negative values workaround
• Schedule FA CSV formatting (no commas, YYYY-MM-DD, plain integers)
• "Nature of Employment", "Description of Perquisite", "Profit in Lieu" dropdown requirements
• Form 67 must be filed BEFORE ITR-2 for DTAA relief

Validation Error Handling

• Portal errors appear as non-copyable popups
• Agent directs you to https://www.onlineocr.net/ to OCR screenshots
• Common fixes pre-documented

Data Quality

• Uses raw document extraction, never trusts summaries
• Cross-references AIS entries against user-provided documents
• Independent tax computation — verifies portal auto-computed values

Folder Structure (Created by Agent)

My-ITR-Filing/
├── documents/
│   ├── extractedinfo/     # Cleaned summaries (agent-created)
│   ├── raw/               # Your original files
│   ├── rawmd/             # PDF extraction output
│   └── tax-facts.md       # Current tax rules
├── FilingPlans/
│   └── FILING_PLAN.md     # Your filing plan
├── site-map/              # Portal walkthrough files
├── scripts/
│   └── compute_tax.py     # Tax computation
└── .github/
    └── copilot-instructions.md

Privacy

• All processing happens locally on your machine
• No data is sent to any external server except:
  • GitHub Copilot API (for AI assistance — governed by GitHub's privacy policy)
  • ITR portal (when you file — that's the government)
• Your PAN, Aadhaar, bank details, and income data stay in your project folder
• Delete the project folder after filing if you want

Updating for New Financial Years

1. Update documents/tax-facts.md with the latest Budget provisions
2. Update slab rates, exemption limits, and deduction amounts in the orchestrator skill
3. The site-map structure is stable — ITR portal doesn't change dramatically year-to-year

Contributing

Found a new portal quirk? Discovered a better workaround? File an issue or PR. The goal is to make Indian tax filing less painful for everyone.

💛 Support This Project

If this extension saved you time, stress, or CA fees, consider supporting its development:

Never pay for tax filing help you can't afford. This extension will always be free and open source.

License

MIT — Use freely, share widely, help others file their taxes.

Built from the hard-earned lessons of a real ITR-2 filing (FY 2025-26). May your filing be smoother than ours.