tax

Tax Avoidance

Legal tax avoidance only. Not tax evasion. The project uses the phrase "tax avoidance" in the ordinary legal sense of lawful tax minimization, not illegal concealment or fraud. See Tax avoidance and Tax evasion.

Tax Avoidance is a normie-focused tax copilot for the Codex app and Claude Cowork. It is built to help a normal person gather tax documents, answer only the necessary interview questions, and assemble a prefilled federal return package for a simple 2025 U.S. federal individual return without e-filing.

What A Normal Codex App User Needs

The intended user is someone with the standard Codex app experience plus ordinary personal accounts and files:

• the Codex app itself
• Gmail connected if their tax forms arrive by email
• Google Drive connected if they store PDFs or Google Docs there
• the ability to upload PDFs when a connector only exposes metadata or a portal notice

No separate backend or custom API setup is required for the main workflow in this repository.

What It Does

• Uses existing desktop AI UIs instead of building a separate product.
• Optimizes for Codex first, because Codex has a stronger connector and document-ingestion story for Gmail, Google Drive, Dropbox, and related tools. See the OpenAI connectors guide.
• Keeps a Claude Cowork path with the same interview flow, but expects explicit PDF upload when Gmail or Drive integrations cannot expose the actual attachment content. See Claude integrations setup, Use Google Workspace connectors in Claude, and Use plugins in Cowork.
• Produces the same artifact set every time:
  • tax-dossier.md
  • return-data.json
  • federal-lines.md
  • missing-items.md
• Surfaces likely SaaS or tooling receipts as candidate business expenses without silently applying them to Schedule C.
• Totals candidate expenses using the receipt or payment date for the target tax year, while still showing out-of-year receipts in the document inventory for auditability.
• Captures resident-state and work-state context now, even before automated state calculations are implemented.

Scope

This repository targets simple federal individual returns only: single or married-filing-jointly households with wage, contractor, and investment income plus common deductions and credits. It supports a simple Schedule C skeleton for contractor 1099-NEC work when gross receipts are known and business expenses can be gathered. It still excludes rental income, K-1s, stock options, QSBS, trusts, estates, multistate returns, and international filings.

All substantive tax facts should trace back to primary IRS sources such as Publication 17, Publication 505, Publication 590-A, and Publication 969. Wikipedia is only used for the avoidance-vs-evasion terminology framing.

Install In Codex

Codex reads repository-scoped skills from .agents/skills, so this repo is directly usable after cloning:

git clone https://github.com/alok/tax-avoidance-skill.git
cd tax-avoidance-skill

Then invoke the skill explicitly:

$tax-avoidance

Recommended starting prompt:

Use $tax-avoidance to connect Gmail and Google Drive, gather my 2025 tax documents, ask only the missing questions, and assemble a prefilled federal return package.

If the user is a contractor or freelancer, a stronger version is:

Use $tax-avoidance to gather my 2025 W-2s, 1099s, and tax receipts, build a Schedule C skeleton if I have 1099-NEC income, and tell me exactly what is still missing.

Try It Locally Without Connectors

If you want to sanity-check the deterministic layer before using your own data:

uv run python .agents/skills/tax-avoidance/scripts/run_tax_flow.py \
  --input examples/contractor-and-investment-input.json \
  --out-dir output/example-run

That should create the same four standard artifacts in output/example-run/.

Install In Claude Cowork

This repo also ships a Cowork plugin wrapper:

/plugin marketplace add alok/tax-avoidance-skill
/plugin install tax

Primary command:

/tax:prep

Workflow