Tax-loss harvesting is one of those ideas that looks made for automation: scan your holdings, find positions trading below your cost basis, sell them to realize a loss that offsets your taxable gains, and reinvest. A developer sees that and thinks "that's a cron job." The logic genuinely is simple. What's not simple is the tax law wrapped around it — and getting that wrong turns a tax saving into a disallowed loss and a mess at filing time. This is an overview of the mechanics and the landmines. None of this is investment or tax advice.
What tax-loss harvesting actually does
The mechanic is straightforward. When you sell an investment for less than you paid, you realize a capital loss. That loss can offset capital gains elsewhere in your portfolio, and within limits it can offset a portion of ordinary income, reducing your tax bill for the year. Crucially, selling at a loss doesn't mean abandoning your investment thesis — the point is to capture the tax benefit of the loss while staying invested in the market.
So the naive algorithm is: for each holding, if its current price is below your cost basis by some threshold, sell to harvest the loss, then reinvest the proceeds to maintain your market exposure. Done across a portfolio, this can meaningfully reduce taxes on your gains. The benefit is real, which is why robo-advisors advertise it heavily.
Harvesting a loss lowers your cost basis when you reinvest, which can mean a larger taxable gain later. Much of the benefit is deferring taxes and offsetting gains in high-income years — valuable, but not a permanent elimination of tax. Model it as timing and offsetting, not as found money.
The wash-sale rule: where naive bots break
Here is the rule that ruins simple automation. In the US, the wash-sale rule disallows a loss if you buy a "substantially identical" security within 30 days before or after the sale that generated the loss. Sell a fund at a loss and rebuy the same fund an hour later, and the IRS disallows the loss entirely — you did the work and got none of the tax benefit.
This is exactly what a naive "sell the loser, immediately rebuy to stay invested" bot does. To harvest correctly, you reinvest the proceeds into something that maintains similar market exposure without being substantially identical — and what counts as "substantially identical" is a genuinely fuzzy legal question, not a clean technical one. The 30-day window also spans before and after the sale, and applies across all your accounts, which trips up anyone who automates one account in isolation.
There is no clean API that tells you whether two securities are 'substantially identical' for wash-sale purposes — it's an interpretation of tax law. Automating around the wash-sale rule means encoding assumptions about that interpretation, and getting it wrong means disallowed losses. This is the part to be conservative about, or to hand to a professional.
Why the rules, not the code, are the hard part
If you strip away the tax law, automating tax-loss harvesting is a trivial program. Everything difficult about it lives in the rules: the wash-sale window across all your accounts, the question of substantially-identical replacements, the distinction between short- and long-term losses, the limits on offsetting ordinary income, and the way your specific tax situation changes whether harvesting is even worthwhile in a given year.
That asymmetry is the real lesson for developers. The temptation is to focus on the part you're good at — the code — and treat the tax rules as a detail. It's the reverse: the code is the easy 10%, and the tax rules are the hard 90% where mistakes cost real money. Before automating any of this, make sure you understand the wash-sale rule cold, know how it applies across your accounts, and seriously consider running your approach past a tax professional. The point of harvesting is to save on taxes; a disallowed loss or an audit headache defeats the entire purpose.
Automating tax-loss harvesting is a great example of a problem where the engineering is easy and the domain is hard. Respect the tax rules more than the code, be conservative around the wash-sale rule, and get professional advice for your situation — the savings only count if they survive contact with the tax authority.
Originally published at pickuma.com. Subscribe to the RSS or follow @pickuma.bsky.social for new reviews.
Top comments (0)