The Problem

Finance professionals need a fast, keyboard‑driven interface that works both as a native desktop app and as a terminal UI. Existing tools are either heavyweight GUIs or lack the extensibility to run custom commands and plugins from a shell.

What This Does

gloomberb delivers a single code base that powers a macOS/Windows desktop app and a terminal UI (TUI). The UI is built with React‑TSX (src/app.tsx, src/app/pane-runtime/*.tsx) while the command‑line layer lives in src/cli/*.ts. Plugins, market data, and broker integrations are defined under src/brokers/ and src/capabilities/.

Key files:

  • src/cli/index.ts – parses CLI arguments and dispatches to sub‑commands (e.g., market, ticker).
  • src/app.tsx – entry point for the desktop renderer; mounts the React root and wires global shortcuts (src/app/global-shortcuts.ts).
  • src/api-client/*.ts – thin HTTP/WebSocket client used by both UI and CLI to fetch quotes, charts, and news.

The architecture isolates UI code from core logic, allowing scripts to call the same API client without launching a window.

How It Is Wired

Execution starts at the CLI entry point src/cli/entry.ts, which is the binary exported by bin/gloomberb. It loads src/cli/context.ts (environment, config) and then routes to a command module (src/cli/commands/*). Each command ultimately calls the shared API client (src/api-client/request.ts) and, for UI‑related commands, invokes the runtime in src/app/pane-runtime/.

When the desktop app is launched (gloomberb without --json), the process imports src/app.tsx. That file creates the React tree, registers shortcuts from src/app/global-shortcuts.ts, and loads the hub module src/ui/index.tsx. This hub is the most connected piece in the import graph (296 inbound imports) and therefore a high‑blast‑radius location; any change here ripples through most of the code base.

A notable import cycle involves src/ui/index.tsx, src/types/plugin.ts, and src/state/app/context/index.tsx. The cycle appears in 14 files and inflates instability; breaking it (e.g., moving shared types to a neutral module) would reduce coupling.

Data flow: CLI → src/api-client/request.ts → external market APIs → result objects → either printed (src/cli/result.ts) or handed to React components (src/components/chart/*). Broker sync (src/brokers/remote-broker-adapter.ts) follows a similar pattern but writes to a local cache (src/brokers/account-cache.ts).

The build system is driven by Bun (bun.lock, scripts/build.ts) and GitHub Actions (.github/workflows/*.yml). No lockfile for npm is present, so reproducibility relies on the Bun lock.

How To Use It

# Install Bun (if not present)
curl -fsSL https://bun.sh/install | bash

# Install the package globally
bun install -g gloomberb

# Verify the CLI is available
gloomberb --help

Configuration – the project ships an .env.example. Populate a local .env with any required API keys (e.g., ALPHA_VANTAGE_KEY) before running commands that hit external services.

Running the UI – on macOS or Windows the same binary launches the desktop app:

gloomberb          # opens the desktop window
gloomberb launch-ui   # forces UI mode from a script

Running headless commands – get JSON output for automation:

gloomberb market AAPL --json
gloomberb ticker-inspector NVDA --json

The scripts/ folder contains helper scripts (scripts/build-electrobun-view.ts, scripts/release.sh) for developers who need to rebuild the Electron‑based desktop bundle.

Real‑World Use

A quant team can embed gloomberb in a CI pipeline to pull daily price snapshots:

#!/usr/bin/env bash
gloomberb ticker AAPL --json > data/aapl.json
gloomberb ticker MSFT --json >> data/portfolio.json

The JSON files feed downstream risk models without opening a GUI, while analysts on a laptop can launch the full desktop UI for chart exploration.

Code Health & Issues

  • HIGH – Pin GitHub Actions to commit SHAs (.github/workflows/*).
  • HIGH – Pushes go directly to the default branch (release.yml).
  • MEDIUM – No Dependabot/Renovate configuration.
  • MEDIUM – No dependency‑vulnerability scan in CI.
  • MEDIUM – Checkout step keeps credentials; should set persist-credentials: false.
  • LOW – Workflow jobs lack explicit timeout-minutes.

Additional measured findings:

  • 14 files participate in import cycles (e.g., src/ui/index.tsx).
  • Hub module src/ui/index.tsx has 296 inbound imports – a stability hotspot.
  • High branching density in src/utils/format.ts and chart data processors; consider refactoring.

No lockfile for npm is present, making builds non‑reproducible outside of Bun’s lock.

The Bottom Line

gloomberb provides a functional, extensible finance terminal that works both as a desktop app and a TUI, with a clear separation of core logic and UI. The code base is sizable and contains several high‑impact import cycles and hub modules that increase maintenance risk. It is suitable for teams comfortable with TypeScript/Bun and willing to address the highlighted CI and dependency‑management gaps.