Getting started.

Kairos is a local desktop app — Python/FastAPI backend, React/TypeScript frontend, Electron renderer. Clone, install, run ./start.sh, done. First run boots the backend, opens the Terminal workspace, and begins caching market data to data/terminal.duckdb.

• macOS (Darwin 25+) — Intel and Apple Silicon tested, with native fullscreen support.
• Python 3.13 at /usr/local/bin/python3 (Homebrew) or /Library/Frameworks/Python.framework/Versions/3.13/bin/python3.
• Node.js 20+ and npm for the React frontend.
• Optional — Interactive Brokers Gateway on 127.0.0.1:7497 for future trading connectors.

From the repo root, install dependencies and start the app:

On first run, data sources auto-connect — yFinance is always available (15-min delayed); dxFeed activates if keyed for futures and Level 2. The default Terminal workspace opens with watchlist, chart, and analysis tabs.

All cached state — bars, ticks, options chains, journal entries, watchlists, workspace layouts — persists to data/terminal.duckdb. DuckDB is columnar and serverless, so the file is self-contained. Back it up by copying the file.

Interface overview.

Kairos uses a workspace + panel model built on Dockview. Each workspace is a persistent, named arrangement of resizable panels. The default Terminal workspace has a watchlist sidebar, a center chart area, and tabbed analysis panels at the bottom. Drag any tab out to tear it into an independent Electron window — panels snap back on drop.

• Workspaces — persistent Dockview layouts (Terminal, Research, Market, Options, or multi-chart grids with 2/4/6/8/12/16 charts). Each workspace is a tab; state auto-saves.
• Panels — 47 reusable UI modules. Chart, Watchlist, Journal, Options Chain, Backtester, News, Macro, and more. Drag to resize or pop out; search via Command Palette.
• Link Groups (A–F) — symbol routing. Change the symbol in one linked panel and all others in the group update. Visible as a pill on each tab.
• Multi-window — tear off any tab into an independent Electron window. Each window has its own Dockview state and persists across restarts.

Press ⌘ K (macOS) or Ctrl K (Windows / Linux) to open the command palette. It searches across tickers, panels, and workspaces. Type a symbol to navigate to Research; type a panel name (e.g. chart, journal, macro) to insert it into the active workspace.

Chart view.

Real-time candlestick charts on TradingView lightweight-charts v5 — 60 fps even with hundreds of thousands of bars. Live ticks update the rightmost candle in place. Bars are cached in DuckDB; re-downloads only fill gaps in your local store.

• UI timeframes: 1m, 5m, 15m, 1h, 4h, 1d, 1w.
• Custom intervals: any OHLCV interval is storable via the backend API.
• Live updates: ticks stream over WebSocket; the current candle updates without redraw lag.
• Storage: all bars cached in data/terminal.duckdb; re-downloads only fill gaps.

Indicators overlay the chart as colored lines, computed via pandas-ta or hand-rolled numpy fallback for speed.

• EMA 9 / EMA 21
• SMA 20 / SMA 50
• Bollinger Bands (BB)
• VWAP
• RSI
• MACD

Gamma exposure per strike is plotted as horizontal price levels derived from the options chain. Use these to locate dealer flip zones and significant gamma-driven support / resistance bands directly on the chart.

Order flow.

Orderflow consists of three pieces: footprint candles (bid/ask volume at each price level within a candle), a cumulative volume delta line tracking aggressor pressure, and a planned DOM heatmap. Footprint is computed server-side from tick data and cached; live ticks update the current candle in real time.

• Customizable timeframe — bid/ask volume split at each price level inside each bar.
• Custom canvas rendering for high performance on dense intraday data.
• Color logic: cells colored by delta (green = ask-side volume, red = bid-side volume).
• Auto tick size: ES / NQ = 0.25, RTY = 0.10, YM = 1.0; custom tick sizes configurable per instrument.

The cumulative volume delta line tracks net buy/sell pressure (ask-trade volume minus bid-trade volume, running total). Rendered alongside the chart, it shows whether each move is being absorbed or confirmed by aggressors.

Options chain.

The Options workspace shows a full chain with calls, puts, strikes, expiries, and Greeks. The left rail has 12 sections covering MenthorQ dealer levels, GEX, dealer flows, IV surface and skew, max pain and OPEX dates, and per-strike heatmaps. Chain data caches with a 15-min refresh during RTH and 24-hour after-hours.

Configurable columns on the chain table:

• strike
• call bid / ask, volume / OI
• call delta / gamma / theta / vega
• put bid / ask, volume / OI
• put delta / gamma / theta / vega
• IV, GEX regime

• delta, gamma, theta, vega, rho — first-order standard.
• vanna (∂Δ/∂σ) — delta sensitivity to vol changes.
• charm (∂Δ/∂t) — delta decay over time.
• Vectorized for 500-row chains in milliseconds.

• GEX — gamma exposure per strike.
• PCR — put/call ratio, both OI-weighted and volume-weighted.
• DEX — net dealer delta in $ notional.
• VEX — $ vanna per 1 vol point.
• CEX — $ charm per day.

The journal.

A six-tab trade logging system. Manual entry, NinjaTrader CSV import, and (post-v1) auto-journaling from broker fills. All data persists to DuckDB. The killer feature: click any trade row or calendar day and re-watch the chart between entry and exit.

• Dashboard — cumulative P&L, win rate, equity curve.
• Trades — filterable log with entry / exit price, size, commission, profit, date, tags, notes.
• Daily Notes — freeform per-day journal with a 1–10 self-grade.
• Calendar — heatmap of daily P&L; click a day to open the Replay modal.
• Reports — aggregate by symbol, tag, day-of-week, hour-of-day.
• Playbook — saved trade setups: entry signal, exit rule, risk rule, notes.

The Trade form takes entry price, exit price, size, commission, tags, and notes — posted to the backend via the form modal. Tags drive the Reports rollups.

Bulk-upload historical trades from NinjaTrader CSV via the nt_import service. Useful for backfilling years of execution history before adopting Kairos as a daily journal.

Click any trade row or calendar day to load the Replay modal. It renders the chart between entry and exit candle with annotations — the single most useful review tool in the journal.

Keyboard shortcuts.

Navigation is intentionally simple in v1 — most flows route through the command palette. Custom chord bindings via settings.json are planned but not yet wired.

API reference.

The backend is a FastAPI app exposing ~147 REST endpoints across 18 routers, mounted at /api/<router>/<endpoint>. A single WebSocket at /ws carries live data (prices, bars, alerts, bot stats, news). No auth in v1 — Kairos is a local single-user app.

• /api/charts/ — bars, indicators, footprint, quote
• /api/options/ — chain, GEX, PCR, DEX, vol, structure
• /api/research/ — fundamentals, peers, screening (32 endpoints)
• /api/journal/ — CRUD on trades, playbooks, notes (22 endpoints)
• /api/watchlist/, /api/backtest/, /api/strategies/, /api/bots/, /api/alerts/
• /api/news/, /api/macro/, /api/market/, /api/calendar/, /api/etf/
• /api/search/, /api/data_feed/

Single connection at /ws. Subscribe to event types:

• PRICE_UPDATE — live last-trade ticks
• BAR_UPDATE — bar close / update for the current candle
• ALERT_TRIGGERED — fired when an alert condition is met
• BOT_STAT — per-bot performance updates
• NEWS_UPDATE — newly ingested news items