Omahub
← All plugins
C

Chordarchy

by ctl0v0

Map Omarchy shortcuts and commands to chords played on a physical MIDI keyboard, with a warm synth and live grand staff.

GitHub

Security review

Review recommended · 1 finding

Deterministic scan — not a security guarantee

Low
Risk level
Low
Analyzed commit
8a8c739
Scanned
1 month ago

Flagged patterns appear only in documentation files (README / docs) — descriptive examples, not executable code.

  • Docs external_hosts CONTRIBUTING.md:10

    Downloads or connects to an external HTTP(S) host.

    git clone https://github.com/ctl0v0/chordarchy.git ~/.config/omarchy/plugins/io.github.ctl0v0.chordarchy

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
8a8c739
Reviewed
1 month ago

Chordarchy is a well-structured MIDI-to-shortcut mapper for Omarchy. The code is clean, well-tested, and transparent about its security model. The only deterministic finding is a `git clone` command in CONTRIBUTING.md, which is documentation only and not part of the executable code. The plugin does execute commands, but only those explicitly mapped by the user, and it includes safety features like confirmation prompts and an armed/disarmed state.

  • The plugin can execute arbitrary commands mapped to MIDI chords, but this is the core documented functionality and requires explicit user configuration.
  • The Python backend runs unsandboxed with user privileges, but this is standard for Omarchy plugins and clearly documented in the README and SECURITY.md.
  • The `git clone` in CONTRIBUTING.md is flagged as an external host connection, but it is purely illustrative documentation and not executed by the plugin.
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/ctl0v0/chordarchy --enable
Productivity #bar #quickshell #media

Chordarchy

"Play your desktop" means mapping Omarchy shortcuts and commands to chords played on a physical MIDI keyboard. Play and release a chord to launch an app, switch workspaces, control media, open an Omarchy menu, or trigger another mapped desktop action. Chordarchy also renders held and sustained notes on a live grand staff and plays a warm velocity-sensitive tone.

The built-in 49-key piano makes the mapping workflow easy to explore without MIDI hardware. On-screen previews and Practice are command-safe; a MIDI controller is required for live chord-command performance.

<p align="center"> <img src="preview.png" alt="Chordarchy on the Omarchy desktop with a live C minor grand staff, mapped setlist, and on-screen piano"> </p>

Demo

Watch Chordarchy trigger mapped Omarchy shortcuts from a physical MIDI keyboard on X.

Features

  • Chord recognition by pitch class, including inversions and octave changes.
  • Release-based gestures that wait for the complete chord before acting.
  • Theme-aware grand staff with held, sustained, and target notes.
  • Low-latency PipeWire synthesizer with velocity response and a soft limiter.
  • Guided mapping for 47 common Omarchy actions and native shortcuts.
  • Full-width on-screen piano for chord selection and safe audio preview.
  • Compact live setlist built from hearted mappings.
  • Command-safe Practice with named chord tones and staff targets.
  • Persistent mappings, chord suggestions, MIDI selection, volume, and staff profile.
  • Confirmation protection for sensitive actions.

Requirements

  • Omarchy with the Quattro plugin system.
  • Python 3.
  • alsa-utils, which provides aseqdump for MIDI input.
  • PipeWire tools, which provide pw-cat for audio output.
  • An ALSA sequencer-compatible MIDI controller for live command performance. USB and Bluetooth controllers are supported when exposed through ALSA.

These runtime tools are included in a standard Omarchy installation. Chordarchy has no build step and no third-party Python or Node packages.

Install

Review the source, then install and enable the plugin:

omarchy plugin add https://github.com/ctl0v0/chordarchy.git --enable

Chordarchy appears in the right section of the Omarchy bar. Plugins run as unsandboxed user code inside omarchy-shell; install only source you are willing to run.

Update an existing installation with:

omarchy plugin update io.github.ctl0v0.chordarchy

Quick start

  1. Click the Chordarchy bar icon, then open Studio with the cog.
  2. Open Mappings.
  3. Click at least three notes on the on-screen piano and choose USE CHORD, or select LEARN A NEW CHORD and play it on MIDI.
  4. Filter or browse Available Key Bindings, then click one to create the mapping.
  5. Heart the mapping to include it in the compact live setlist.
  6. Keep commands armed, then play and release that chord on your MIDI controller.

Available Chords shows three suggestions at a time and scrolls independently. Mapped Chords remains visible below it and has its own scrollable list.

Safety and behavior

  • Commands start armed on each shell launch and can be disarmed independently from note recognition.
  • Sound starts enabled at the saved volume and can be muted independently from commands.
  • On-screen previews, setlist previews, Studio demos, and Practice never execute mapped desktop actions.
  • Opening Practice disarms commands. Leaving Practice keeps them disarmed until explicitly re-armed.
  • Confirmation actions must be played twice within three seconds.
  • The first note release freezes the complete gesture, preventing a triad from firing while a seventh chord is still being formed.
  • Sustain affects the synthesizer and staff but is excluded from command matching.
  • Built-in actions and custom commands are launched as argument arrays without a shell.

See SECURITY.md for the trust model and private vulnerability reporting.

Controls

  • Left-click the bar widget to open the compact performance panel.
  • Right-click the bar widget to mute or unmute Chordarchy sound.
  • Click a compact setlist row to preview that chord one octave higher.
  • Use the compact-panel cog to open the detached Studio.
  • In Studio, use M for sound, A for command arming, D for a safe demo, P for panic, and Escape to close.
  • In Mappings, use PLAY to preview a saved chord, the heart to change setlist membership, and UNMAP to return it to Available Chords.
  • Filter key bindings by action name, category, or native shortcut.

MIDI

List ALSA sequencer inputs with:

aconnect -i

Chordarchy automatically selects inputs containing Korg or microKEY. Select any other detected input from Studio Settings.

The persistent audio stream requests a 128-frame quantum at 48 kHz, uses a 3 ms click-free attack and 20 ms volume smoothing, and reports estimated software-path latency in Settings. MIDI transport and controller hardware latency are not included in that estimate; USB MIDI is normally faster than Bluetooth.

Configuration

Mappings and preferences are written atomically to:

~/.config/chordarchy/config.json

Advanced users can add custom mappings with a customCommand argument array. Custom commands have the same authority as the logged-in user and should be reviewed carefully.

IPC

omarchy-shell io.github.ctl0v0.chordarchy status
omarchy-shell io.github.ctl0v0.chordarchy arm
omarchy-shell io.github.ctl0v0.chordarchy disarm
omarchy-shell io.github.ctl0v0.chordarchy mute
omarchy-shell io.github.ctl0v0.chordarchy unmute
omarchy-shell io.github.ctl0v0.chordarchy volume 1.0
omarchy-shell io.github.ctl0v0.chordarchy demo
omarchy-shell io.github.ctl0v0.chordarchy demoHold 3
omarchy-shell io.github.ctl0v0.chordarchy panic
omarchy-shell io.github.ctl0v0.chordarchy profile 49 60
omarchy-shell io.github.ctl0v0.chordarchy studio
omarchy-shell io.github.ctl0v0.chordarchy mappings
omarchy-shell io.github.ctl0v0.chordarchy practice
omarchy-shell io.github.ctl0v0.chordarchy settings
omarchy-shell io.github.ctl0v0.chordarchy.panel open
omarchy-shell io.github.ctl0v0.chordarchy.panel close
omarchy-shell io.github.ctl0v0.chordarchy.panel toggle

Remove

Remove the plugin checkout with:

omarchy plugin remove io.github.ctl0v0.chordarchy

The removal command preserves user configuration. To remove mappings and preferences as well:

rm -r ~/.config/chordarchy

Development

python3 -m unittest discover -s tests -p 'test_*.py'
node tests/test_music.js
omarchy plugin validate .

See CONTRIBUTING.md for the local workflow and docs/DEMO.md for the release recording storyboard and GIF tooling.

License

MIT copyright 2026 ctl0v0.