Jukebox

One console, two levels of intervention

Jukebox keeps the everyday decision small: choose Verbatim when the prompt should still sound like you, or Upskill when the task benefits from the vocabulary, artifacts, constraints, and acceptance criteria of the field you are discussing. Choose a connected provider and model, then keep talking. The recording has no Jukebox time limit.

Settings makes the consequential behavior explicit:

• Review first opens the complete generated prompt in an editable, scrollable deck before anything reaches the coding agent. Edits are saved privately before Insert or Copy can continue. Auto-insert restores the originating window and pastes there without pressing Enter.
• Provider cards report the real connection state for Codex, Claude Code, and OpenRouter. Jukebox never silently substitutes a different provider or model, and transcript content cannot change routing or persistent settings.
• Prompt Workbench lets you inspect, edit, save, or reset the private Verbatim and Upskill templates. Every override must retain {{TRANSCRIPT}}, is stored with private permissions, and remains outside the repository.
• Agent-ready controls expose a bounded semantic UI contract for opening views, choosing modes and models, scrolling long content, and activating named actions without exposing transcripts, prompts, or credentials in UI snapshots.

Plugin direction

The central hypothesis is that a primary chat thread becomes more useful when its language stays detailed, specific, and native to the domain, giving the model high-resolution context for later work. Recent studies report that LLMs strongly converge toward a conversation's style and adapt their syntactic choices to conversational partners; Jukebox explores whether deliberate prompt upscaling can use that tendency productively without inventing facts.

Possible next experiments include specialist critique-and-rewrite stages, multiple candidate prompts with evaluation, and short-lived conversation forks that use the primary thread as context before returning a tailored prompt. Longer term, Jukebox may become a voice-driven control center for broader workflows.

How to use

1. Open Jukebox once. Its guided setup checks dependencies, shows hotkey conflicts, tests the microphone, and offers one explicit, reversible configuration action.
2. Click the coding-agent terminal where the finished prompt should return, then press Super+F9. Jukebox remembers that exact Hyprland window; the session stays open until you decide it is finished.
3. Choose Verbatim or Upskill, then choose a connected provider and one of that adapter's explicit models.
4. Speak naturally while the movable, resizable console shows live frequency activity.
5. Press Super+F10 or click Finish + Clean/Upskill. Jukebox either opens the review deck or automatically inserts the result into the originating terminal, according to Settings. Auto-insert never presses Enter.
6. Scroll and edit the complete draft, compare the raw transcript if needed, then choose Insert into Agent, Copy, Retry, Discard, or cancel an active transformation. Insertion restores the exact originating window and never presses Enter.

Open the brass gear to choose Review first or Auto-insert, connect providers, and edit or reset the private Verbatim and Upskill templates. Custom templates must retain the {{TRANSCRIPT}} placeholder.

The X button, Cancel, Escape, and Ctrl+W dismiss Jukebox without deleting the active recording or waiting draft. Explicitly summon Jukebox again to return to the same workflow state.

Prompt modes

Architecture

flowchart LR
    A[Microphone] --> B[Voxtype<br/>meeting capture]
    B --> C[NVIDIA Parakeet<br/>local transcription]
    C --> D{Jukebox mode}
    D --> V[Verbatim<br/>cleanup]
    D --> U[Upskill<br/>expert compiler]
    V --> E{Connected provider}
    U --> E
    E --> X[Codex CLI]
    E --> Y[Claude Code]
    E --> O[OpenRouter]
    X --> R[Editable review]
    Y --> R
    O --> R
    R --> F[Coding agent<br/>exact originating window]

    click B "https://github.com/peteonrails/voxtype" "Open Voxtype"
    click C "https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3" "Open NVIDIA Parakeet"
    click D "https://github.com/JamesWeatherhead/jukebox" "Open Jukebox"
    click X "https://github.com/openai/codex" "Open Codex CLI"
    click Y "https://code.claude.com/docs/en/overview" "Open Claude Code"
    click O "https://openrouter.ai/docs/guides/overview/auth/oauth" "Open OpenRouter OAuth docs"

Jukebox reuses coding-agent CLIs you already authenticated for Codex and Claude Code. It checks each CLI's documented status command and never reads its credential store. OpenRouter uses its documented browser PKCE flow and stores the resulting user-controlled key in the Linux Secret Service keyring, never in Jukebox settings.

The interface runs inside Omarchy's shared shell, while capture and prompt upscaling remain isolated backend processes. A private provider bridge stays warm for ten minutes, streams supported provider output, and exits automatically. Recordings, transcripts, credentials, model caches, and machine-specific state stay outside this repository.

Runtime stack

See Architecture, Development plan, the versioned expert-intent compiler, and the conservative verbatim-cleanup contract.

Requirements

• Omarchy 4 / Quattro and its long-running Quickshell shell
• Voxtype meeting mode with Parakeet or Whisper; guided setup recommends an engine and defaults language detection to auto
• Codex CLI or Claude Code authenticated through its own subscription-backed login; OpenRouter is optional and requires secret-tool from libsecret
• wtype, wl-clipboard, hyprctl, and libnotify
• PulseAudio parec and Python NumPy for the bundled live frequency display

Jukebox does not request root privileges. The plugin, controller, compiler, and every dependency run with the current user's permissions.

Installation

Review the source, then install and enable the current release:

omarchy plugin add https://github.com/JamesWeatherhead/jukebox.git --enable
cd "$HOME/.config/omarchy/plugins/io.github.jamesweatherhead.jukebox"
less manifest.json
less Jukebox.qml
less bin/jukebox
less bin/jukebox-upscale
./scripts/validate.sh
./bin/jukebox-setup plan --json
./bin/jukebox-setup setup --yes

The setup command prints its plan without changing anything unless --yes is supplied. It writes only a marked Jukebox binding block and the required Voxtype keys, records their prior values privately, and can reverse them with ./bin/jukebox-setup uninstall --yes. The same flow is available inside the first-run panel.

Removal

First restore the hotkeys and Voxtype values that Jukebox changed:

cd "$HOME/.config/omarchy/plugins/io.github.jamesweatherhead.jukebox"
./bin/jukebox-setup uninstall --yes

Then remove the plugin itself:

omarchy plugin remove io.github.jamesweatherhead.jukebox

The rollback step restores only values recorded by Jukebox. Removing the plugin does not delete Voxtype meetings or optional Jukebox state and history. See Rollback and removal for the complete data cleanup options.

Contributing

Contributions are welcome. Read CONTRIBUTING.md before proposing changes. In particular, never commit recordings, transcripts, generated prompts containing private information, credentials, or model artifacts.

Open contributions

Jukebox v0.2 ships Codex, Claude Code, and an initial OpenRouter adapter. The following work remains open for focused, independently reviewable contributions. Each integration must safely delegate authentication, preserve the selected model without hidden downgrade, keep private speech out of process arguments and logs, and leave capture and terminal delivery unchanged.

Gemini CLI adapter

• Reuse Gemini CLI's documented Google sign-in, with API-key or Vertex paths supported only when their billing/auth mode is explicit.
• Add explicit Gemini model validation without hidden provider or model fallback.
• Cover missing binary, logged-out session, quota/rate errors, unavailable models, timeout, malformed output, and transcript recovery.
• Keep Google OAuth material, API keys, and service-account credentials outside Jukebox storage and logs.

OpenRouter hardening

• Implement user-controlled OpenRouter PKCE and keyring-only secret storage; this is separately billed and is not a coding-agent subscription.
• Add explicit openrouter/auto routing and a mocked HTTP protocol test.
• Refuse credential-bearing redirects and bound completion responses before JSON parsing.
• Add searchable model discovery plus connection replacement, disconnect, and remote revocation UI.
• Complete opt-in live OAuth/inference validation; mocked protocol coverage already includes 401/402/403/404/429/5xx responses, invalid JSON, redirects, and oversized responses.

The linked issues define the full security boundaries, acceptance criteria, integration evidence, and documentation required for each pull request. Please claim or discuss a track there before implementing it so contributors do not duplicate work.

Security and privacy

Omarchy plugins run unsandboxed with the current user's permissions. Review all dependencies and commands before enabling a development build. See SECURITY.md for the trust boundaries and reporting process.

Raw transcripts exist only while a prompt is awaiting review or recovery and are removed after successful insertion or copy. Generated prompts are retained privately for seven days by default. Failed drafts expire after 24 hours. Voice audio stays inside the configured local transcription engine. Only transcript text is sent to the provider explicitly selected in Jukebox. Transcript content cannot select a provider, model, mode, or delivery setting. Jukebox has no telemetry.

License

MIT © James Weatherhead. See LICENSE.