Skip to content
Back to search

market-stress-monitor

AI-assisted US market-stress monitor: multi-source macro data, a deterministic rule engine for crash signals, AI-written daily briefs, live dashboard, push alerts, and free-tier scheduled runs.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/abhay-sud--market-stress-monitor/badge.svg)](/listings/abhay-sud--market-stress-monitor)

HTML

<a href="/listings/abhay-sud--market-stress-monitor"><img src="/api/listings/abhay-sud--market-stress-monitor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You'll need your own Supabase project, Cloudflare Pages, GitHub Actions, several free API keys and an MCP client such as Claude Desktop or Claude Code. Requires Node 22+. Each of `ingestion/`, `rule_engine/` and `mcp_server/` is an independent package (`npm ci` inside each) with a `.env.example` to copy to `.env`:

| Variable | Needed | What it's for | |---|---|---| | `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY` | Yes | Your Supabase project | | `FRED_API_KEY` | Yes | Free, [fred.stlouisfed.org](https://fred.stlouisfed.org/docs/api/api_key.html) | | `EIA_API_KEY` | Yes | Free, [eia.gov/opendata](https://www.eia.gov/opendata/) | | `MASSIVE_API_KEY` | For watchlist prices | Free tier at massive.com | | `SEC_EDGAR_CONTACT_EMAIL` | For SEC data | SEC requires a contact address in automated requests | | `POLYMARKET_SLUGS` | Optional | Polymarket markets to track | | `NTFY_TOPIC` | Optional | A random, unguessable ntfy.sh topic for the local wave-trigger alert (`mcp_server`, not GitHub Actions) |

Then:

1. Copy each `local_state/*.example.yaml` to the same name without `.example` and fill in your own values, starting with `policy.yaml` (your wave triggers and splits) and `portfolio.yaml`. Optionally add a `local_state/personal-rules.md` with your own versions of the rules doc's personal sections, under the same headings. 2. Tune [`config/monitoring.yaml`](config/monitoring.yaml) if you want different bands or a different stress gate. 3. Apply `supabase/migrations/` in order (SQL editor or Supabase CLI). 4. Add the same values as GitHub Actions secrets for `.github/workflows/ingest.yml`. Run `backfill.yml` once to load history. 5. MCP client: merge [`mcp_server/claude_desktop_config.example.json`](mcp_server/claude_desktop_config.example.json) into your config (the MCP server needs `PORTFOLIO_PATH` and `WAVE_DEPLOYMENT_STATE_PATH`; the other local files default to sitting next to `PORTFOLIO_PATH`). In Claude Desktop, create a project and set its instructions to one line: *"Before anything else, call the crash-check `get_instructions` tool and follow what it returns."* Attach nothing as project knowledge. 6. `dashboard_site/`: a Cloudflare Pages project with no build step. Swap in your own Supabase URL and anon key. 7. `full_report_site/`: a second Pages project behind Cloudflare Access. See [`full_report_site/README.md`](full_report_site/README.md).

`npm run typecheck` works in all three packages.

If you keep personal data in `local_state/` and push to a public fork, turn on the leak guard once per clone: `git config core.hooksPath .githooks`, then copy `local_state/leak-guard.example.yaml` to `leak-guard.yaml` and add your own name and email.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 488 lines
  1. <div align="center">
  2. # Macro Market Stress Monitor
  3. **The LLM writes the story. The code makes the call.**
  4. A daily market-stress and crash-risk monitor built on public data. A
  5. deterministic TypeScript rule engine scores six crash indicators
  6. RED / AMBER / GREEN. Claude, connected over MCP, does the research and writes
  7. the narrative, and never re-derives a number.
  8. [![Daily ingest](https://img.shields.io/github/actions/workflow/status/abhay-sud/market-stress-monitor/ingest.yml?branch=main&style=flat-square&label=daily%20ingest)](https://github.com/abhay-sud/market-stress-monitor/actions/workflows/ingest.yml)
  9. [![Live site](https://img.shields.io/website?url=https%3A%2F%2Fmarketstress.org&style=flat-square&label=marketstress.org&up_message=live&down_message=down)](https://marketstress.org/)
  10. [![Last commit](https://img.shields.io/github/last-commit/abhay-sud/market-stress-monitor?style=flat-square)](https://github.com/abhay-sud/market-stress-monitor/commits/main)
  11. <br>
  12. ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)
  13. ![Node.js 22+](https://img.shields.io/badge/Node.js-22%2B-5FA04E?style=flat-square&logo=nodedotjs&logoColor=white)
  14. ![Supabase](https://img.shields.io/badge/Supabase-3FCF8E?style=flat-square&logo=supabase&logoColor=white)
  15. ![Cloudflare Pages](https://img.shields.io/badge/Cloudflare%20Pages-F38020?style=flat-square&logo=cloudflarepages&logoColor=white)
  16. ![GitHub Actions](https://img.shields.io/badge/GitHub%20Actions-2088FF?style=flat-square&logo=githubactions&logoColor=white)
  17. ![MCP](https://img.shields.io/badge/MCP-server-111111?style=flat-square&logo=modelcontextprotocol&logoColor=white)
  18. ![Claude](https://img.shields.io/badge/Claude-D97757?style=flat-square&logo=claude&logoColor=white)
  19. **[Live dashboard →](https://marketstress.org/)** · free, no sign-up, updated daily<br>
  20. **[Get the alerts on your phone →](docs/run-your-own.md)** · fork, add two secrets, done<br>
  21. [How it works](#how-it-works) · [Evidence](#evidence-over-vibes) · [Rules](reference_docs/rules/crash-check-rules.md) · [Run it yourself](#run-it-yourself) · [Known gaps](BACKLOG.md)
  22. <a href="https://marketstress.org/">
  23. <img src="docs/screenshots/stress.png" alt="The Stress tab of marketstress.org: 1 of 6 indicators red, the six-indicator gate panel with 60-day sparklines, distance to red, the drawdown risk band and upcoming catalysts" width="900">
  24. </a>
  25. </div>
  26. > [!WARNING]
  27. > **Not investment advice.** This is a personal, educational project. The
  28. > dashboard's bands, stress gate and crash probability apply the author's own
  29. > rules to public data. They are not recommendations to buy or sell anything,
  30. > and the data can be delayed, revised or wrong. The code is shared as-is,
  31. > with no warranty.
  32. ## Get the alerts yourself
  33. Fork this repo, add a free FRED key and an [ntfy](https://ntfy.sh/) topic as
  34. secrets, and switch on GitHub Actions. Every weekday evening your phone gets
  35. the reading, plus an alert when something changes. No server, no database,
  36. no cost. This is what it sent on Friday 20 November 2026:
  37. ```
  38. S&P 500 now 11.6% below its high
  39. Fri Nov 20: The S&P 500 closed at 6910.39, 11.6% below its all-time high of
  40. 7818.93 (2026-10-06): past the 10% line. 0 of 6 confirmed RED; stress gate not met.
  41. Market stress · Fri Nov 20
  42. 1 of 6 RED: VIX 35.89 (not yet confirmed)
  43. 3 AMBER: High-yield spread 352 bp (Nov 19) · S&P 500 drawdown 11.6% · 10-year Treasury 4.92%
  44. Stress gate: not met (0 of 6 confirmed RED; the gate needs 3)
  45. Drawdown risk band: not scored, because the S&P 500 is already 11.6% below its high.
  46. Closest to RED: 10-year Treasury 0.08 pts away · S&P 500 drawdown 8.4 pts away
  47. Not investment advice · marketstress.org
  48. ```
  49. Same rules and code as the live site. Optional extras: your own crash-plan
  50. triggers as a private secret (you get "Wave 2 trigger hit", never the
  51. levels), Telegram/Discord/Slack/email, and a short AI summary from the
  52. model of your choice, whose numbers are checked against the data before it's
  53. sent. **[Ten-minute setup →](docs/run-your-own.md)**
  54. ## Contents
  55. - [Get the alerts yourself](#get-the-alerts-yourself)
  56. - [Why this exists](#why-this-exists)
  57. - [The dashboard](#the-dashboard)
  58. - [How it works](#how-it-works)
  59. - [What's deterministic and what's judgment](#whats-deterministic-and-whats-judgment)
  60. - [Evidence over vibes](#evidence-over-vibes)
  61. - [The indicators](#the-indicators)
  62. - [AI workflows over MCP](#ai-workflows-over-mcp)
  63. - [Security model: public engine, private policy](#security-model-public-engine-private-policy)
  64. - [Tech stack](#tech-stack)
  65. - [Run it yourself](#run-it-yourself)
  66. - [Project structure](#project-structure)
  67. - [Contributing, security and status](#contributing-security-and-status)
  68. ## Why this exists
  69. It started as a giant static prompt: numbers hand-pasted into an LLM chat on
  70. every run. That gave confident, unrepeatable answers. It became a small
  71. pipeline built on three rules:
  72. - **Numeric classification is never an LLM's job.** Every threshold, band and
  73. RED/AMBER/GREEN colour is computed by plain code from real market data. The
  74. LLM reads news, judges Fed communication and writes the narrative, and it
  75. always reports what the code already decided.
  76. - **Every signal has to earn its place.** New flags are backtested for a base
  77. rate and a forward edge before they ship. Ideas that fail stay documented
  78. with their evidence, and features that turn out to be noise get deleted.
  79. - **Personal data never leaves the machine.** The engine and the dashboard
  80. are public; the deployment policy and every dollar figure stay in local,
  81. gitignored files, with guardrails in code that refuse to publish them.
  82. ## The dashboard
  83. [marketstress.org](https://marketstress.org/) has four read-only tabs, each
  84. with its own URL:
  85. | | |
  86. |---|---|
  87. | **[Stress](https://marketstress.org/)**: the six-indicator panel, the stress gate, distance to RED, the drawdown risk band, a 3-month scenario view, upcoming catalysts, divergence flags and indicator history charts with their bands. | **[Smart Money](https://marketstress.org/smart-money)**: futures positioning (CFTC), options put/call and margin debt as historical percentiles, sector capital rotation, and institutional 13F net buying by sector. |
  88. | <img src="docs/screenshots/stress.png" alt="Stress tab" width="440"> | <img src="docs/screenshots/smart-money.png" alt="Smart Money tab: positioning measures shown as percentiles of their own history" width="440"> |
  89. | **[Macro & Fiscal](https://marketstress.org/macro)**: a fiscal dominance checklist, contextual indicators, the yield curve and rates decomposition, and a short AI-written summary that is only rewritten when the data underneath changes. | **[Notable Views](https://marketstress.org/views)**: what well-known macro voices are saying, set against today's data. Short attributed paraphrases with links and dates, reviewed by hand before publishing. |
  90. | <img src="docs/screenshots/macro.png" alt="Macro & Fiscal tab: fiscal dominance checklist and yield curve" width="440"> | <img src="docs/screenshots/views.png" alt="Notable Views tab: macro commentators' views checked against live data" width="440"> |
  91. You can browse past reports with a calendar picker, check each source's
  92. freshness, and install the dashboard as a home-screen app (PWA).
  93. <details>
  94. <summary>Animated tour (recorded 2026-11-15)</summary>
  95. <br>
  96. <img src="docs/demo.gif" alt="Animated tour of the four dashboard tabs" width="880">
  97. </details>
  98. ## How it works
  99. ```mermaid
  100. flowchart LR
  101. SRC["Public data<br/>FRED · Treasury · Yahoo · EIA · CBOE<br/>CFTC · FINRA · SEC EDGAR · State Street<br/>GPR index · Polymarket · Massive"]
  102. ING["ingestion/<br/>fetch · normalise ·<br/>plausibility guard"]
  103. DB[("Supabase<br/>public: market data, rule output<br/>private: report snapshots<br/>no dollar figures")]
  104. RE["rule_engine/<br/>panel · stress gate ·<br/>risk band"]
  105. DASH["dashboard_site/<br/>public · marketstress.org"]
  106. FULL["full_report_site/<br/>private · Cloudflare Access"]
  107. MCP["mcp_server/<br/>21 MCP tools · runs locally"]
  108. LOCAL[["local_state/<br/>personal policy and balances<br/>never leave the machine"]]
  109. LLM["Claude<br/>research and narrative only"]
  110. SRC -->|"GitHub Actions<br/>10am + 6pm ET"| ING --> DB
  111. DB <--> RE
  112. DB --> DASH
  113. DB --> FULL
  114. DB <--> MCP
  115. LOCAL --> MCP
  116. MCP <--> LLM
  117. ```
  118. | Component | What it does |
  119. |---|---|
  120. | [`ingestion/`](ingestion/) | Pulls each source into Supabase. A plausibility guard quarantines implausible values before they're written, and a backfill script loads each series' full history. No LLM and no classification logic. |
  121. | [`rule_engine/`](rule_engine/) | Pure functions: the six-indicator panel, confirmation windows, the stress gate, cross-indicator divergence flags and the drawdown risk band. Writes `crash_checks`. Also holds the "run your own" alerts copy (`src/lite/`), which replays the same per-day logic from public data with no database. Vitest suite. |
  122. | [`mcp_server/`](mcp_server/) | Local stdio [Model Context Protocol](https://modelcontextprotocol.io/) server. 21 tools: workflow instructions, market state, context indicators, rules lookup, portfolio drift, watchlist, wave evaluation, deployment planning and fire drill, fund-filing watch, and write/persist tools. Runs locally because it's the only component that reads personal data. `node:test` suite. |
  123. | [`dashboard_site/`](dashboard_site/) | Public static site on Cloudflare Pages, no build step. Reads only public market data with the anon key. A small worker server-renders the latest reading for crawlers and AI tools. |
  124. | [`full_report_site/`](full_report_site/) | Private page behind Cloudflare Access: wave status, personal triggers, the watchlist with insider activity, crash-type diagnosis and the portfolio review. Rendered server-side, so no credential reaches the browser. |
  125. | [`config/`](config/) | `monitoring.yaml`: the public panel bands, confirmation days and stress gate, read by both `rule_engine` and `mcp_server`. |
  126. | [`supabase/migrations/`](supabase/migrations/) | Schema and row-level-security history. |
  127. ## What's deterministic and what's judgment
  128. This is a stress-monitoring and discretionary deployment dashboard, **not a
  129. calibrated crash-probability model**. Both reporting pages say so.
  130. | Output | How it's produced | Validated? |
  131. |---|---|---|
  132. | Six-indicator panel, bands, confirmation windows, stress gate | Code (`rule_engine/`), thresholds in `config/monitoring.yaml` | Deterministic and reproducible |
  133. | Deployment waves | Code (`mcp_server/`), triggers in a private local policy file | Deterministic. The pathways were replayed against every ≥20% S&P drawdown since 1993, but the thresholds are a personal choice, not an optimised fit |
  134. | Drawdown risk band: could the S&P end up 10% below its peak within ~21 trading days? | Code: S&P drawdown % + VIX / 5, three bands | Yes, modestly. See [the results below](#results-the-drawdown-risk-band) |
  135. | Scenario split and crash probability | A frozen historical bull/base/bear/crash split for the current risk band, which the LLM may tilt by one 5-point step | Partly: the split is history (a handful of crises); the tilt has no track record yet |
  136. | Crash-type diagnosis, Fed classification | LLM judgment informed by the panel and web research | No |
  137. The full write-up is in
  138. [`crash-check-rules.md`](reference_docs/rules/crash-check-rules.md)
  139. ("What this system actually is").
  140. ## Evidence over vibes
  141. How changes get made, and what's been thrown out along the way:
  142. - **New signals are backtested before they ship.** A flag needs a base rate
  143. and a forward edge. Rejected so far, with the evidence kept: a MOVE-vs-VIX
  144. divergence flag, a BDC-ETF private-credit proxy, high-frequency positioning
  145. signals and a CTA trend-exposure estimate. See "Investigated and rejected"
  146. in the rules doc,
  147. [`BUILD_SPEC_crash_check_enhancements.md`](reference_docs/BUILD_SPEC_crash_check_enhancements.md)
  148. and the
  149. [hazard-model rebuild brief](reference_docs/hazard-model-rebuild-brief.md).
  150. - **A model that couldn't beat a simple rule was retired.** A 32-input
  151. logistic hazard model looked strong in-sample. Refit honestly out of sample,
  152. it scored an AUC of 0.545 (a coin flip is 0.5) against 0.818 for a
  153. two-input drawdown + VIX rule, and three rebuilt variants also failed. The
  154. rule replaced it, and the model is still scored daily, side by side, so the
  155. record stays honest
  156. ([`hazard-model-rebuild-brief.md`](reference_docs/hazard-model-rebuild-brief.md)).
  157. - **Rules that hurt in backtests are relaxed, in public.** Requiring the
  158. 3-of-6 stress gate before deploying blocked six deployments since 1990 that
  159. were all up a year later, and never blocked one that lost (two
  160. pre-registered backtests on 1962–2026 data, reproduced by an independent
  161. reviewer). Since 2026-11-19 the gate is shown as information, not required.
  162. - **An alert that never warned in time was replaced.** The original phone
  163. alert fired when 2 indicators were confirmed RED. Replayed over 1990–2026,
  164. it fired before the S&P was 10% down in none of the four bear markets, and
  165. a 10% fall followed it less often than an ordinary day. It was retired for
  166. an alert on the deployment triggers themselves
  167. ([`config/monitoring.yaml`](config/monitoring.yaml)).
  168. - **Ideas that sound smart but don't pay are left out.** Tilting holdings by
  169. macro regime was tested before it could be built: instrument tilts added
  170. +0.14% a year (90% interval −0.76% to +0.96%) and industry tilts −0.49%,
  171. so the regime notes stay as context only (rules doc, "Regime → Instrument
  172. Fit").
  173. - **Low-signal features get cut.** A discretionary "Risk Radar" score was
  174. retired, and later deleted, after its readings swung run to run on
  175. unchanged data.
  176. - **Refactors are checked for identical behaviour.** Moving thresholds into
  177. config files and wave evaluation onto the local machine was verified by
  178. diffing old and new code over every input combination and the full real
  179. history before switching over.
  180. - **External reviews are written down with their outcomes**
  181. ([`architecture-summary-for-external-review.md`](reference_docs/architecture-summary-for-external-review.md)).
  182. ### Results: the drawdown risk band
  183. Score = S&P drawdown from its all-time high (%) + VIX / 5. The cutoffs were
  184. fixed before any live scoring and are never retuned from live results.
  185. | Band | Score | Share of days, 1994–2026 | S&P closed 10%+ below its peak within the next ~21 trading days |
  186. |---|---|---|---|
  187. | Low | below 8.5 | ~77% | 4.6% |
  188. | Elevated | 8.5 to 10 | ~8% | 16.8% |
  189. | High | 10 and above | ~15% | 44.4% |
  190. | *All days* | | | *~12% base rate* |
  191. Ranking skill (AUC): 0.834 in the 1994–2026 replay, 0.818 out of sample. The
  192. live scorecard keeps recording each day's band against what actually
  193. happened.
  194. ## The indicators
  195. ### The six-indicator panel and the stress gate
  196. The panel tracks **VIX, HY credit spreads, S&P drawdown from its all-time
  197. high, the 10-year Treasury yield, the Sahm Rule and a Fed-pivot signal**. A
  198. RED reading only counts once it holds across two or more distinct ingestion
  199. dates, so a single noisy print can't trigger anything. The **stress gate** is
  200. met when 3 or more of the 6 are confirmed RED: a read on how broad the stress
  201. is. All of these thresholds live in
  202. [`config/monitoring.yaml`](config/monitoring.yaml).
  203. ### Deployment waves
  204. A staged, three-tranche plan for deploying a cash reserve. A wave becomes
  205. deployable when **its own trigger** holds: S&P drawdown from the all-time high
  206. plus a VIX level (same day), or a separate "slow-bear" pathway (deep drawdown
  207. plus a fresh one-year low, confirmed on two dates) for grinding,
  208. low-volatility bears like 2000–02 and 2022, which the drawdown + VIX pathway
  209. missed in backtesting. The stress gate is reported alongside; setting
  210. `stress_gate_required: true` in the config makes it a requirement again.
  211. Trigger levels and the percentage split of each wave are personal policy, so
  212. they live in a gitignored local file, not in this repo. Waves are evaluated
  213. on the local machine from public inputs the rule engine publishes (drawdown,
  214. VIX, days since a one-year low). Deployment is cumulative and
  215. execution-aware: a fast crash that skips straight to Wave 3 returns every
  216. not-yet-executed wave, and executed waves are tracked locally so they're
  217. never proposed twice.
  218. ### Context only (never gates)
  219. - **Contextual indicators:** financial-conditions and stress indices (incl.
  220. the OFR FSI), breakevens, jobless claims, IG spreads, the yield curve and
  221. the NY Fed's recession-probability model, the SOFR−IORB repo-stress spread,
  222. MOVE bond volatility, Treasury auction quality, copper, recent-grad
  223. unemployment and more.
  224. - **Distance to RED:** how far each panel indicator is from its RED band.
  225. - **Divergence detection:** pairs that normally move together, flagged when
  226. they decouple: IG vs HY spreads, initial vs continuing claims, VIX vs HY,
  227. gold vs silver, and foreign official Treasury holdings vs the 10-year
  228. yield.
  229. - **Positioning and flows:** CFTC Commitments of Traders, CBOE put/call and
  230. FINRA margin debt as historical percentiles; sector rotation; 13F
  231. institutional net buying by sector.
  232. - **Fiscal dominance checklist:** Taylor-rule gap, primary balance, net
  233. interest as a share of GDP and of receipts, the average rate on marketable
  234. debt, and the gold/real-yield relationship.
  235. - **Event-conditional scenarios** for scheduled events such as FOMC
  236. meetings, scored after the event.
  237. ## AI workflows over MCP
  238. The MCP server works with any MCP client. Two workflows run on it:
  239. - **"Run crash check"** runs every weekday evening as a headless Claude Code
  240. job, after the 6pm ingest. It confirms ingestion actually ran, pulls the
  241. panel and context, and commits to a scenario view **before** it can see the
  242. previous report's number. That anti-anchoring rule is enforced by tool
  243. order: no tool used in the first six steps exposes a prior probability. It
  244. then does the qualitative research, persists the result (`write_snapshot`
  245. for the public row, `write_full_report` for the private page) and ends with
  246. a plain-text summary. Steps:
  247. [`project-instructions.md`](reference_docs/rules/project-instructions.md).
  248. - **"Run portfolio review"** runs weekly. It covers portfolio drift against
  249. targets, watchlist status, a deployment fire drill, fund-filing checks and
  250. a re-underwrite of each watchlist thesis. It's rendered from
  251. [`portfolio-review-template.html`](reference_docs/rules/portfolio-review-template.html)
  252. and merged into the private Full Report page. It only proposes changes;
  253. applying them is a manual step.
  254. The instructions, the review template and the rules doc are served by the
  255. MCP server itself (`get_instructions`, `get_rules`) straight from this
  256. working tree, so a change takes effect on the next run without re-uploading
  257. anything.
  258. ## Security model: public engine, private policy
  259. Personal financial data never reaches a cloud service, and personal policy
  260. never reaches the public repo or the public tables.
  261. - **Three kinds of configuration.**
  262. - Public monitoring thresholds: [`config/monitoring.yaml`](config/monitoring.yaml).
  263. - Personal policy, local and gitignored: `local_state/policy.yaml` (wave
  264. triggers, wave and crash-type splits, hard rules, private terms) and
  265. `local_state/personal-rules.md` (the personal sections of the rules doc,
  266. merged in by the `get_rules` tool).
  267. - Dollar data, local and gitignored: balances, cash reserve, position
  268. sizing, executed waves, the exchange log.
  269. The repo tracks only `*.example.yaml` templates with illustrative numbers.
  270. - **Two access tiers in Supabase.** `crash_checks` and `data_points` are
  271. readable with the public anon key, which is how the dashboard works; they
  272. hold market data, rule output and market-event triggers only. Everything
  273. personal, including the private report snapshots, watchlist ticker prices
  274. (`private_data_points`), the watchlist and its insider activity, is
  275. readable only with the server-side key that the local MCP server and the
  276. Access-gated Pages Function hold.
  277. - **Guardrails in code, not just instructions.** Every write path that
  278. persists free text checks it against the real local portfolio and throws
  279. on any dollar figure. `write_snapshot` also refuses public text containing
  280. any of the policy's private terms (account names, "watchlist") and keeps
  281. only market-event triggers on the public row.
  282. - **A leak guard on every push.** A dependency-free pre-push hook
  283. ([`.githooks/leak-guard.mjs`](.githooks/leak-guard.mjs)) checks each new
  284. commit's changes, file names, message and author against the personal
  285. terms, tickers, fund names and dollar figures in the gitignored local
  286. files, plus common secret patterns, and blocks the push on any hit. The
  287. sensitive lists are read at push time, so they never enter the repo.
  288. - **Dollar amounts are computed at read time.** The policy stores wave
  289. splits as percentages of the cash reserve; the MCP server applies them to
  290. the local balance, and the result stays in the chat.
  291. Found a problem with any of this? See [`SECURITY.md`](SECURITY.md).
  292. ## Tech stack
  293. | Layer | What's used |
  294. |---|---|
  295. | Language and runtime | TypeScript, Node.js 22+ (three independent packages, no root workspace) |
  296. | Scheduling | GitHub Actions cron (10am ET Mon–Sat, 6pm ET Mon–Fri; SEC 13F manual, quarterly) |
  297. | Storage | Supabase Postgres with row-level security, two access tiers |
  298. | Public site | Static HTML/JS on Cloudflare Pages, plus a small worker for server-rendered metadata |
  299. | Private site | Cloudflare Pages Function behind Cloudflare Access |
  300. | AI layer | Model Context Protocol server (stdio), Claude for research and narrative |
  301. | Alerts | ntfy.sh push when a wave trigger fires (run locally); the "run your own" copy sends a daily brief and event alerts from GitHub Actions to ntfy, email, Telegram, Discord or Slack |
  302. | Tests | Vitest (`rule_engine`), `node:test` (`mcp_server`), `tsc --noEmit` everywhere |
  303. ## Run it yourself
  304. > **At your own risk.** The alerts-only copy below is packaged to run on its
  305. > own; the full setup after it is one person's working system, not a product.
  306. > If you only want to look at the signals, use the
  307. > [live dashboard](https://marketstress.org/).
  308. ### Alerts only: your own copy in ten minutes
  309. Get the six-indicator reading every weekday evening and an alert when
  310. something changes, on your phone (ntfy, Telegram, Discord, Slack or email).
  311. Fork the repo, add a free FRED key and one notification secret, and switch on
  312. GitHub Actions. No database, no website, nothing to install. You can also add
  313. your own wave triggers and get a private alert when one is hit. Same rules and
  314. code as the live site.
  315. **[Set it up: docs/run-your-own.md](docs/run-your-own.md)**
  316. ### Quick look: no keys, no accounts
  317. The rule logic is pure functions with tests, so you can read and run it
  318. without any credentials:
  319. ```bash
  320. git clone https://github.com/abhay-sud/market-stress-monitor.git
  321. cd market-stress-monitor/rule_engine
  322. npm ci
  323. npm test # Vitest: bands, confirmation, stress gate, risk band, scorecards
  324. cd ../mcp_server
  325. npm ci
  326. npm test # node:test: deployment instruments, trading limits, filings, scenario tilt
  327. ```
  328. Tests use `local_state/policy.example.yaml`, never a real policy.
  329. ### Full setup
  330. You'll need your own Supabase project, Cloudflare Pages, GitHub Actions,
  331. several free API keys and an MCP client such as Claude Desktop or Claude
  332. Code. Requires Node 22+. Each of `ingestion/`, `rule_engine/` and
  333. `mcp_server/` is an independent package (`npm ci` inside each) with a
  334. `.env.example` to copy to `.env`:
  335. | Variable | Needed | What it's for |
  336. |---|---|---|
  337. | `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY` | Yes | Your Supabase project |
  338. | `FRED_API_KEY` | Yes | Free, [fred.stlouisfed.org](https://fred.stlouisfed.org/docs/api/api_key.html) |
  339. | `EIA_API_KEY` | Yes | Free, [eia.gov/opendata](https://www.eia.gov/opendata/) |
  340. | `MASSIVE_API_KEY` | For watchlist prices | Free tier at massive.com |
  341. | `SEC_EDGAR_CONTACT_EMAIL` | For SEC data | SEC requires a contact address in automated requests |
  342. | `POLYMARKET_SLUGS` | Optional | Polymarket markets to track |
  343. | `NTFY_TOPIC` | Optional | A random, unguessable ntfy.sh topic for the local wave-trigger alert (`mcp_server`, not GitHub Actions) |
  344. Then:
  345. 1. Copy each `local_state/*.example.yaml` to the same name without
  346. `.example` and fill in your own values, starting with `policy.yaml`
  347. (your wave triggers and splits) and `portfolio.yaml`. Optionally add a
  348. `local_state/personal-rules.md` with your own versions of the rules
  349. doc's personal sections, under the same headings.
  350. 2. Tune [`config/monitoring.yaml`](config/monitoring.yaml) if you want
  351. different bands or a different stress gate.
  352. 3. Apply `supabase/migrations/` in order (SQL editor or Supabase CLI).
  353. 4. Add the same values as GitHub Actions secrets for
  354. `.github/workflows/ingest.yml`. Run `backfill.yml` once to load history.
  355. 5. MCP client: merge
  356. [`mcp_server/claude_desktop_config.example.json`](mcp_server/claude_desktop_config.example.json)
  357. into your config (the MCP server needs `PORTFOLIO_PATH` and
  358. `WAVE_DEPLOYMENT_STATE_PATH`; the other local files default to sitting
  359. next to `PORTFOLIO_PATH`). In Claude Desktop, create a project and set its
  360. instructions to one line: *"Before anything else, call the crash-check
  361. `get_instructions` tool and follow what it returns."* Attach nothing as
  362. project knowledge.
  363. 6. `dashboard_site/`: a Cloudflare Pages project with no build step. Swap
  364. in your own Supabase URL and anon key.
  365. 7. `full_report_site/`: a second Pages project behind Cloudflare Access.
  366. See [`full_report_site/README.md`](full_report_site/README.md).
  367. `npm run typecheck` works in all three packages.
  368. If you keep personal data in `local_state/` and push to a public fork, turn
  369. on the leak guard once per clone: `git config core.hooksPath .githooks`,
  370. then copy `local_state/leak-guard.example.yaml` to `leak-guard.yaml` and
  371. add your own name and email.
  372. ## Project structure
  373. ```
  374. ingestion/ data sources → Supabase, plausibility-guarded
  375. rule_engine/ deterministic panel, stress gate, risk band; src/lite/ = run-your-own alerts
  376. mcp_server/ local MCP tools (21), wave evaluation, wave-trigger alert
  377. dashboard_site/ public dashboard (static, Cloudflare Pages)
  378. full_report_site/ private Full Report page (Cloudflare Pages Function)
  379. config/ public monitoring thresholds
  380. reference_docs/rules/ rules doc, workflow instructions, review template
  381. reference_docs/ hazard-model explainer and rebuild brief, external-review summary, specs
  382. supabase/migrations/ schema + row-level security
  383. local_state/ *.example.yaml templates; real files are gitignored
  384. docs/ run-your-own setup guide, screenshots and demo
  385. .github/workflows/ daily ingest + classify, backfill, SEC 13F, run-your-own alerts
  386. ```
  387. ## Contributing, security and status
  388. - **Contributing:** questions, data issues and ideas are welcome. See
  389. [`CONTRIBUTING.md`](CONTRIBUTING.md) for what helps most and how new
  390. signals are judged.
  391. - **Security:** please don't open a public issue for a vulnerability. See
  392. [`SECURITY.md`](SECURITY.md).
  393. - **Conduct:** [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
  394. - **Known gaps:** [`BACKLOG.md`](BACKLOG.md) lists open items, deliberately
  395. deferred rather than forgotten.
  396. - **Data sources:** each source (FRED and the series' original providers,
  397. Treasury, EIA, CBOE, CFTC, FINRA, SEC EDGAR, State Street, Polymarket,
  398. Yahoo Finance, Massive) keeps its own terms, and you're responsible for
  399. complying with them when you run the code with your own keys.
  400. - **Status and support:** a personal project with a single maintainer,
  401. shared as-is and maintained as time allows. It runs daily and is actively
  402. used. Issues are for bugs and data problems; pull requests are welcome but
  403. may not be merged. There's no support commitment, and responses aren't
  404. guaranteed.
  405. ## License
  406. The code is released under the [MIT License](LICENSE). The license covers this
  407. repository's code only: market data from FRED, ICE, Treasury, Yahoo Finance
  408. and the other sources (including values in test fixtures) keeps its owners'
  409. terms. Nothing here is investment advice.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.