Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/l3lackcurtains/trading-ops

πŸ“ˆ Framework-driven trading workspace in Claude Code β€” one slash command scans stocks, crypto, FX, indices & commodities with structured verdicts and audit trails πŸ€–
https://github.com/l3lackcurtains/trading-ops

ai algorithmic-trading claude-code crypto forex stocks technical-analysis trading

Last synced: 23 days ago
JSON representation

πŸ“ˆ Framework-driven trading workspace in Claude Code β€” one slash command scans stocks, crypto, FX, indices & commodities with structured verdicts and audit trails πŸ€–

Awesome Lists containing this project

README 

          


  trading-ops




A systematic trading workspace that runs inside [Claude Code](https://claude.ai/code). One command scans any asset β€” stock, crypto, index, FX, commodity β€” and produces a dated, framework-aligned analysis with structured verdicts, ASCII price ladders, and trade tables. Everything saves as local Markdown: auditable, greppable, version-controlled, and yours.



It is intentionally lean. The framework handles research and structured verdicts β€” execution, alerts, and integrations are left to you. That boundary is deliberate: your trading decisions should stay yours.



The base layer works out of the box. But Claude Code is MCP-native, so the stack is open:



```

+ broker MCP       β†’ place orders directly from a verdict (Alpaca, CCXT / Weex / Binance)

+ Chrome MCP       β†’ auto-pull TradingView charts into every scan

+ Hermes           β†’ run scans 24/7 on a $5 VPS, push alerts to Telegram or Discord

+ Playwright MCP   β†’ scrape any page without an API β€” positions, portals, flow data

+ Slack MCP        β†’ post verdict deltas to a channel the moment a rescan flips

```



Every integration is additive. The research framework stays the anchor; MCPs handle execution and delivery. Add as many or as few as you need.



```

/scan AAPL        β†’ 6-pillar fundamentals + Volume Profile + VWAP + trade plan

/scan BTCUSDT     β†’ F&G + ETF flows + perp funding/OI + liquidation heatmap

/scan SPX         β†’ gamma exposure + VIX term structure + AAII + breadth

/scan EURUSD      β†’ CFTC COT + retail sentiment + rate differentials

/scan-macro       β†’ regime quadrant (Goldilocks / Reflation / Stagflation / Risk-Off)

/discover         β†’ Finviz screener anchored to current macro regime

```



---



## Demo





  trading-ops β€” live scan running in Claude Code




---



## What you get



**Structured verdicts β€” no prose triggers.** Every scan ends with a verb (`LONG` / `SHORT` / `WAIT` / `SKIP` / ...), an ASCII price ladder with every level marked, and a trade table with Entry / Stop / T1 / T2 / T3 / R:R / Sizing / Time-stop:



```

              BTCUSDT  -  2026-04-29  -  spot $76,335

              ==========================================



              UPSIDE  (bull resolution path)

   $84,000   ===   [T2]  heatmap cluster (forced-cover magnet)

   $80,000   ===   [T1]  heatmap density + May 30 max pain

   $79,500         -->   LONG entry  (Swing-B)

   $79,200   ===    ^^   trigger: daily close β‰₯ + green vector

   $78,200   ###         supply zone bottom (3-wk rejection)

   - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

>> $76,335   ***   CURRENT   ***

   $75,500   ===   [t]   Day target / counter-trend entry

   - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

              DOWNSIDE  (bear resolution path)

   $73,800         -->   SHORT entry  (Swing-A)

   $66,000   ===   [T3]  long-dated max pain (Sept/Dec OPEX)

```



**Three horizons per name.** Positional (weeks–months), Swing (3–15 days), Day (intraday). Different verdict per horizon β€” positional auto-reject is compatible with a tradeable swing.



**Audit trail built in.** Every scan is dated and archived. Rescans delta-compare against prior snapshots (`Ξ” since last scan`) and classify prior triggers as `fired-correct / fired-stopped / invalidated / stale`.



**Mostly no API keys required.** Nine Python scripts pre-compute data locally (Yahoo Finance, SEC EDGAR, CoinGecko, alternative.me, Binance, mempool.space, Google News RSS). Optional free keys for FRED macroeconomics and Finnhub analyst data upgrade the output further.



---



## Prerequisites



- **[Claude Code](https://claude.ai/code)** β€” the CLI that runs the slash commands

- **Python 3.10+** β€” for the data pre-compute scripts

- **Free TradingView account** (optional) β€” for chart screenshots via chrome-devtools MCP



No paid data subscriptions required at any tier.



---



## Installation



```bash

git clone https://github.com/YOUR_USERNAME/trading-ops.git

cd trading-ops



python3 -m venv .venv

source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -r requirements.txt

```



Or with [uv](https://github.com/astral-sh/uv) (faster installs, no activation needed):



```bash

git clone https://github.com/YOUR_USERNAME/trading-ops.git

cd trading-ops



uv venv

uv pip install -r requirements.txt

```



Scripts can then be run directly without activating the venv:



```bash

uv run python scripts/fetch_quote.py AAPL

uv run python scripts/fetch_ohlc.py BTCUSDT

```



Or with npm (installs venv, dependencies, and the pre-commit hook in one step):



```bash

npm run setup

```



Then open the folder in Claude Code:



```bash

claude .

```



The slash commands are immediately available. Start with:



```

/scan-macro

```



---



## Optional API keys



Set these as environment variables (e.g. in `~/.bashrc` or a `.env`):



| Variable | Source | What it unlocks |

|---|---|---|

| `FRED_API_KEY` | [fredaccount.stlouisfed.org/apikeys](https://fredaccount.stlouisfed.org/apikeys) (free) | Full macro data via `fetch_macro.py` β€” replaces ~6 WebFetches per `/scan-macro` |

| `FINNHUB_TOKEN` | [finnhub.io/register](https://finnhub.io/register) (free, 60 req/min) | Analyst price targets, recommendations, earnings AMC/BMO timing |

| `SEC_USER_AGENT` | Any string: `"Name "` | SEC EDGAR fair-access policy for `fetch_sec.py` β€” Form 4 insider data + ROIC from XBRL |



Everything works without keys. The keys are upgrades.



---



## Quick start (first 5 minutes)



**1. Set the macro regime.**

```

/scan-macro

```

Pulls rates, curve, CPI, PCE, NFP, DXY, VIX. Places the market in one of four quadrants (Goldilocks / Reflation / Stagflation / Risk-Off). Saves to `scanned/MACRO/current.md`. Run this first β€” the regime gates every downstream verdict.



**2. Scan a ticker.**

```

/scan AAPL

```

Auto-detects asset class (stock β†’ 6-pillar + Volume Profile + VWAP + ChartExchange flow). Saves to `scanned/stocks/AAPL/current.md`. For crypto, FX, indices, or commodities β€” same command, different symbol.



**3. Find new names.**

```

/discover

```

Parses your intent into Finviz filters, anchors to the current regime, saves a candidate list to `scanned/SCREENS/`. Then `/scan ` on anything promising.



**4. Rescan when things move.**

```

/rescan AAPL

```

Rotates the prior snapshot to `archive/`, pulls fresh data, marks the TL;DR with `Ξ”` if the verdict changed.



---



## All commands



| Command | What it does |

|---|---|

| `/scan-macro` | Top-down regime read. Sets the quadrant for all downstream scans. |

| `/scan [SYMBOL]` | Universal scan β€” auto-detects stock / crypto / index / FX / commodity. No args = regenerate `scanned/INDEX.md`. |

| `/rescan SYMBOL\|macro` | Full refresh β€” rotate archive, pull fresh data, mark deltas. |

| `/scan-flow SYMBOL` | Partial: refresh asset-class flow & positioning only (COT / ETF / gamma). |

| `/scan-fundamentals TICKER` | Partial: refresh 6-pillar scorecard only (stocks). Run after new 10-Q / 13F. |

| `/scan-earnings TICKER` | Partial: earnings setup 8-point checklist. Run 4–6 weeks pre-print. |

| `/discover [intent]` | Finviz screener. Natural language: `/discover cheap semis with ROI > 20`. |

| `/ingest source` | Add new framework knowledge to `docs/`. PDF / URL / inline text. |

| `/calibrate [scope]` | Audit `guide/` against `docs/` for drift. |



### Asset-class auto-detection



| Symbol shape | Routed as | Extra data |

|---|---|---|

| 1–5 letter US ticker | Stock | 6-pillar + ChartExchange + earnings |

| ends in `USDT`/`USD` | Crypto | F&G + ETF + perp funding/OI + max pain + heatmap |

| `SPX` / `NDX` / `SPY` / `QQQ` | Index | Gamma + VIX structure + AAII + breadth + COT |

| 6-letter pair (`EURUSD`) | FX | CFTC COT + retail sentiment + rate diffs |

| `CL` / `GC` / `USO` / `GLD` | Commodity | COT + EIA/USDA + curve + seasonality |



Override ambiguous cases: `/scan MSTR --type=crypto`



---



## Folder layout



```

trading-ops/

β”œβ”€β”€ docs/                    ← framework knowledge base (read-only)

β”‚   β”œβ”€β”€ macro.md             ← 4-regime model, key indicators, news-trading playbook

β”‚   β”œβ”€β”€ long-term-investing.md  ← 6-pillar fundamentals, moat types, 10-K reading

β”‚   β”œβ”€β”€ positioning.md       ← squeeze tier, dealer gamma, CFTC COT

β”‚   β”œβ”€β”€ volume-profile.md    ← POC / VAH / VAL / HVN / LVN, profile shapes

β”‚   └── vwap.md              ← session / weekly / monthly / quarterly / anchored VWAP

β”œβ”€β”€ guide/                   ← scan protocol (read-only during scans)

β”‚   β”œβ”€β”€ scan-rules.md        ← index into guide/scan/

β”‚   └── scan/                ← per-concern protocol files

β”œβ”€β”€ .claude/commands/        ← slash command definitions

β”œβ”€β”€ scripts/                 ← Python data-fetch utilities

β”œβ”€β”€ scanned/                 ← living analyses β€” your trading desk

β”‚   β”œβ”€β”€ INDEX.md             ← auto-generated coverage navigator

β”‚   β”œβ”€β”€ MACRO/               ← regime tracker

β”‚   β”œβ”€β”€ stocks//     ← per-stock coverage (current.md + archive/)

β”‚   β”œβ”€β”€ crypto//

β”‚   β”œβ”€β”€ indices//

β”‚   β”œβ”€β”€ fx//

β”‚   └── commodities//

└── requirements.txt

```



`docs/` and `guide/` are read-only during scans β€” the framework is enforced, not improvised. `/ingest` is the only command that writes to `docs/`. `/calibrate` audits `guide/` for drift against the knowledge base.



---



## Python scripts



The scripts replace WebFetches with local pre-computation. All keyless by default; optional keys shown in parentheses:



| Script | What it pre-computes |

|---|---|

| `fetch_quote.py TICKER` | Yahoo Finance quote β€” price, valuation, profitability, growth, balance sheet, short interest, analyst consensus. Includes Pillar-1 numeric auto-reject check. |

| `fetch_ohlc.py TICKER` | Multi-timeframe OHLCV + EMAs (20/50/200) + ATR + RSI + VWAP family (session/weekly/monthly/quarterly/anchored, Β±Οƒ bands) + Volume Profile (POC/VAH/VAL/HVN/LVN + ASCII histogram). |

| `fetch_sec.py TICKER` | SEC EDGAR Form 4 insider transactions, cluster detection, ROIC from XBRL company facts. Requires `SEC_USER_AGENT`. |

| `fetch_max_pain.py TICKER` | Options max pain across next N OPEX dates from yfinance options chain. |

| `fetch_macro.py` | FRED macro gauges + Treasury yield curve. Requires `FRED_API_KEY`. |

| `fetch_crypto.py SYMBOL` | CoinGecko + alternative.me F&G + Binance klines + mempool.space + DeFiLlama. |

| `fetch_news.py SYMBOL` | Google News RSS (keyless) + Finviz widget + optional Finnhub analyst data (`FINNHUB_TOKEN`). |

| `regen_index.py` | Regenerate `scanned/INDEX.md` from every `current.md`. |

| `prune_archive.py [--apply]` | Retention policy β€” keep latest per month, drop >12 months. Dry-run by default. |

| `validate_links.py` | Project-wide markdown link audit. Exits non-zero on broken links. |

| `validate_tiers.py` | Lint coverage tier syntax across all `current.md` files. |



Run any script with `--help` for full options. Use `.venv/bin/python scripts/.py` if the venv is not activated.



---



## Coverage tiers



Every scan tags one tier per horizon (Pos / Swing / Day). `INDEX.md` rolls them up:



| Tier | Meaning |

|---|---|

| **T** β€” Top Pick | Full conviction, deploy on next trigger |

| **W** β€” Watchlist | Live trigger spec ready, act when conditions hit |

| **B** β€” Bench | Followed but no near-term trigger |

| **S** β€” Skip | Auto-reject or hostile setup |

| **X** β€” Dropped | Removed from coverage |



A name's verdict can differ by horizon β€” positional S is compatible with a swing W around a catalyst.



---



## The framework (in `docs/`)



All scans draw from four documents in `docs/`. They are read-only during scans β€” the framework is the anchor.



- **`macro.md`** β€” Four growth Γ— inflation quadrants (Goldilocks / Reflation / Stagflation / Risk-Off), key indicators, FOMC/CPI/NFP news-trading playbook, bubble indicators.

- **`long-term-investing.md`** β€” 6-pillar scorecard (Quality / Growth / Valuation / Balance Sheet / Capital Allocation / Smart Money), moat types, how to read a 10-K, capital allocation discipline.

- **`volume-profile.md`** β€” POC / VAH / VAL / HVN / LVN, profile shapes (D / P / b / B / multi-modal), naked POCs as forward targets. The backbone of the technical read.

- **`vwap.md`** β€” Session / weekly / monthly / quarterly / anchored VWAP, Β±1Οƒ / Β±2Οƒ bands, reclaim / lose patterns. The second leg of the technical core.



Add new knowledge via `/ingest`. The command shows a write plan and waits for consent before touching `docs/`.



---



## Extending the framework



**New framework knowledge** (new indicator, new macro model, new positioning concept):

```

/ingest input/new-paper.pdf

/ingest "Add dealer delta positioning section to macro.md"

```



**Protocol improvements** (better source priority, new data source, fixed filter code): handled by the self-improvement loop β€” Claude surfaces suggestions at the end of every scan and waits for your consent before editing `guide/` or `.claude/commands/`.



**New asset class or data source**: add a `guide/scan/<class>-flow.md` file following the pattern of the existing flow docs, then run `/calibrate` to sync.



---



## Extending with MCPs



Claude Code is MCP-native. Any MCP server you add to `~/.claude/claude.json` (global) or `.claude/settings.json` (project) is immediately available inside every slash command and freeform session. The possibilities are essentially unbounded β€” here are the ones that slot most naturally into this workspace.



### Broker integration



Wire up order execution so Claude can place, size, and cancel orders directly from a scan verdict.



**Alpaca** (stocks, commission-free):

```json

// ~/.claude/claude.json β†’ mcpServers

"alpaca": {

  "command": "npx",

  "args": ["-y", "@alpacahq/alpaca-mcp"],

  "env": {

    "ALPACA_API_KEY": "your-key",

    "ALPACA_API_SECRET": "your-secret",

    "ALPACA_BASE_URL": "https://paper-api.alpaca.markets"

  }

}

```



After adding it, `/scan AAPL` ends with a trade table β€” then you ask Claude: *"Place the Swing-B entry as a limit order, 50% size."* Claude calls the broker MCP, confirms fill, logs it.



**Weex / Binance** (crypto perpetuals and spot):



Crypto exchanges expose REST + WebSocket APIs with HMAC-signed requests. Wire them up through any HTTP MCP that handles auth signing, or use a thin community wrapper:



```json

"weex": {

  "command": "npx",

  "args": ["-y", "mcp-server-ccxt"],

  "env": {

    "EXCHANGE": "weex",

    "API_KEY": "your-key",

    "API_SECRET": "your-secret"

  }

}

```



[CCXT](https://github.com/ccxt/ccxt) covers 100+ exchanges under a unified interface β€” swap `"weex"` for `"binance"`, `"bybit"`, `"okx"`, or any other supported exchange without changing anything else.



Other brokers with community MCPs: Interactive Brokers, Tradovate. Search `mcp <broker name>` on GitHub or the MCP registry.



### TradingView charts via Chrome DevTools MCP



The Chrome DevTools MCP is listed in Prerequisites because chart screenshots plug directly into scan output β€” Claude opens TradingView, navigates to the symbol, screenshots the chart, and embeds it in `scanned/stocks/<TICKER>/charts/`.



```json

"chrome-devtools": {

  "command": "npx",

  "args": ["-y", "@modelcontextprotocol/server-chrome-devtools"],

  "env": { "CHROME_PATH": "/usr/bin/google-chrome" }

}

```



Then from a scan: *"Pull a daily chart for NVDA with 20/50/200 EMAs and save it."* Claude navigates TradingView, applies the layout, screenshots, saves. No manual steps.



You can extend this further β€” monitor an open TradingView alert panel and have Claude notify you when a level fires, or read DOM-level order book data from exchange web UIs.



### Browser automation MCP



A Playwright or Puppeteer MCP opens the rest of the web to the scan pipeline β€” pages that don't have APIs, paywalled data sources, broker web portals.



```json

"playwright": {

  "command": "npx",

  "args": ["-y", "@executeautomation/playwright-mcp-server"]

}

```



Example use: scrape a brokerage account's positions page, reconcile against open scan verdicts, flag anything that drifted outside its stop.



### Notification MCP (Slack / Discord / Telegram)



Get alerted when a rescan flips a verdict from W β†’ T or fires a trigger.



```json

"slack": {

  "command": "npx",

  "args": ["-y", "@modelcontextprotocol/server-slack"],

  "env": { "SLACK_BOT_TOKEN": "xoxb-..." }

}

```



After a `/rescan AAPL`, if the verdict changed: *"Post the delta summary to #trading-alerts."*



### The pattern



Every MCP extends what Claude can *do* inside this workspace β€” but the research framework, verdicts, and levels stay anchored to `docs/` and `guide/`. MCPs handle the last mile (execute, alert, visualize) while the framework handles the thinking. Add as many or as few as you need.



---



## npm shortcuts



A `package.json` is included for common maintenance tasks. No Node dependencies β€” just script aliases.



| Command | What it does |

|---|---|

| `npm run setup` | Create venv, install Python deps, install pre-commit hook |

| `npm run hook` | Install pre-commit hook only |

| `npm run validate` | Run link audit + tier syntax linter |

| `npm run index` | Regenerate `scanned/INDEX.md` |

| `npm run prune` | Dry-run archive retention policy |

| `npm run prune:apply` | Apply retention policy (deletes old snapshots) |



---



## Automating with Claude routines



Claude Code has a `/schedule` command that runs any slash command as a recurring background agent β€” no cron setup, no server. Useful for keeping the workspace fresh without manual effort.



```

/schedule "run /scan-macro every Monday at 8am ET"

/schedule "run /rescan BTCUSDT every day at 6am ET"

/schedule "run /discover every Sunday at 7pm ET"

```



Each routine runs independently, saves output to the normal `scanned/` paths, and respects the same framework rules as a manual scan. You can list, pause, or delete routines with `/schedule list` and `/schedule delete`.



**Practical setups:**



- **Weekly regime refresh** β€” schedule `/scan-macro` Monday premarket. Every downstream scan that week reads a fresh regime.

- **Watchlist maintenance** β€” schedule `/rescan` on your open positions daily. The delta markers (`Ξ”`) flag anything that moved.

- **Screen rotation** β€” schedule `/discover` weekly on Sunday. Monday morning you have a fresh candidate list anchored to the new regime.

- **Earnings pipeline** β€” schedule `/scan-earnings TICKER` a month out from print date. The checklist is waiting when you need it.



Routines don't replace judgment β€” they make sure the data is there when you sit down to make a decision.



### Server-side automation with Hermes



Claude routines require the Claude Code desktop app to be running. If you want the same workflows running 24/7 on a VPS β€” and delivered to your phone via Telegram, Discord, or Slack β€” [Hermes](https://github.com/nousresearch/hermes-agent) is the natural complement.



Hermes is an open-source autonomous agent framework (Nous Research) with a built-in cron scheduler, MCP support, and messaging-platform bridges. It runs on a $5 VPS and supports 200+ models.



**Install:**

```bash

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

source ~/.bashrc

hermes setup          # configure model + messaging platform

```



**Schedule the same workflows:**

```bash

# weekly macro refresh β€” Monday 8am

hermes cron add "0 8 * * 1" "claude --print '/scan-macro'"



# daily watchlist rescan β€” 6am weekdays

hermes cron add "0 6 * * 1-5" "claude --print '/rescan BTCUSDT'"



# weekly screen β€” Sunday 7pm

hermes cron add "0 19 * * 0" "claude --print '/discover'"

```



Results save to `scanned/` exactly as they would from a manual run. Hermes forwards a summary to your configured Telegram or Discord channel β€” you wake up to a fresh regime read and any verdict deltas, no laptop required.



**With MCP:** If you wire this workspace's tools into Hermes as an MCP server, Hermes can also trigger scans conversationally β€” ask it from your phone and get the full scan output back in the chat.



---



## Pre-commit validation



A git hook runs `validate_links.py` and `validate_tiers.py` on every staged markdown commit. Install with:



```bash

npm run hook

```



---



## Rules in four bullets



1. **`docs/` is read-only.** `/ingest` is the only writer. Never modify during a scan.

2. **Read before you scan.** Every command loads `current.md`, recent archives, and `MACRO/current.md` first.

3. **Cite numbers, not vibes.** Every claim that drives a verdict gets a markdown link. ROIC -38.6% beats "ROIC is poor."

4. **Action verdicts are structured, not prose.** Verbs from a fixed list, ASCII ladder for levels, trade table for triggers / stops / targets / R:R / sizing.



---



## License



MIT β€” do whatever you want with it, including adding your own framework docs and protocols.