autoportfolio — A Stateful AI Portfolio Manager for Claude Code

⚠️ Not financial advice. Highly experimental. Use at your own risk.

autoportfolio is a personal research project. It is not a registered investment advisor, broker, or financial product. Nothing it outputs constitutes investment, tax, or trading advice. The strategy logic is opinionated, the data sources can be wrong or delayed, the LLM can hallucinate, and the math has known approximations (FX history, dividend withholding, multi-currency cash). The author accepts no liability for losses, missed gains, tax consequences, or any other harm arising from using this software. Verify every number before acting on it. Do not deploy capital you cannot afford to lose.

I had a Notion page with seventeen tickers, four columns of “buy below / RSI cutoff / cooldown until”, and a sticky note that said “check JEQP.L distribution Friday”. Three weeks later I noticed AMAT had broken its 50-day moving average eight sessions ago. I’d forgotten why I owned EOAN.DE in the first place. The Notion page was a fossil.

The problem isn’t deciding what to do. The problem is doing it — every session, on every position, while remembering the cooldowns and the rationale and the tax-residency-specific UCITS substitutions. It’s a job. A boring one. Most weeks I did it badly.

The shape of the fix isn’t a finance app. It’s Karpathy’s autoresearch — but for personal investing instead of ML experiments. A single instruction file describing the loop. A handful of small scripts that fetch data, execute trades, and render a dashboard. A JSON state file the agent picks up between runs. No bespoke framework. No SaaS dependency. Just files an LLM can reason over, run after run.

I shipped that this week as autoportfolio. It’s a Claude Code plugin. Open source, free, MIT licensed.

What autoresearch got right

Karpathy’s framing is: don’t write a framework, write a loop the agent runs. The repo is roughly a CLAUDE.md describing the workflow, a few Python scripts that handle the deterministic parts (fetch, write, plot), and state in flat files. The LLM does the reasoning. The scripts do the I/O. The state file means session N can pick up from session N−1 without a database.

That same shape works for portfolio management. The reasoning is hard to write down — “is this an entry, or am I chasing a green candle?” — but the bookkeeping is trivial. So you let the LLM do the reasoning, you write the bookkeeping in 800 lines of Python, and the instruction file (SKILL.md in Claude Code’s vocabulary) glues them together.

What I wanted from a portfolio manager

• Stateful: knows my available cash, holdings, recent trades, cooldowns, watchlist, and the rationale behind every position.
• Opinionated: a Barbell strategy pairing high-momentum growth with tax-efficient dividend income, with automatic UCITS substitution for non-US tax residents (skip the 30% US dividend withholding).
• Auditable: every trade timestamped with action, price, shares, rationale, and resulting cash. Undo-able.
• Multi-currency-correct: I hold EUR-listed positions on Frankfurt, USD on Nasdaq, GBP on LSE. P&L should decompose cleanly into stock movement and FX translation. Most personal-finance trackers silently treat one number as the other and call it a day.
• Runnable two ways: interactively when I want to trade, autonomously on a schedule when I want a monitor report waiting for me in the morning.

Two modes, one state file

/autoportfolio

Interactive: validates any tickers I throw at it, discovers new picks aligned to my strategy via web research, runs sell-signal checks on every existing holding, presents a full plan (validation table, sell orders, buy orders, projected cash), waits for my approval, executes, snapshots, opens the dashboard. Nothing happens without a yes.

/autoportfolio monitor

Autonomous: same sell-signal logic, no human in the loop. Outputs a structured text report with alerts, watchlist triggers, P&L update. Schedule it via Claude Code’s /schedule:

/schedule create --cron "0 8 * * 1-5" --prompt "Run /autoportfolio monitor"

Wake up to the report.

The hard part: multi-currency without lying

The boring-but-load-bearing decision was the data model. Each holding is stored natively:

{
  "BAS.DE": {
    "shares": 11,
    "currency": "EUR",
    "avg_cost_native": 51.93,
    "fx_rate_at_buy": 1.0764
  }
}

avg_cost_native is per share in the trade currency. fx_rate_at_buy is the cost-weighted average rate when those shares were acquired. Per-position P&L decomposes:

• Stock: (price_native − avg_cost_native) × shares — pure equity movement.
• Reporting (USD): (price_native × fx_now − avg_cost_native × fx_at_buy) × shares — what the trade is worth in your home currency now.
• FX: pnl_reporting − pnl_native × fx_now — the translation gain isolated.

The dashboard’s P&L card surfaces the split as Stock $X · FX $Y. When the dollar moves and your headline number jumps three percent overnight, you can see whether anything actually happened.

The full data model, including the v2 schema migration and the verify_cost_basis op for fixing mistagged imports, is on the GitHub README.

The dashboard

Generated as a single static data/dashboard.html after every session:

• Top cards: Total Portfolio Value, Available Cash, Contributions reconciled against expected cycles, Total P&L with the Stock/FX decomposition.
• Portfolio Value Over Time chart.
• Dividend Goal section with two scenario projections — Scenario A keeps your growth/dividend split forever, Scenario B grid-searches the optimal year to pivot the entire growth bucket into dividend instruments. Both render as monthly-income and total-portfolio-value curves over time, with a trade-off summary so you can see what each path costs.
• Holdings table with two-line cells for non-reporting currencies (native price + reporting-currency value with the FX rate inline). Per-position FX P&L decomposition. “Verify” / “approx” badges on positions with uncertain cost basis.
• Watchlist with conditions and trigger status.
• Trade ledger with rationale on every row.

What’s in the box

• SKILL.md describing the interactive and monitor flows.
• Three Python scripts: fetch_data.py (live prices + ticker search via yfinance), execute_trade.py (trades, imports, cash management, snapshots, undo, edit), generate_dashboard.py (HTML builder).
• 15 stdlib unittest cases covering FX math, the migration, snapshot dual schema, dashboard rendering, edit/undo of weighted-average state.
• TypeScript-style strictness in the data model — schema versioned, idempotent migrations, dual-write of legacy aliases for one release.
• MIT licensed. Source on GitHub. Installable from the Claude Code marketplace:

/plugin marketplace add sebastiangrebe/autoportfolio
/plugin install autoportfolio

Who this is for

If you’re a hobbyist investor running a small-to-medium portfolio across multiple currencies and you want something that (a) remembers what it did last week, (b) doesn’t lie about FX, and (c) lets you audit every decision back to a timestamp and a sentence of rationale — this is the least annoying setup I’ve found. Strategy lives in the state file as config; fork the repo, change the split, run.

If you’re building agents on top of Claude Code and want a reference for the autoresearch-style “instruction file + scripts + JSON state” pattern applied to something with real money on the line, the source is small enough to read in one sitting.

Grab it from the Lab — sign in to unlock the GitHub repo, install instructions, and issue tracker. I run this on my own portfolio, so feedback gets fixed fast.

(Reminder from the top: not financial advice, no liability, highly experimental. Verify every number before acting on it.)