Multi-State Tax Allocator
Track where employees actually worked, allocate their wages across states, apply reciprocity rules, and export a clean per-state withholding split your payroll system can ingest - with a human approval gate before anything leaves the tool.
Import work-days by state and wages, get a per-employee wage allocation across states with reciprocity rules applied, have payroll review and approve the split, then export a per-state withholding allocation CSV plus a summary.
Before you start
- A free Vercel account
- A free Supabase account
- A free Resend account (for review/approval notifications)
- A spreadsheet or CSV of employee work-days by state and wages per period
The problem this kills
Your team isn't all sitting in one state anymore. People work remote from one state, live in another, and travel to a third for a week here and there. Payroll is supposed to set up withholding for each state based on where the work actually happened - and somehow you're tracking all of this in your head, in email threads, and in a spreadsheet that nobody fully trusts.
When it goes wrong it goes wrong quietly. Someone gets double-taxed because two states both think they're owed withholding and nobody applied the reciprocity agreement between them. Someone else is under-withheld all year and finds out at tax time. You only catch it when an employee complains or a state sends a notice.
The hard part isn't the math - it's keeping an honest record of who worked where, applying the right state rules consistently, and having a real person sign off before the numbers hit your payroll system. That's exactly what this tool does.
What you'll build
A small, private web app for your payroll team that turns "days worked by state" plus "wages per period" into a clean, approved, per-state withholding allocation.
- Import a CSV or Google Sheet of employee work-location days and wages per pay period.
- Automatically allocate each employee's wages across states based on the days they actually worked there.
- Apply the reciprocity and resident-vs-work-state rules for the specific states your company operates in.
- Show payroll a clear per-employee breakdown to review.
- Require a human to approve each employee's split before it can be exported.
- Export a per-state withholding allocation CSV (in the exact columns your payroll system expects) plus a readable summary.
Important and built into the plan: this is a setup aid, not tax advice. The tool makes your allocation consistent, reviewable, and auditable - a qualified person still approves it.
What's inside the Implementation Plan
The plan is a single markdown file you paste into an AI coding agent (Claude Code), which then builds the tool with you step by step.
- It starts by interviewing you about your business. Before writing any code, the plan has the agent ask about your real states, your reciprocity agreements, how you track work-days today, the exact column names in your spreadsheet, your pay-period shape, and your messiest edge cases. It reads a short tailored spec back to you and waits for your thumbs-up. You get a tool shaped around your company - not a generic template.
- A clear definition of done, so you know exactly when you're finished.
- Copy-paste prompts for every build step - you never have to think up what to say to the agent.
- A data model and allocation logic tuned to the states and rules you described in the interview.
- A "No API yet?" fallback so you can build and use this today using just a CSV, with no integration to your payroll system required.
- A verification checklist to confirm the tool actually works before you rely on it.
The governance it includes (this is the point)
This isn't a throwaway script. The plan builds in the controls a payroll function actually needs:
- Login so only your team can open the tool.
- Row-level security so each organization only ever sees its own employees and data.
- A complete audit trail - who imported what, who changed an allocation, who approved it, and when.
- A hard human-in-the-loop approval gate - the tool drafts the per-state split, a payroll reviewer checks it, and only an approved allocation can be exported. Nothing reaches your payroll system unreviewed.
- Duplicate guards so the same employee-and-period can't be imported or processed twice.
Who it's for
Payroll teams at companies with remote, hybrid, or multi-state-traveling employees - anyone responsible for getting state withholding set up correctly for a distributed workforce, who is tired of doing it by hand and wants a consistent, auditable process.
You don't need to be a developer. If you can follow a recipe and paste text into a chat box, you can build this.
You've got this - paste the first prompt and let the agent interview you.