Build a Stock Portfolio Tracker with Claude Code

What You're Building

A personal stock portfolio tracker — no spreadsheets, no apps, no subscriptions. Tell Claude Code "I bought 10 shares of NVDA" and it updates your portfolio, calculates your P&L, tracks your tax situation, and remembers everything across sessions. All from JSON files on your machine.

Milestone 1: Create Your Portfolio Data

We need a place to store your holdings. A simple JSON file works perfectly.

Prompt:

Create a folder ~/Dev/my-portfolio/ and inside it create a portfolio.json file. Add 5 sample stock holdings with these fields for each: ticker, name, quantity, buy_price, current_price, currency (USD). Use real stocks — AAPL, NVDA, TSLA, META, GOOGL. Make up realistic buy prices that are lower than current prices (I want to see green P&L). Also add a cash_balance field of 5000 and a last_updated timestamp.

Claude Code creates a structured JSON file with your holdings. This is your entire database — no server, no SQL, just a file on your machine. Each stock has everything needed to calculate profit and loss: what you paid vs. what it's worth now.

Try it: Open ~/Dev/my-portfolio/portfolio.json in any editor. You should see 5 stocks with buy prices, current prices, and quantities.

Milestone 2: Build the Skill

You're about to write a markdown file that teaches Claude Code how to be your portfolio manager.

Prompt:

Create a skill file at ~/.claude/skills/stock-portfolio.md. This skill triggers when I say /stock-portfolio or ask about my portfolio. When triggered, it should:
1. Read ~/Dev/my-portfolio/portfolio.json
2. Show a clean table with all holdings: ticker, quantity, current price, cost basis, P&L in $ and %, weight in portfolio
3. Show total portfolio value and total P&L
4. Show top winners and losers
Make sure the instructions tell Claude to always read the JSON file first before responding.

A Claude Code skill is just a set of instructions written in plain language. You're not writing code — you're writing rules like "when the user asks about their portfolio, read this file and show a table." Claude follows these instructions every time the skill triggers.

Try it: Start a new Claude Code session (the skill gets detected on startup). Type /stock-portfolio. You should see a formatted table with all 5 holdings, their P&L, and portfolio totals.

Your portfolio tracker is alive.

Milestone 3: Track Your Trades

A tracker that can't record trades isn't a tracker. Let's add buy/sell commands with a permanent transaction history.

Prompt:

I need two things:
1. Create a transactions.json file in ~/Dev/my-portfolio/ with an empty transactions array and a next_id counter starting at 1.
2. Update the skill file ~/.claude/skills/stock-portfolio.md to handle buy and sell commands:
   - When I say "bought 10 AAPL at $200", add a BUY transaction to transactions.json with date, ticker, quantity, price. Then update portfolio.json — add to existing position or create new one, recalculate average cost basis.
   - When I say "sold 5 NVDA at $250", add a SELL transaction with realized P&L calculated. Update portfolio.json — reduce quantity. If fully sold, move to a closed_positions array.
   - The transaction log is append-only — never delete entries.
   - After any buy/sell, show a confirmation with what changed.

The key design decision here is append-only logging. Every trade gets recorded permanently — buys, sells, dates, prices, realized P&L. You never delete a transaction. This gives you a complete audit trail and makes tax reporting straightforward.

Try it: Say "I bought 10 shares of AMZN at $195." Check that portfolio.json now has 6 positions and transactions.json has its first entry. Then say "I sold 2 GOOGL at $180" — verify the quantity decreased and a SELL transaction was logged with the realized gain or loss.

Milestone 4: Know Your Tax Situation

This is the milestone that pays for itself. Literally.

Prompt:

Update the skill file to add two new commands:
1. "tax" command — reads transactions.json, calculates total realized gains and losses for the current year, shows net P&L, estimates 25% capital gains tax, and identifies tax-loss harvesting opportunities (positions currently at a loss that could be sold to offset gains).
2. "analyze" command — reads portfolio.json and shows: concentration risk (any position over 10%?), top 5 holdings by weight, and overall portfolio health assessment.
The tax command should clearly show: total gains, total losses, net taxable amount, estimated tax, and how much you'd save by harvesting specific losses.

Tax-loss harvesting is the concept that makes this valuable: if you have realized gains of $1,000 and unrealized losses of $800, selling those losers offsets your gains — dropping your taxable amount to $200. Your "garbage" positions become tax shields.

Try it: If you sold GOOGL in the previous step, you already have a realized trade. Run the tax command — you should see your realized gain, estimated 25% tax, and any positions sitting at a loss that you could sell to offset it. If you haven't sold anything yet, sell a position first so the tax report has data to work with.

Milestone 5: Snapshots and Persistence

Last step: give your portfolio memory across time and across sessions.

Prompt:

Two final additions:
1. Create a snapshots/ folder in ~/Dev/my-portfolio/. Update the skill to add a "snapshot" command that saves the current portfolio state as snapshots/YYYY-MM-DD.json (today's date). Add a "compare" command that loads two snapshots and shows what changed — value difference, new/removed positions, P&L change.
2. Add a section to ~/CLAUDE.md (or create it if it doesn't exist) documenting this portfolio project — the folder path, the skill name, what data files exist, and what commands are available. This way Claude Code remembers this project exists in every future session.

Snapshots are your portfolio's memory. Take one today, take another next week, and compare them to see exactly what changed — which positions grew, which shrank, what you added or removed. The CLAUDE.md entry ensures Claude knows about your portfolio in every future conversation, even months from now.

Try it: Run the snapshot command and check ~/Dev/my-portfolio/snapshots/ for today's file. Then the real test: open a brand new Claude Code session and ask "what's in my portfolio?" — Claude should know exactly where to look.

What You Built

A complete portfolio tracking system, running entirely from your terminal:

• Holdings tracker with real-time P&L calculations
• Transaction log that permanently records every buy and sell
• Tax calculator with loss-harvesting recommendations
• Portfolio analysis with concentration risk alerts
• Snapshots for comparing your portfolio over time
• Persistent memory via CLAUDE.md — survives across sessions

No database, no backend, no monthly subscription. Just JSON files and a skill file that teaches Claude Code how to manage them.

Take It Further

• Live prices: Add a prompt that uses web search to update stock prices before each overview
• Multi-currency: Track positions in different currencies and monitor exchange rate exposure
• Alerts: Add rules like "warn me if any position exceeds 15% of my portfolio"
• Dividend tracking: Record dividend payments and calculate total return including income