bhardwajaditya/trader-in-alerts

What does trader-in-alerts do?

Price Alerts watches the numbers so the user does not have to stare at a chart. An alert is information, never an order: when a stop alert rings, nothing is sold by this skill. The stop (SL-M sell) and the target (LIMIT sell) sit at the broker as two separate orders and do the work; the alerts tell the user what happened, remind them to cancel the leftover order, and say when it is time to be flat.

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

python3 "${CLAUDE_SKILL_DIR}/alerts.py" clock                          # NSE open or closed, pre-open, next open (IST)
python3 "${CLAUDE_SKILL_DIR}/alerts.py" add --from-plan                # stop, target, flat-by from trader-in/plan.json
python3 "${CLAUDE_SKILL_DIR}/alerts.py" add --opening-bell             # 09:15 IST
python3 "${CLAUDE_SKILL_DIR}/alerts.py" add --pre-open                 # 09:00 IST pre-open (optional)
python3 "${CLAUDE_SKILL_DIR}/alerts.py" add --symbol RELIANCE --stop 1193.30
python3 "${CLAUDE_SKILL_DIR}/alerts.py" add --symbol RELIANCE --target 1201.10
python3 "${CLAUDE_SKILL_DIR}/alerts.py" add --at 15:10 --label "flat by" --before-close --symbol RELIANCE
python3 "${CLAUDE_SKILL_DIR}/alerts.py" add --symbol TCS --pct 2
python3 "${CLAUDE_SKILL_DIR}/alerts.py" add --symbol ^NSEI --pct 1     # Nifty 50 (watch only)
python3 "${CLAUDE_SKILL_DIR}/alerts.py" check                          # exit 0 = something rang
python3 "${CLAUDE_SKILL_DIR}/alerts.py" quote RELIANCE "M&M" --write   # -> trader-in/prices.json
python3 "${CLAUDE_SKILL_DIR}/alerts.py" quote --holdings --write       # portfolio + plan tickers
python3 "${CLAUDE_SKILL_DIR}/alerts.py" list
python3 "${CLAUDE_SKILL_DIR}/alerts.py" reset reliance-ns-plan-stop

--now "2026-10-27 15:10" pins the clock (IST; a bare 15:10 is today IST, Z or +05:30 is absolute); --offline DIR reads saved quote files instead of the network. Quote M&M in the shell ("M&M"), or & splits the command.

Symbols

RELIANCE, RELIANCE.NS and NSE:RELIANCE are NSE; RELIANCE.BO and BSE:RELIANCE are BSE. A bare symbol is NSE (or config default_exchange). Files always hold the Yahoo form (RELIANCE.NS). A bare six-digit number is read as a BSE scrip code (500325.BO), but Yahoo does not serve numeric BSE codes (it answered "No data found" on 2026-10-27): use RELIANCE.BO. Indices ^NSEI (Nifty 50), ^NSEBANK (Bank Nifty) and ^BSESN (Sensex) can be watched and quoted in points, never traded.

What it reads and writes

file	what
trader-in/plan.json	the trade from trader-in-exit, for add --from-plan
trader-in/config.json	flat_by (default 15:10), default_exchange, extra_holidays, special_sessions
trader-in/alerts.json	the rules (alerts.example.json in this folder)
trader-in/state/alerts.json	which rules rang and when, so each rings once
trader-in/prices.json	the latest quotes in rupees, merged in, for trader-in-budget and trader-in-risk
trader-in/portfolio.json	the symbols held, for quote --holdings

Rule types

type	rings when	rings again
above / target	price at or above price	after reset, or on its own if "rearm": true and the price fell back
below / stop	price at or below price	same
pct_move	moved pct percent from the previous close (or ref), optional direction up or down; only on a quote from today	once per day at most
time	the IST clock passed at ("15:10") on a trading day	once per trading day
opening_bell	NSE is open (09:15 IST, or a special session's open)	once per trading day
pre_open	NSE pre-open is on (09:00-09:15 IST: order entry to 09:08, then matching)	once per trading day, only inside the pre-open

A rule with "date" is watched on that IST date only; --from-plan rules carry the plan's date, so yesterday's stop never rings today. A time rule with "before_close": true keeps its gap to the close on a special session that ends early: "flat by" at 15:10 rings at 14:40 on a session that closes at 15:00.

A stop or target ring adds: "Your stop and target are two separate broker orders, not OCO: if the stop filled, cancel the target order now" (or the other way round). Indian brokers dropped bracket orders and have no OCO for MIS, so a leftover SL-M or LIMIT sell stays live and can sell shares you no longer hold.

Quotes

• Yahoo chart JSON: query2.finance.yahoo.com/v8/finance/chart/RELIANCE.NS (symbol percent-encoded, M%26M.NS), an unofficial free endpoint, one request per ticker, half a second apart. On a 429 it waits and tries once more; on a 429, a 5xx or a network error after that it tries query1. It identifies itself as day-trader-skill-in/1.0. Yahoo serves NSE and BSE in INR with Asia/Kolkata times; the percent move uses its previous close.
• Stooq is not used: it lists no NSE/BSE tickers, and on 2026-10-27 its quote CSV answered 404 for every ticker and its other pages sat behind a JavaScript challenge.
• Free quotes are unofficial, delayed and can lag. They are fine for alerts and for checking a size, not for timing an order. The broker's price is the one that fills. Each price in trader-in/prices.json keeps its quote time, and trader-in-risk only uses one under 15 minutes old.
• If Yahoo is down, read the price from the broker (Kite, Upstox) and write it into trader-in/prices.json as {"as_of": "...Z", "prices": {"RELIANCE.NS": 1196.20}}.

The NSE clock

IST is UTC+05:30 all year (no daylight saving); the tool works it out itself and ignores the computer's own zone. Normal session 09:15 to 15:30 IST, pre-open 09:00 to 09:15 (order entry 09:00-09:08, matching 09:08-09:15). Brokers square off MIS positions from about 15:20 IST and charge for it, so the plan's flat-by defaults to 15:10.

• NSE equity holidays 2026 (weekdays): Jan 26 Republic Day, Mar 3 Holi, Mar 26 Ram Navami, Mar 31 Mahavir Jayanti, Apr 3 Good Friday, Apr 14 Ambedkar Jayanti, May 1 Maharashtra Day, May 28 Bakri Id, Jun 26 Muharram, Sep 14 Ganesh Chaturthi, Oct 2 Gandhi Jayanti, Oct 20 Dussehra, Nov 10 Diwali Balipratipada, Nov 24 Guru Nanak Jayanti, Dec 25 Christmas.
• Special sessions (not normal days): Sunday 2026-02-01 Union Budget day, 09:15-15:00; Sunday 2026-11-08 Muhurat trading, 14:20-15:30 with pre-open from 14:05, per NSE circular NSE/CMTR/76941 of 2026-10-19 (press reports differ on the close for closing-auction stocks: check the circular).
• 2027 is not published yet: for any year without a list the tool warns once ("NSE holidays for 2027 are not built in; add them to config extra_holidays") and treats weekdays as open. Add closures with config "extra_holidays": ["2027-01-26", ...] and sessions with "special_sessions": {"YYYY-MM-DD": ["HH:MM", "HH:MM"]}.

Steps

1. Right after trader-in-exit writes the plan, run add --from-plan. Confirm the three alerts back to the user: the stop, the target and the flat-by time, in rupees and IST. Say that the stop and target are separate orders at the broker: when one fills, the other must be cancelled.
2. Run check while the trade is open: every few minutes from a Claude scheduled task or /loop. Each run fetches only the symbols in today's rules and rings each alert once. A check reads the latest delayed quote; it is not a live feed, and a price can pass a level between two checks.
3. Tell the user what rang in one line each. A stop or target alert means that order has probably filled: check positions and orders in the broker app, cancel the other order, and record the fill with /trader-in-broker. "Flat by" means close anything still open before the MIS square-off: /trader-in-broker flatten, then /trader-in-risk, then the user's yes, then cancel the leftover stop and target. Never act for them.

Example: the reel

RELIANCE.NS on Tuesday 2026-10-27: opening range 1,189.70-1,197.00, entry ₹1,197.20 at 12:40 IST, stop ₹1,193.30 (range midpoint), target ₹1,201.10 (1R), flat by 15:10. add --from-plan writes reliance-ns-plan-stop, reliance-ns-plan-target and reliance-ns-flat-by for that day. A check at 15:05 reads the real last quote, ₹1,196.20, between the stop and the target:

NSE OPEN (2026-10-27 15:05 IST, normal session).
Nothing hit. 3 rule(s) watched today, RELIANCE.NS ₹1,196.20.

At 15:10:

ALERT Flat by: it is 15:10 IST (set for 15:10), the market closes at 15:30 IST. Brokers square off MIS
positions from about 15:20 IST and charge for it. If RELIANCE.NS is still open, close it:
/trader-in-broker flatten --symbol RELIANCE.NS builds the sell ticket, then /trader-in-risk and your yes.
Then cancel any stop and target orders still pending for it at the broker.

It rings once. The next morning the plan's three alerts are no longer watched; with add --pre-open and add --opening-bell, they ring at 09:00 and 09:15.

Rules

• An alert is a fact about a price or the clock. Say it as a fact.
• Never present a quote as live. Free quotes are delayed and unofficial.
• Confirm every new rule back to the user: symbol, type, level in ₹, day.
• Money in rupees with Indian grouping (₹1,23,456.78); times in IST.

What it never does

It never places, cancels or changes an order, never claims a quote is live, and never predicts where a price is going.

Safety

• Education and tooling, not investment advice. For advice, talk to a SEBI-registered investment adviser. A PASS is a rules check, not a recommendation.
• Paper trading by default ("paper": true): Indian brokers have no paper account, so paper is a local simulated ledger (trader-in/state/paper.json). Going live is the user's own decision, in their own config.
• Nothing in this pack places an order except trader-in-broker, and only when all three hold: trader-in-risk passed that exact order today, paper is false, and the user typed an explicit yes for that one order in the chat.
• Long cash equities only: no F&O, options, short selling or MIS 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.