MarketDeck docs

GNOME Shell plugin

The desktop-overlay plugin that puts a marketdeck panel on the GNOME top bar and renders positions, agents, and notifications.

marketdeck-gnome is the official GNOME Shell extension. It adds a panel to the top bar, a pop-down menu for live mids and open positions, and a set of full-window views (positions, performance, liquidations, http log) — all of it sourced from the same SQLite database and exchange clients the CLI uses.

The plugin is a separate repo (https://git.marketdeck.io/marketdeck/marketdeck-gnome) and is installed through the CLI's plugin loader.

Install#

marketdeck plugin install git:https://git.marketdeck.io/marketdeck/marketdeck-gnome.git
marketdeck gnome install

marketdeck gnome install is a subcommand the plugin registers. It assembles the GNOME extension dir under ~/.local/share/gnome-shell/extensions/marketdeck@clawdy.local/ — plugin files are copied in, and the shared CLI modules (core/, db/, ai/, exchanges/, wallets/, vendor/, bin/, snapshot.js, ai-runtime.js, default-prompt.js, node_modules/) are symlinked from the CLI install root. After install, restart the GNOME Shell:

X11: Alt-F2 → r → Enter.
Wayland: log out and back in.

Then enable the extension via the GNOME Extensions app or the gext / extensions CLI.

Subcommands#

The plugin registers marketdeck gnome <subcommand>:

Subcommand	What it does
`install [--cli-root PATH] [--force]`	Assemble the extension dir. `--force` overwrites an existing install.
`uninstall`	Remove the assembled dir.
`status`	Install state + symlink health (no broken pointers).
`compile-schemas`	Run `glib-compile-schemas` for the gschemas.
`reload`	X11: `gnome-extensions reload`. Wayland: prints the logout hint.

Why symlinks for the shared modules#

marketdeck-gnome install copies the plugin's own files but symlinks the shared CLI modules. That means git pull in the CLI repo updates the live extension immediately — no re-install step needed. The plugin's own files stay copies so a git pull on the plugin doesn't surprise you with mid-session shell-loaded code changes; you re-run marketdeck gnome install --force explicitly when you want those changes live.

Development smoke#

After editing the plugin, reinstall it and re-assemble the GNOME extension dir before testing:

marketdeck plugin update marketdeck-gnome
marketdeck gnome install --force
node test/smoke-gnome.js

The smoke checks the plugin manifest, extension metadata, schemas, JavaScript syntax, CLI-first helper invariants, installed plugin copy, assembled extension files, shared symlinks, and marketdeck gnome status.

What runs in-process#

The GNOME extension hosts several long-lived loops:

The panel tick (live mids, open-position P&L).
The agent scheduler.
The auto-review loop.
The trailing-stop watcher. Real-wallet reads and writes delegate through the CLI data layer so signing and exchange mutation paths stay owned by marketdeck wallets ....

GJS-side code consumes shared read modules through the installed symlinks and sends real-wallet mutations through the CLI.

Secret diagnostics#

GNOME Preferences uses marketdeck secrets ... --format json for credential diagnostics instead of implementing its own inspection logic.

Credential diagnostics shows wallet/OpenRouter/Telegram status from marketdeck secrets doctor.
The Test action runs marketdeck secrets test --scope all.
Export Metadata writes a non-secret JSON file under ~/.cache/marketdeck/.
Rotate Plan creates a manual rotation checklist through marketdeck secrets rotate-plan --scope all.
Real-wallet details show credential status and the safe marketdeck wallets set-secret <wallet> repair command when a credential is missing.
Unset Secret removes a wallet credential only after confirmation via marketdeck secrets unset --scope wallet --ref <wallet> --yes.

No private key, API key, API secret, or Telegram bot token is printed in the preferences UI.