FluxBar Companion 0.8.1

A local Codex plugin for Windows FluxBar 0.4+, with a workflow skill and eleven stdio MCP tools. Works with Codex running natively on Windows or in WSL2 on that Windows machine. Requires Node 18+ on the Codex host PATH and the running toolbar in the same Windows user/session; WSL additionally requires Windows Node 18+ and working interoperability. No npm dependencies, API key, network listener or cloud service.

Toolbar 0.9 adds staged favicon URL previews and explicit button removal to the confirmed batch workflow. The other AI instance shows the actual image and identifies exactly which button will be removed, asks for approval, then applies that exact stored batch. No Settings step is needed for these confirmed changes. Installing/updating the plugin does not approve changing existing buttons. See favicon/removal batches.

Toolbar 0.8 adds direct app-published menus after one-time button permission and user-created setup, without Codex/project suggestions. The AppIntegration helper publishes ordered, expiring snapshots over the local pipe. It also adds two AI tools: preview a batch of existing-button patches, then apply the exact plan after explicit user confirmation in chat. Suggestions remain available. No proposal, publication or configuration apply executes an action. Read direct app menus and chat-confirmed edits for integration and confirmation rules; userConfirmation is a caller assertion, not host-verified human approval.

Toolbar 0.6 adds Custom / favicon… beside Built icons, with local PNG/JPEG/ICO import, explicit URL loading and a preview. Apps can propose iconUrl for native review, with a built-in fallback. Suggestions never fetch images automatically; the user loads/selects a preview before approval. Imports are cached locally, never uploaded, and failures leave saved icons unchanged. See custom icons and favicons for fields, limits, clearing/preservation rules and an example. Existing custom-image pixels retain their original colours.

For apps with frontend and backend servers, see right-click controls and supervisor guidance. It covers one managed foreground command, startup dependencies, combined readiness, partial failures, cleanup and platform-specific stop limitations. Toolbar 0.7 adds up to ten custom entries via menuActions, plus the existing managed Start/Stop/Restart controls. Native Buttons and Suggestions provide list editing and explicit approval; actions execute only on user clicks.

Core tools: status, project list/detail, register project, suggest button, expiring per-instance activity, explicit handoff, LED notification and scoped app lifecycle reporting. Suggestions are reviewed under native Settings → Suggestions. A changed target never changes an installed button without a fresh user approval. The plugin deliberately has no approval or arbitrary execution tool.

Toolbar 0.5 adds app-reported lifecycle status alongside polling. Propose allowLifecycleReports: true; the user approves it, saves the button, then selects Create / copy app reporting setup in Buttons. The actual app uses that private setup file through the bundled Windows Node helper. fluxbar_report_lifecycle exposes read/begin/report by registered project ID without accepting or returning credentials. See the integration guide for Node and WSL/other-language examples, shutdown ordering, timeouts, restart recovery and state precedence. Agent Working/Done messages are never app health.

Runs use UUIDs, server-issued generations and increasing sequences. Ready leases expire; Stopping stays latched despite polling or ordinary Ready messages. Confirmed intentional exit is neutral, unannounced observed exit is red, and overdue shutdown stays advisory amber. A final app message or HTTP failure alone cannot prove exit. Reporting grants no stop/restart ownership and never makes FluxBar automatically kill/restart an app. Existing integrations are unchanged until the user opts in. Do not share one button's key across independently running apps/replicas.

Toolbar 0.4.3 adds Built icons, a visual searchable picker of 40 locally bundled Lucide outline icons. Custom image imports remain available through Custom / favicon… on toolbar 0.6+. Companion 0.3 exposes the same names in suggestion.icon; see the icon catalogue and recommendations or machine-readable icons.json. The original six names remain valid. Additional names require toolbar 0.4.3+; the plugin checks before storing a proposal. Built icons inherit the text/status colour. Custom images retain their own colours. Selecting or proposing an icon does not launch the button target.

Lucide source is pinned and bundled, with no runtime fetch or font dependency. Attribution and ISC/MIT notices are included in Lucide-LICENSE.txt and native build/publish output under ThirdParty/.

With FluxBar 0.4.2+, button proposals also accept healthUrl, observeName, backgroundColour, textColour and boolean useStatusColours. Native Suggestions displays these values for editing before approval. Omitted fields preserve an existing button's configuration; an empty health/process string clears it, empty text colour uses its preset, and false disables automatic status colours. Colours must be opaque #RRGGBB. Unsupported toolbar versions reject extended proposals before storing anything.

Examples include a dashboard with a verified HEAD health endpoint, an editor shortcut with read-only process observation, a managed foreground WSL development service, and an unmonitored documentation shortcut. See the packaged skill for complete example tool arguments and palette recommendations. The examples are templates: verify their target, endpoint and Windows reachability before proposing them. Suggested deep blue for dashboards, plum for editors, teal for services and slate for documentation are recommendations, not automatically assigned category defaults.

fluxbar_status returns state.buttonStatuses with each button's display state, rendered colours and automatic mode. state.workloads separately reports process status/ownership. HTTP 2xx HEAD responses are Connected; non-success responses are Warning; failed requests are Disconnected. Running/Observed proves a process exists, not account login or application connectivity. Monitoring begins only after approval and an actual health refresh; unknown status keeps the custom colours.

Load the folder containing plugin.json through your client's local plugin installation flow. The shared mcp.json now runs node with ${PLUGIN_ROOT}/scripts/launch.mjs on both platforms. Native Windows imports the server directly and needs no Bash, WSL distribution or wslpath. WSL retains the existing Bash exec handoff to Windows Node through interoperability, translating only the plugin path. Paths with spaces remain separate process arguments. The server and named pipe stay in the Windows user session.

On WSL, set FLUXBAR_WINDOWS_NODE to the Windows executable's WSL path if it is not discoverable (for example /mnt/c/Program Files/nodejs/node.exe). Explicit Windows-format paths are also converted. Standard Windows Node/nvm4w locations are fallback candidates. scripts/launch.sh remains the WSL-only handoff used internally by the portable entry point and can also be invoked manually. Standalone/remote Linux and macOS have no transport to this local Windows pipe.

For GitHub installation and updates, see the repository installation guide. Install separately in each native Windows or WSL Codex profile; refresh the client after installation.

The package uses the portable Agent Plugins format: root plugin.json and mcp.json, with an explicit stdio transport. Codex resolves ${PLUGIN_ROOT} in this format. Version 0.1.0 used the legacy compatibility format, which Codex 0.163.0 passed literally to Bash and failed before starting the launcher. Version 0.1.1 fixes that startup failure. Refresh the installed package and restart/refresh the client; existing conversations may retain their original tool inventory. This package does not change sandbox permissions or Windows/network configuration.

A shell probe under an execution sandbox can separately fail with UtilBindVsockAnyPort. That alone does not diagnose the client's MCP launch. Check its actual startup error and tool inventory; 0.1.1 has been verified through Codex app-server discovery and a real fluxbar_status call. If the client's own launcher reports a WSL interoperability restriction, it still needs an execution context permitted to run Windows Node.

Invoke the FluxBar skill in each intended project instance. Register a stable project ID, send an early button suggestion, and report activity during meaningful progress. Unknown targets stay drafts. Session entries expire; no hooks or automatic heartbeat daemon are installed. Handoff notes are deliberately shared local data, not shared hidden model memory.

Data lives in FluxBar's own companion.json, separate from toolbar settings. Limits: 32 projects, 8 unexpired instances per project, 2000-character handoff and 240-character activity. Agents cannot approve or dismiss through MCP. User dismissal is preserved when the same proposal is submitted again. For privacy, send short task metadata, not secrets or personal file contents.

Protocol checks: node --test tests/plugin.test.mjs from the FluxBar repository. Native approval checks: scripts/test-desktop.ps1. Windows MCP checks: node scripts/test-plugin-windows.mjs from this repository in Windows, after updating FluxBar.

Official format reference: https://developers.openai.com/plugins/build/plugins