trader-budget

trader-budget

The Budget Manager turns a plan ("buy TSLA at 364.18, stop 358.32") into an exact order ("buy 8 shares"), inside rules the user sets once. The stop decides the size: the further away the stop, the fewer shares. It writes a proposal only. trader-risk checks it and trader-broker asks the user yes or no. Day trading loses most people money. Sizing to a max loss keeps each loss small; it does not make a trade win.

${CLAUDE_SKILL_DIR} below is this skill's folder (where this SKILL.md lives).

python3 "${CLAUDE_SKILL_DIR}/size.py"                        # trader/plan.json + trader/config.json
python3 "${CLAUDE_SKILL_DIR}/size.py" --write                # write trader/orders.json
python3 "${CLAUDE_SKILL_DIR}/size.py" --limit --write        # a limit order at the plan's entry
python3 "${CLAUDE_SKILL_DIR}/size.py" --limit 364.00 --json  # a limit order at 364.00
python3 "${CLAUDE_SKILL_DIR}/size.py" --weights AAPL=40,KO=60 --config split.json   # weights mode, below

--now "2026-10-19 10:15" pins the clock (New York time). A plan for another day is refused: make a new one with trader-exit.

What it reads and writes

file	what
trader/config.json	the rules (start from config.example.json in this folder)
trader/plan.json	the trade: entry, stop, target, setup, flat-by time (trader-exit writes it)
trader/prices.json	optional: a fresh price above the plan's entry means a bigger risk (trader-alerts writes it)
trader/portfolio.json	optional: its cash caps the size (trader-broker keeps it)
trader/orders.json	the one proposed bracket order it writes with --write

Step 1: set the rules once

If trader/config.json does not exist, copy config.example.json into trader/config.json and ask the user for each value in plain words:

• budget: how much money this is for. Only money they can afford to lose.
• cash_buffer_pct: how much always stays in cash (default 10).
• max_loss_per_trade_usd: the most one trade may lose if the stop fills at the stop (default 50).
• max_position_pct, max_order_usd, min_order_usd: the biggest position (75% of the budget), the biggest order ($4,000) and the smallest order ($5).
• The day limits trader-risk enforces: max_daily_loss_usd (150), max_trades_per_day (3), min_reward_risk (1.0), require_stop (true), no_entries_before / no_entries_after ("09:45" / "15:30") and flat_by ("15:55"), all New York time.
• blocked: tickers they never want to trade.
• Keep paper true until they have watched it work on a paper account.

Step 2: size the trade

python3 "${CLAUDE_SKILL_DIR}/size.py" --write

Whole shares only: Alpaca takes no fractions in a bracket order. The size is the smallest of four limits:

limit	shares
max loss	max_loss_per_trade_usd / risk a share (entry minus stop)
position cap	budget x max_position_pct / entry
max order	max_order_usd / entry
cash	(budget minus the cash buffer) / entry, never more than the cash in trader/portfolio.json

The entry it sizes at: the limit price with --limit. For a market order, the plan's entry, or the price in trader/prices.json if it is fresh (under 15 minutes old) and higher. A price that ran up since the plan means a bigger loss at the same stop, so fewer shares. A lower price never shrinks the risk.

It refuses, and writes no order, when: the size is zero shares, the order is under the minimum, reward:risk is under min_reward_risk, the stop is not below the entry, the target is not above it (the move already happened), the plan is for another day, the ticker is blocked, or the plan is a short. Say the reason to the user in one line.

Step 3: show the user

Show the four limits, which one decided the size, the shares, the dollars and the max loss at the stop. Say plainly that a stop is an order, not a promise: in a fast market it can fill below the stop. Then hand over to /trader-risk.

Example: the reel

TSLA on Monday 2026-10-19. Opening-range breakout: entry 364.18 at 10:15 AM, stop 358.32 (the opening-range midpoint), target 370.04 (1R). Risk 5.86 a share. The example config: $5,000 budget, 10% cash buffer, $50 max loss.

limit	the math	shares
max loss	$50 / 5.86	8 (decides it)
position cap	75% of $5,000 = $3,750 / 364.18	10
max order	$4,000 / 364.18	10
cash	$5,000 minus $500 = $4,500 / 364.18	12

8 shares = $2,913.44. Max loss at the stop: 8 x 5.86 = $46.88. It writes:

{"symbol": "TSLA", "side": "buy", "qty": "8", "type": "market", "time_in_force": "day",
 "order_class": "bracket", "take_profit_limit_price": "370.04", "stop_loss_stop_price": "358.32",
 "why": "opening-range breakout on TSLA: 8 shares, bound by your $50 max loss per trade (8 x 5.86 = $46.88 at the stop)",
 "plan": {"entry": 364.18, "stop": 358.32, "target": 370.04, "risk_per_share": 5.86, "max_loss": 46.88,
          "setup": "orb", "entry_time": "10:15 AM", "flat_by": "15:55"}}

why and plan are notes for trader-risk and trader-broker. They are never sent to Alpaca. With the stop at 300.00 instead, one share would risk 64.18, more than the $50 max loss: no order. At 10:52 the real quote was 366.48, so the same plan sizes to 6 shares at 8.16 a share, and reward:risk falls to 0.44: refused, because the move it was waiting for has mostly happened.

Weights mode (kept from v1)

--weights AAPL=22.04,KO=10.86 or --targets FILE (targets.example.json here) splits a budget across a list by weight: the cash buffer comes off the top, weights are renormalised to 100, any stock over max_position_pct is pinned at the cap and its excess shared out, slices under the minimum order are dropped, and amounts round to whole dollars so nothing is left idle by accident. With "max_position_pct": 25 and "fractional": true, the example file gives AAPL $1,250 (capped), AXP $1,119, GOOGL $823, KO $708, BAC $600. With "fractional": false (the example config) it buys whole shares and needs prices (--prices trader/prices.json). These are plain buys with no stop: trader-risk blocks them while require_stop is true and counts each one against max_trades_per_day. Use a separate config (--config) for a long-term split.

Rules

• Proposals only. This skill never calls a broker tool.
• Never size money the user has not said is for this. Ask for the budget and the max loss.
• Every number comes from the config, the plan or the prices. Nothing is guessed.
• No projections: never say what a trade will make. A target is a plan, not a forecast.
• Free Yahoo prices are unofficial and can lag. The broker's price is the one that fills.

What it never does

It never places, approves or schedules an order, never raises a limit on its own, never shrinks a stop to fit more shares, and never sizes options, margin or short positions.

Safety

• Education and tooling, not financial advice. A PASS is a rules check, not a recommendation.
• Paper trading by default ("paper": true). Going live is the user's own decision, in their own config.
• Nothing in this pack places an order except trader-broker, and only when all three hold: trader-risk passed that exact order today, the user typed an explicit yes for that one order in the chat, and the user clicked Allow once on Claude's own card because the order tool is set to "Needs approval" (Customize > Connectors > tool permissions). Never set an order tool to "Always allow".
• No options, margin, short selling or leverage unless the config allows it and the user confirms.
• Broker keys live in environment variables or the Claude Desktop config, never in the chat.