intelligence-terminal/README.md

Crucix

Local intelligence engine. 26 OSINT sources. One command. Zero cloud dependency.

Crucix aggregates open-source intelligence from 26 data sources in parallel — satellite fire detection, flight tracking, radiation monitoring, economic indicators, live market prices, conflict data, sanctions lists, social sentiment, and more — and renders it as a real-time Jarvis-style dashboard that auto-refreshes every 15 minutes.

Everything runs on your machine. No telemetry, no SaaS, no subscriptions required for core functionality.

---

Quick Start

# 1. Clone the repo
git clone https://github.com/YOUR_USERNAME/crucix.git
cd crucix

# 2. Install dependencies (just Express)
npm install

# 3. Copy env template and add your API keys (see below)
cp .env.example .env

# 4. Start the dashboard
npm run dev

The dashboard opens automatically at http://localhost:3117, runs the first intelligence sweep, and auto-refreshes every 15 minutes via SSE (Server-Sent Events). No manual page refresh needed.

Requirements: Node.js 22+ (uses native fetch, top-level await, ESM)

---

What You Get

Live Dashboard

A self-contained Jarvis-style HUD with:

• D3 world map with 7 marker types (fire detections, air traffic, radiation sites, maritime chokepoints, SDR receivers, OSINT events, health alerts, geolocated news)
• Region filters (World, Americas, Europe, Middle East, Asia Pacific, Africa) with smooth zoom transitions
• Live market data — indexes, crypto, energy, commodities via Yahoo Finance (no API key needed)
• Risk gauges — VIX, high-yield spread, supply chain pressure index
• OSINT feed — English-language posts from 12 Telegram intelligence channels
• News ticker — merged RSS + GDELT headlines + Telegram posts, auto-scrolling
• Nuclear watch — real-time radiation readings from Safecast + EPA RadNet
• Leverageable ideas — AI-generated trade ideas (with LLM) or signal-correlated ideas (without)

Auto-Refresh

The server runs a sweep cycle every 15 minutes (configurable). Each cycle:

1. Queries all 26 sources in parallel (~30s)
2. Synthesizes raw data into dashboard format
3. Computes delta from previous run (what changed, escalated, de-escalated)
4. Generates LLM trade ideas (if configured)
5. Evaluates Telegram breaking news alerts (if configured)
6. Pushes update to all connected browsers via SSE

Optional LLM Layer

Connect any of 4 LLM providers for enhanced analysis:

• AI trade ideas — quantitative analyst producing 5-8 actionable ideas citing specific data
• Breaking news alerts — Telegram notifications when critical signals emerge
• Providers: Anthropic Claude, OpenAI, Google Gemini, OpenAI Codex (ChatGPT subscription)
• Graceful fallback — LLM failures never crash the sweep cycle

---

API Keys Setup

Copy .env.example to .env at the project root:

cp .env.example .env

Required for Best Results (all free)

Key	Source	How to Get
FRED_API_KEY	Federal Reserve Economic Data	fred.stlouisfed.org — instant, free
FIRMS_MAP_KEY	NASA FIRMS (satellite fire data)	firms.modaps.eosdis.nasa.gov — instant, free
EIA_API_KEY	US Energy Information Administration	api.eia.gov — instant, free

These three unlock the most valuable economic and satellite data. Each takes about 60 seconds to register.

Optional (enable additional sources)

Key	Source	How to Get
ACLED_EMAIL + ACLED_PASSWORD	Armed conflict event data	acleddata.com/register — free, OAuth2
AISSTREAM_API_KEY	Maritime AIS vessel tracking	aisstream.io — free
ADSB_API_KEY	Unfiltered flight tracking	RapidAPI — ~$10/mo

LLM Provider (optional, for AI-enhanced ideas)

Set LLM_PROVIDER to one of: anthropic, openai, gemini, codex

Provider	Key Required	Default Model
anthropic	LLM_API_KEY	claude-sonnet-4-20250514
openai	LLM_API_KEY	gpt-4o
gemini	LLM_API_KEY	gemini-2.0-flash
codex	None (uses ~/.codex/auth.json)	gpt-5.2-codex

For Codex, run npx @openai/codex login to authenticate via your ChatGPT subscription.

Telegram Alerts (optional, requires LLM)

Key	How to Get
TELEGRAM_BOT_TOKEN	Create via @BotFather on Telegram
TELEGRAM_CHAT_ID	Get via @userinfobot

Without Any Keys

Crucix still works with zero API keys. 18+ sources require no authentication at all. Sources that need keys return structured errors and the rest of the sweep continues normally.

---

Architecture

crucix/
├── server.mjs                 # Express dev server (SSE, auto-refresh, LLM orchestration)
├── crucix.config.mjs          # Configuration with env var overrides
├── .env.example               # All documented env vars
├── package.json               # Single dependency: express
│
├── apis/
│   ├── briefing.mjs           # Master orchestrator — runs all 26 sources in parallel
│   ├── save-briefing.mjs      # CLI: save timestamped + latest.json
│   ├── BRIEFING_PROMPT.md     # Intelligence synthesis protocol
│   ├── BRIEFING_TEMPLATE.md   # Briefing output structure
│   ├── utils/
│   │   ├── fetch.mjs          # safeFetch() — timeout, retries, abort, auto-JSON
│   │   └── env.mjs            # .env loader (no dotenv dependency)
│   └── sources/               # 26 self-contained source modules
│       ├── gdelt.mjs          # Each exports briefing() → structured data
│       ├── fred.mjs           # Can run standalone: node apis/sources/fred.mjs
│       ├── yfinance.mjs       # Yahoo Finance — free live market data
│       └── ...                # 23 more
│
├── dashboard/
│   ├── inject.mjs             # Data synthesis + standalone HTML injection
│   └── public/
│       └── jarvis.html        # Self-contained Jarvis HUD
│
├── lib/
│   ├── llm/                   # LLM abstraction (4 providers, raw fetch, no SDKs)
│   │   ├── provider.mjs       # Base class
│   │   ├── anthropic.mjs      # Claude
│   │   ├── openai.mjs         # GPT
│   │   ├── gemini.mjs         # Gemini
│   │   ├── codex.mjs          # Codex (ChatGPT subscription)
│   │   ├── ideas.mjs          # LLM-powered trade idea generation
│   │   └── index.mjs          # Factory: createLLMProvider()
│   ├── delta/                 # Change tracking between sweeps
│   │   ├── engine.mjs         # Delta computation (new/escalated/de-escalated/removed)
│   │   ├── memory.mjs         # Hot memory (3 runs) + cold storage (daily archives)
│   │   └── index.mjs          # Re-exports
│   └── alerts/
│       └── telegram.mjs       # Breaking news alerts via Telegram
│
└── runs/                      # Runtime data (gitignored)
    ├── latest.json            # Most recent sweep output
    └── memory/                # Delta memory (hot + cold storage)

Design Principles

• Pure ESM — every file is .mjs with explicit imports
• Minimal dependencies — Express is the only runtime dependency. LLM providers use raw fetch(), no SDKs.
• Parallel execution — Promise.allSettled() fires all 26 sources simultaneously
• Graceful degradation — missing keys produce errors, not crashes. LLM failures don't kill sweeps.
• Each source is standalone — run node apis/sources/gdelt.mjs to test any source independently
• Self-contained dashboard — the HTML file works with or without the server

---

Data Sources (26)

Tier 1: Core OSINT & Geopolitical (11)

Source	What It Tracks	Auth
GDELT	Global news events, conflict mapping (100+ languages)	None
OpenSky	Real-time ADS-B flight tracking across 6 hotspot regions	None
NASA FIRMS	Satellite fire/thermal anomaly detection (3hr latency)	Free key
Maritime/AIS	Vessel tracking, dark ships, sanctions evasion	Free key
Safecast	Citizen-science radiation monitoring near 6 nuclear sites	None
ACLED	Armed conflict events: battles, explosions, protests	Free (OAuth2)
ReliefWeb	UN humanitarian crisis tracking	None
WHO	Disease outbreaks and health emergencies	None
OFAC	US Treasury sanctions (SDN list)	None
OpenSanctions	Aggregated global sanctions (30+ sources)	Partial
ADS-B Exchange	Unfiltered flight tracking including military	Paid

Tier 2: Economic & Financial (7)

Source	What It Tracks	Auth
FRED	22 key indicators: yield curve, CPI, VIX, fed funds, M2	Free key
US Treasury	National debt, yields, fiscal data	None
BLS	CPI, unemployment, nonfarm payrolls, PPI	None
EIA	WTI/Brent crude, natural gas, inventories	Free key
GSCPI	NY Fed Global Supply Chain Pressure Index	None
USAspending	Federal spending and defense contracts	None
UN Comtrade	Strategic commodity trade flows between major powers	None

Tier 3: Weather, Environment, Tech, Social, SIGINT (7)

Source	What It Tracks	Auth
NOAA/NWS	Active US weather alerts	None
EPA RadNet	US government radiation monitoring	None
USPTO Patents	Patent filings in 7 strategic tech areas	None
Bluesky	Social sentiment on geopolitical/market topics	None
Reddit	Social sentiment from key subreddits	OAuth
Telegram	12 curated OSINT/conflict channels (web scraping)	None
KiwiSDR	Global HF radio receiver network (~600 receivers)	None

Tier 4: Live Market Data (1)

Source	What It Tracks	Auth
Yahoo Finance	Real-time prices: SPY, QQQ, BTC, Gold, WTI, VIX + 9 more	None

---

npm Scripts

Script	Command	Description
npm run dev	node server.mjs	Start dashboard with auto-refresh
npm run sweep	node apis/briefing.mjs	Run a single sweep, output JSON to stdout
npm run inject	node dashboard/inject.mjs	Inject latest data into static HTML
npm run brief:save	node apis/save-briefing.mjs	Run sweep + save timestamped JSON

---

Configuration

All settings are in .env with sensible defaults:

Variable	Default	Description
PORT	3117	Dashboard server port
REFRESH_INTERVAL_MINUTES	15	Auto-refresh interval
LLM_PROVIDER	disabled	anthropic, openai, gemini, or codex
LLM_API_KEY	—	API key (not needed for codex)
LLM_MODEL	per-provider default	Override model selection
TELEGRAM_BOT_TOKEN	disabled	For breaking news alerts
TELEGRAM_CHAT_ID	—	Your Telegram chat ID

---

API Endpoints

When running npm run dev:

Endpoint	Description
GET /	Jarvis HUD dashboard
GET /api/data	Current synthesized intelligence data (JSON)
GET /api/health	Server status, uptime, source count, LLM status
GET /events	SSE stream for live push updates

---

License

MIT