Back to search
tip-overtime-w2
SkillGitHub
Live: https://tip-overtime-w2.vercel.app
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/2016judea--tip-overtime-w2)HTML
<a href="/listings/2016judea--tip-overtime-w2"><img src="/api/listings/2016judea--tip-overtime-w2/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 169 lines
- # Tip & Overtime W-2s
- **Live:** https://tip-overtime-w2.vercel.app
- Works out the federal **"no tax on tips"** and **"no tax on overtime"** deductions, and the new 2026
- Form W-2 boxes behind them, in code, with the math shown and a citation for every rule. Two people
- ask the question, so it has two front doors:
- - **The person asking an AI** (since 2026-11-19). A worker says "how much of my tips and overtime can
- I deduct?" to Claude or ChatGPT. The connector at **`https://tip-overtime-w2.vercel.app/mcp`**
- works it out from their W-2 boxes or pay stubs, line by line on Schedule 1-A, and hands back a
- link that opens the filled-in [worksheet](https://tip-overtime-w2.vercel.app/worksheet/) to print
- or give to a preparer. A bookkeeper pastes payroll rows and gets each employee's box 12 TP, TT and
- box 14b. Setup: [/ai/](https://tip-overtime-w2.vercel.app/ai/).
- - **The owner on Clover.** A Clover app that reads the register and gives every employee's W-2
- figures. Unchanged; described from "How it works" down.
- And one page of numbers nobody else publishes:
- [what no tax on tips is worth, by tipped occupation](https://tip-overtime-w2.vercel.app/no-tax-on-tips-by-occupation/)
- (BLS OEWS May 2025 pay for all 71 IRS tipped occupations, run through the 2026 tax tables: a median
- waiter saves $120 per $1,000 of tips and at most $2,048 a year).
- **It calculates and shows. Nobody here files anything, and the connector stores nothing it is sent.**
- ## The connector (MCP)
- Streamable HTTP, stateless, no auth: `site/api/mcp.js`, rewritten from `/mcp`.
- | Tool | For | Computes with |
- |---|---|---|
- | `tip_overtime_deduction` | a worker: W-2 box 12 TP/TT/14b, Form 4137, 1099s, or pay stubs → both deductions, every Schedule 1-A line, the Form 1040 line, federal tax saved, flags, citations, worksheet link | `site/api/_deduction.js` |
- | `w2_tip_overtime_boxes` | an owner or bookkeeper: one row per employee per workweek → TP, TT, 14b per employee, each overtime week's regular rate, printable sheet link | `site/api/_payroll.js` → the Clover engine `site/api/_engine.js` |
- | `tipped_occupation_code` | "does my job qualify?": the TTOC for a job title, its IRS description, BLS median pay, what the deduction is worth there | `site/api/_occupations.json` |
- A model is never the source of a number: the assistant passes figures in and carries the answer out.
- **Privacy, by design.** The worksheet link carries the figures in the URL **fragment**
- (`/worksheet/?src=mcp#w1.<base64 JSON>`). Browsers never send a fragment to a server, so the figures
- never reach Vercel's logs. The page's first script copies the fragment into memory and deletes it
- from the address bar *before* PostHog or Vercel Analytics load, so they see only `/worksheet/?src=mcp`.
- A short-lived server token was the alternative and was rejected: it means storing the figures.
- Employer labels are dropped from the link; nothing is written to storage.
- **Analytics.** Each call sends one PostHog `mcp_tool_call` event: `tool`, `ok`, `ms`, `client`,
- `client_ua`, and coarse booleans (`has_tips`, `has_ot`, `source` w2/estimate, `year`, `blocked`;
- `employees` count for the owner tool). Never an amount, a name or an argument, and no IP: claude.ai
- connector calls arrive from Anthropic's servers, so an IP-based id counts servers, not people
- (`distinct_id` is a fresh random id per call). **People are counted on the web side**: PostHog
- pageviews whose `$current_url` contains `src=mcp`, plus `worksheet_opened` (`prefilled`
- worker/owner/none, `src`), `worksheet_computed`, `worksheet_printed`, `worth_tried`,
- `connector_url_copied`. Mark a test call with header `x-tow-test: 1`.
- ## The rules, verified 2026-11-19 from primary sources
- Copies of every source are in `regs/` and `tests/sources.test.js` checks that each rule the code
- quotes is verbatim in its copy.
- | Rule | Source |
- |---|---|
- | Tips: up to $25,000 per return, any filing status | 26 U.S.C. § 224(b)(1); 26 CFR 1.224-1(b)(1) (T.D. 10044, 91 FR 19026, Apr. 13 2026) |
- | Overtime: up to $12,500, $25,000 joint | § 225(b)(1) |
- | Each falls $100 per full $1,000 of MAGI over $150,000 ($300,000 joint); thousands round DOWN | § 224(b)(2), § 225(b)(2); Schedule 1-A 2026 draft lines 13, 25 (2025: lines 11, 19) |
- | Married filing separately: nothing. SSN valid for work required | § 224(e)-(f), § 225(d)-(e) |
- | Tax years 2025-2028 | § 224(h), § 225(g) |
- | Qualified tips: voluntary, in an occupation on the IRS list (71 codes); service charges and automatic gratuities never count | § 224(d); 1.224-1(c)(4); irs.gov/tippedoccupations |
- | SSTB exclusion not enforced for listed occupations until final SSTB regs (reserved in 1.224-1(g)) | Notice 2025-69 |
- | Qualified overtime: only the FLSA half (hours over 40 × 0.5 × regular rate) | § 225(c)(1); 2026 W-2 instructions, code TT |
- | Pay-stub estimates: total at 1.5x ÷ 3, at 2x ÷ 4; stated premium ×1 or ÷2 | Notice 2025-69 methods A-D (Examples 1-4 are unit tests) |
- | 2026 lines: tips per employer on line 4 (larger of box 12 TP and Form 4137 line 1 col c), deduction line 15; overtime line 16 (box 12 TT), deduction line 27; total to Form 1040 line 13a | Schedule 1-A and Form 1040 2026 **drafts** (6/16/26, 8/19/26): line numbers can still move |
- | 2026 rates and standard deduction ($16,100 single) for the tax-saved estimate | Rev. Proc. 2025-32 |
- ## How the Clover app works
- 1. A merchant installs from the Clover App Market (or opens it from their dashboard). Clover sends
- them to `/clover` (`site/api/clover/launch.js`), which starts OAuth v2. `/clover/callback`
- exchanges the code, seals the token pair (AES-256-GCM) into Cloudflare D1, and sets a 12-hour
- signed session cookie.
- 2. `/report/` calls `/api/data`. That reads the year from Clover in 85-day windows (the API caps a
- time filter at 90 days): employees, shifts, and payments with `expand=tender,order,employee,refunds,serviceCharge`.
- Refresh tokens are single-use and are rotated and saved before use. `site/api/_clover.js` maps the
- rows to the engine's input.
- 3. **The engine** (`site/api/_engine.js`) is pure, deterministic JavaScript with no model and no
- network. The browser runs the same file, so every answer the owner gives recomputes instantly.
- Answers save to D1 (`/api/answers`).
- 4. Anything Clover can't tell us is asked, with a visible default, and flagged until confirmed: pay
- rates, exempt status, workweek start, tip credit, tip sharing done off the register, bonuses,
- whether service charges go to staff, and occupation codes. `DATA_MODEL.md` has the field-by-field
- check.
- 5. Download CSV: the W-2 figures, every workweek, every tip row.
- ## The Clover engine's rules, and where they come from
- Cited in code where applied (`site/api/_engine.js` header):
- - IRS, [2026 General Instructions for Forms W-2 and W-3](https://www.irs.gov/instructions/iw2w3): codes TP and TT, Box 14b (up to two codes; "000" if any tips came from a nonqualifying occupation).
- - IRS [FS-2026-13](https://www.irs.gov/pub/taxpros/fs-2026-13.pdf), Q10–Q17: per-workweek formula, fixed recurring workweek with no averaging, regular rate = all remuneration ÷ FLSA hours, only the FLSA half counts (Q16 worked example is a unit test).
- - IRS [tipped occupations list](https://www.irs.gov/tippedoccupations), transcribed to `site/api/_ttoc.js`.
- - DOL Fact Sheets [#15](https://www.dol.gov/agencies/whd/fact-sheets/15-tipped-employees-flsa) (tip credit: OT on the full minimum wage; service charges are not tips but are wages in the regular rate), [#23](https://www.dol.gov/agencies/whd/fact-sheets/23-flsa-overtime-pay), [#56A](https://www.dol.gov/agencies/whd/fact-sheets/56a-regular-rate).
- One judgment call: workweeks hold the owner's **local** start (Sunday 00:00 stays Sunday 00:00 all
- year), so the two weeks with a DST change run 167 and 169 hours. Stepping a strict 168 hours put
- summer boundaries at 01:00 and moved a Saturday-night hour into the wrong week in the sandbox run.
- ## Tests
- npm test # 61: engine (18), deduction (15), sources verbatim (22), MCP (6)
- python3 scripts/fetch_oews.py # BLS OEWS May 2025 pay for every related SOC (needs BLS_API_KEY)
- node scripts/build_pages.js # → _occupations.json, the by-occupation page, llms(-full).txt, sitemap
- python3 scripts/indexnow.py # ping Bing/IndexNow with every sitemap URL after a deploy
- node scripts/check_sandbox.js # live pull from the sandbox merchant vs. hand-worked figures (3/3)
- ## Clover
- Tool skill: `~/.claude/skills/clover-api/SKILL.md`. Developer account and sandbox test merchant
- `4ZNNY5AK5SNT1` are shared with Block Brief.
- - **Sandbox app** `VRS0YGB8BCFY2` (NA sandbox, Private + Web). Read: Employees, Merchant, Orders,
- Payments. Site URL `https://tip-overtime-w2.vercel.app/clover`, launch path `/clover`, OAuth Code.
- Secret in `.env` and Vercel (`CLOVER_APP_ID`, `CLOVER_APP_SECRET`, `CLOVER_ENV=sandbox`).
- - **Proved end to end on 2026-11-02:** install from the sandbox App Market → Open the app → `/clover`
- → OAuth → `/clover/callback` → `/report/` showing 28 shifts and 7 payments. Then pay rates were
- entered in the page. TP $353.00, TT $205.50, and every employee's figures match the hand-worked
- ones. Answers persisted across a reload. The final install held READ permissions only. Seeding
- (`scripts/seed_sandbox.js`) briefly needed WRITE, which was removed and the app reinstalled.
- - **Production:** the developer account is verifying (Aidan's ID documents, ~11/14). Listing copy,
- permission reasons, icon, cover, screenshots and the walkthrough video are in `listing/`.
- ## Running it
- set -a; . ~/Desktop/workspace/bricks/.env; set +a # VERCEL_TOKEN
- node scripts/make_sample.js # rebuild the SAMPLE café
- python3 scripts/deploy.py # Vercel over REST (copies the engine to public/js first)
- python3 scripts/vercel_env.py KEY… # push .env keys to Vercel
- `.env` (gitignored): `ACCESS_SECRET`, `CLOUDFLARE_API_TOKEN`, `CLOVER_ENV`, `CLOVER_APP_ID`,
- `CLOVER_APP_SECRET` (later `CLOVER_PROD_APP_ID`, `CLOVER_PROD_APP_SECRET`). D1 database
- `tip-overtime-w2` (`2bfd0140-…`), Vercel project `prj_z2TmV6xcMppgVzpzIPamqulmcWn3`, Web Analytics on.
- ## Price
- Draft: one tier, **$29/month**, billed by Clover. Not set live. An owner installs in December,
- runs it in January, and can uninstall after W-2s go out, so the season costs about $58. That is
- less than an hour of an accountant rebuilding the same figures by hand, and the same price as
- Block Brief on the same marketplace.
- ## Expectation (written 2026-11-19, before the connector was listed anywhere)
- The read is **2027-02-26**, four weeks after W-2s are due (Jan 31) and seven before filing ends
- (Apr 15). Second read 2027-04-16.
- - **Base rates.** heistclips' connector sent 151 people to its site via `src=mcp` links in
- 11/16-11/19 (54% used it), where people already ask an AI the exact question. The Brick & Mortar
- business connector, same channel, got zero human calls in 7 days. Directory review for both
- Claude and ChatGPT has taken weeks; until a listing is live, the only way in is the custom URL
- or the data page being cited.
- - **Expected:** 40 people landing on `/worksheet/?src=mcp` by 2027-02-26, and 30 more arriving at
- the by-occupation page from search or AI citations. Most of it depends on a directory listing
- being live by mid-January.
- - **Would surprise us upward:** more than 300 `src=mcp` people by the read date. That would mean
- the filing-season question pulls through the directories the way the clipping question did.
- - **Would surprise us downward:** zero `src=mcp` people with a directory listing live for 30 days.
- That would mean assistants answer this from their own knowledge and never call a tool (the
- business-connector pattern), and the page is the only channel.
- - **Count with:** PostHog, `$host` tip-overtime-w2.vercel.app, pageviews where `$current_url`
- contains `src=mcp`, unique persons; `mcp_tool_call` counts calls, not people.
- ## Licence
- MIT.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.