super-tax-agent

---

🌍 Why this project · 为什么做这个项目

"征税没有征到最应该被征税的人身上，而是征到最容易被征税的人身上。"

Taxes don't fall on those who should pay them most — they fall on those who are easiest to tax: wage earners, immigrants, working families. Meanwhile, commercial tax software costs $100–$300 a year, even for a simple W2 filing.

This project is built on a simple belief: AI should serve the many, not the few. With a capable model and a well-designed agent, preparing a straightforward return shouldn't require an expensive annual subscription. Your data should stay on your laptop. The rules should be open. And if the agent gets something wrong, the whole community should be able to fix it — permanently, for everyone.

这个项目的初衷，是基于 "AI 造福最广大人民" 的思想：让普通工薪家庭、留学生、新移民、小业主，都能免费、私密、体面地完成自己的报税准备工作，不必再被昂贵的年费软件反复收割。你的数据留在自己电脑上，规则全部开源，社区一起让它越来越准。

---

📦 Installation · 安装

Install from the Claude Code plugin marketplace:

/plugin marketplace add Fangyi-Chen/tax-marketplace
/plugin install super-tax-agent@tax-marketplace

Or install directly from GitHub:

/plugin install https://github.com/Fangyi-Chen/SuperTaxAgent.git

Requires Claude Code. Works on macOS, Linux, and Windows.

---

🚀 Quick Start · 快速上手

The easiest way — just ask Claude in plain language:

help me do tax 2025
帮我报 2025 年的税

Claude will walk you through the interview, ask for your documents, and handle the rest.

Prefer explicit commands? Use the pipeline directly:

/tax-start            # begin the interactive interview
/tax-import w2.pdf    # import a W2 / 1099 / brokerage PDF
/tax-calculate        # compute refund or amount owed
/tax-fill             # produce a mail-ready IRS 1040 PDF

---

🧠 Skills

Core pipeline · 核心流程

Command	Description
/tax-start [year]	Interactive interview — personal info, dependents, income, deductions, credits. Saves to data/tax-profile.json.
/tax-import <file>	Parse W2, 1099-B, 1099-DIV, 1099-INT, 1099-DA, 1099-MISC from PDF or image. Auto-detects type.
/tax-calculate	Compute income, AGI, deductions, brackets, credits (CTC, EIC), refund or amount owed. Maps to Form 1040 line numbers.
/tax-fill	Fill the official IRS fillable Form 1040 PDF. Outputs a print-and-mail-ready PDF.

Domain knowledge · 领域规则

Automatically invoked by the core pipeline when relevant income types appear.

Skill	Triggers when...	What it knows
tax-domain-rsu	W2 box 14 has RSU codes, or 1099-B has ESPP lots	RSU vesting, cost basis = FMV at vest, ISO/NSO, ESPP qualifying dispositions
tax-domain-rental	User reports rental income	Schedule E, MACRS 27.5-yr depreciation, $25K passive loss allowance
tax-domain-harvest	1099-B has wash sale adjustments	30-day wash sale rule, adjusted basis, $3,000 net loss limit, carryforward
tax-domain-crypto	1099-DA detected	Form 8949, FIFO / specific-ID cost basis, staking, DeFi, stablecoin rules

Self-evolution · 自进化

Help make the agent smarter for everyone by comparing your output against TurboTax.

Command	Description
/tax-compare <our.pdf> <turbotax.pdf>	Diff two returns line by line.
/tax-evolve	Classify discrepancies, generate skill fixes.
/tax-publish [description]	Submit improvements as an anonymized GitHub PR.

---

🔁 How it works · 工作流程

/tax-start ──> /tax-import ──> /tax-calculate ──> /tax-fill
     │              │                │                 │
     │        (detects type)    (applies rules)        │
     ▼              ▼                ▼                 ▼
tax-profile.json  (merges)    tax-calculation.json   1040.pdf
                                                       │
                                              /tax-compare ◄── turbotax.pdf
                                                       │
                                                /tax-evolve
                                                       │
                                                /tax-publish ──> GitHub PR

---

🔒 Privacy · 隐私

All data stays 100% local on your machine. 所有数据 100% 留在你自己电脑上。