Omahub
← All plugins
G

Cloud SQL Tracker

by golgor

Bar dropdown to start, stop, and monitor Google Cloud SQL Auth Proxy connections via the cloud-sql-tracker CLI. Summon with: omarchy-shell shell toggle io.github.golgor.cloud-sql-tracker

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
d1941a0
Scanned
3 weeks ago

No potentially dangerous behavior detected in the analyzed commit.

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
d1941a0
Reviewed
3 weeks ago

The plugin is a well-structured bar widget that only shells out to a fixed set of cloud-sql-tracker CLI commands, with no file I/O or destructive operations. The deterministic scan found no issues, and the code review confirms the plugin adheres to its documented contract, with all process execution confined to Tracker.qml and proper input validation. The only minor concern is the use of a shell wrapper for output capping, which is documented and does not introduce additional commands.

  • The plugin relies on an external CLI (cloud-sql-tracker) which is not part of this repository; users must trust that CLI's behavior, but the plugin itself does not execute arbitrary commands.
  • The shell wrapper used for output capping (via head -c) is a potential injection point if the CLI path or arguments are not properly sanitized, but the code validates cliPath and uses fixed argv, mitigating this risk.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/golgor/cloud-sql-tracker-oma-plugin --enable
Developer Tools #bar #quickshell #system

cloud-sql-tracker-oma-plugin

A fast, keyboard-first Omarchy bar widget to monitor and control your Google Cloud SQL Auth Proxies at a glance.

Toggle database proxies individually, spin up entire environment groups (backend, frontend, staging), or hit emergency Stop all — directly from your status bar without context-switching to terminal windows.

Powered by the external cloud-sql-tracker control plane CLI.

Status

v1.0 Stable. Features house-style grouped list UI, live status polling, environment group actions, setup preflight, and full keyboard navigation (j/k, Enter, h/l). Recommends CLI ≥ 0.1.1 for disabled-connection labeling (backward-compatible with older CLI versions).
Plugin id io.github.golgor.cloud-sql-tracker
How it works docs/how-it-works.md
Module seams docs/modules.md
Design / chrome docs/DESIGN.md, docs/chrome.md
Agent notes AGENTS.md
Language CONTEXT.md
Control plane golgor/cloud-sql-tracker

Requirements

  • Omarchy with omarchy plugin support
  • cloud-sql-tracker on your PATH (or set cliPath in plugin settings — an absolute path or a bare command name; a relative path like ./tracker is rejected)
  • Configured ~/.config/cloud-sql-tracker/connections.json (see CLI repo examples)
  • cloud-sql-proxy + GCP ADC set up for the proxy itself

Install

# Install from git and enable on the bar
omarchy plugin add https://github.com/golgor/cloud-sql-tracker-oma-plugin.git --enable

Place Cloud SQL Tracker on the bar (category Development), or add it in ~/.config/omarchy/shell.json.

Removal

# Remove an installed plugin
omarchy plugin remove io.github.golgor.cloud-sql-tracker

Validate a local checkout:

omarchy plugin validate ~/Code/Personal/cloud-sql-tracker-oma-plugin

Keyboard

The panel is fully drivable without a mouse once open: j/k walk rows across group boundaries, Enter toggles whatever the cursor is on, h/l are the explicit stop/start verbs for a connection or a whole group, Esc closes, and Tab switches to the neighbouring bar panel.

To summon it with a hotkey, add a binding to ~/.config/hypr/bindings.lua:

o.bind("SUPER + CTRL + Q", "Cloud SQL Tracker",
  "omarchy-shell shell toggle io.github.golgor.cloud-sql-tracker")

If that combination is already taken, hl.unbind("SUPER + CTRL + Q") on the line before releases it first — check with omarchy menu keybindings --print.

Omarchy's built-in SUPER + CTRL + <n> also toggles the nth panel in the bar's right section, which may already reach this one; a named binding is preferred because the numbered form is positional and follows bar order.

Local development

For working on this plugin itself, symlink this checkout into Omarchy's plugin directory instead of using omarchy plugin add (which clones a copy):

./scripts/dev-link

This symlinks ~/.config/omarchy/plugins/io.github.golgor.cloud-sql-tracker to this checkout, runs omarchy plugin validate, rescans plugins, and enables the widget (default bar section: right). Safe to re-run.

Saved edits do not hot-reload. The shell watches its own config path, not a symlinked plugin directory, so QML changes under this checkout are picked up only after:

omarchy restart shell

The symlink still saves you re-cloning on every change — it is the copy step that goes away, not the reload step.

./scripts/dev-link --help              # options
./scripts/dev-link --section left      # place elsewhere
./scripts/dev-link --no-enable         # link + validate only
node scripts/check-model.js            # Model.js + fixtures (no QML runtime)
bash scripts/check-qml-seams.sh        # static Tracker/Process seam gate
bash scripts/check-process-seam.sh     # Quickshell fake-CLI flood/timeout gate

check-process-seam.sh runs a throwaway Quickshell harness with a fake Control plane. It uses QT_QPA_PLATFORM=offscreen, writes artifacts under .test-artifacts/process-seam/, and fails when quickshell is missing.

It never deletes a real plugin directory: if something other than a symlink to this checkout already occupies that path, it fails with no changes made.

Unlink:

rm ~/.config/omarchy/plugins/io.github.golgor.cloud-sql-tracker
omarchy plugin disable io.github.golgor.cloud-sql-tracker   # optional

omarchy plugin add <git-url> (above) remains the non-dev install path for everyone else — it clones its own copy rather than tracking a local checkout.

Agent workflow (branch, PR, seams, contract): AGENTS.md.

Contract

The plugin only shells out to:

cloud-sql-tracker --version
cloud-sql-tracker status --json
cloud-sql-tracker doctor --json   # once when the panel opens
cloud-sql-tracker start <id|--group=G|--group G|--all>
cloud-sql-tracker stop  <id|--group=G|--group G|--all>

Tracker may execute those argv through a local shell cap wrapper so stdout and stderr are bounded before QML buffers them. The wrapper does not add Control plane commands. It passes ids and Group names as data argv.

It does not read or write the connections config file. Doctor hard-fail hides the connection list (setup unusable). Per-connection start failures show on the row after setup passes.

Disabled Connections (enabled: false in config, exposed on Status) stay visible in the panel but are not start targets. Bar and group counts use enabled Connections only.

License

MIT