README
¶
bsbctl
bsbctl connects BUSY Bar to local tools on macOS. It shows Calendar events, Codex activity and quota, and Mac resource usage.
See it on the device
These previews use mock data. See preview generation for how they are made.
| Local Mac Calendar | Codex | Codex quota |
|---|---|---|
 |
 |
 |
| Mac Resources | ||
 |
Install
On macOS, connect a reachable BUSY Bar and install the latest stable release:
curl -fsSL https://github.com/lxdb/bsbctl/releases/latest/download/install.sh | sh
The installer verifies the download, installs bsbctl in ~/.local/bin, starts a per-user service, and asks which apps to enable. No app is selected by default. Add ~/.local/bin to PATH if needed.
Release binaries are ad-hoc signed, not Developer ID signed or notarized. macOS may block them under its Gatekeeper policy.
Check the installation:
bsbctl status
A JSON response confirms that the daemon responds. Check the device readiness field separately. For authentication, app selection, or setup failures, see Getting started.
Documentation
| Task | Guide |
|---|---|
| Choose and configure apps | Built-in apps |
| Use the device controls | Device and attention |
| Troubleshoot the service | Operations |
| Find a command | CLI reference |
| Build a plugin | Plugin authoring |
| Contribute or release | Maintainer documentation |
See the documentation index for all guides and references.
Support and license
Report bugs through GitHub Issues. Use the security policy for vulnerability reports.
Licensed under GNU GPL version 3 or later. Before redistribution, review NOTICE, third-party notices, and LICENSES/.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
bsbctl
command
|
|
|
bsbctl-plugin-calendar
command
|
|
|
bsbctl-plugin-codex
command
|
|
|
bsbctl-plugin-codex-quota
command
|
|
|
bsbctl-plugin-mac-resources
command
|
|
|
localinstall
command
localinstall is the checkout-only implementation of install.sh --local.
|
localinstall is the checkout-only implementation of install.sh --local. |
|
releasectl
command
Command releasectl builds, verifies, and publishes release artifacts.
|
Command releasectl builds, verifies, and publishes release artifacts. |
|
docs
|
|
|
examples/raw-json-plugin
command
raw-json-plugin is a transport example that intentionally uses only the Go standard library.
|
raw-json-plugin is a transport example that intentionally uses only the Go standard library. |
|
internal
|
|
|
assets
Package assets verifies and reconciles plugin-owned device assets.
|
Package assets verifies and reconciles plugin-owned device assets. |
|
attention
Package attention owns core-only eligibility, arbitration, and explanations.
|
Package attention owns core-only eligibility, arbitration, and explanations. |
|
catalog
Package catalog verifies the signed metadata and content digests used for independently released plugin executables.
|
Package catalog verifies the signed metadata and content digests used for independently released plugin executables. |
|
checkpoint
Package checkpoint owns bounded, non-secret plugin state scoped to one authenticated plugin instance generation.
|
Package checkpoint owns bounded, non-secret plugin state scoped to one authenticated plugin instance generation. |
|
cliinput
Package cliinput owns cancellable process stdin without detached read workers.
|
Package cliinput owns cancellable process stdin without detached read workers. |
|
codexusage
Package codexusage normalizes and renders Codex account rate-limit windows independently of the provider used to obtain them.
|
Package codexusage normalizes and renders Codex account rate-limit windows independently of the provider used to obtain them. |
|
config
Package config owns validated, generation-checked, atomic daemon configuration.
|
Package config owns validated, generation-checked, atomic daemon configuration. |
|
configschema
Package configschema verifies and applies plugin-owned JSON Schemas.
|
Package configschema verifies and applies plugin-owned JSON Schemas. |
|
control
Package control implements the local CLI-to-daemon JSON-RPC control plane.
|
Package control implements the local CLI-to-daemon JSON-RPC control plane. |
|
daemon
Package daemon composes observation state, core attention, and device output.
|
Package daemon composes observation state, core attention, and device output. |
|
daemonrun
Package daemonrun owns construction and bounded shutdown of the daemon runtime.
|
Package daemonrun owns construction and bounded shutdown of the daemon runtime. |
|
device
Package device owns the single serialized BUSY Bar output boundary.
|
Package device owns the single serialized BUSY Bar output boundary. |
|
deviceownership
Package deviceownership prevents multiple bsbctl daemons from writing to the same BUSY Bar application namespace at the same time.
|
Package deviceownership prevents multiple bsbctl daemons from writing to the same BUSY Bar application namespace at the same time. |
|
eventbus
Package eventbus provides bounded, session-bound input delivery.
|
Package eventbus provides bounded, session-bound input delivery. |
|
firstpartyplugins
Package firstpartyplugins owns immutable metadata shared by the built-in plugin development, verification, packaging, and release workflows.
|
Package firstpartyplugins owns immutable metadata shared by the built-in plugin development, verification, packaging, and release workflows. |
|
identifier
Package identifier validates and encodes identifiers used at trust boundaries.
|
Package identifier validates and encodes identifiers used at trust boundaries. |
|
input
Package input maps BUSY Bar physical controls to core-owned interaction state.
|
Package input maps BUSY Bar physical controls to core-owned interaction state. |
|
installer
Package installer authenticates, verifies, installs, activates, and recovers independently released bsbctl plugins.
|
Package installer authenticates, verifies, installs, activates, and recovers independently released bsbctl plugins. |
|
launchagent
Package launchagent writes the macOS login-service definition for bsbctl.
|
Package launchagent writes the macOS login-service definition for bsbctl. |
|
livesession
Package livesession owns the shared lifecycle of plugin foreground sessions.
|
Package livesession owns the shared lifecycle of plugin foreground sessions. |
|
localstate
Package localstate persists small local JSON documents with explicit commit outcomes at the atomic rename boundary.
|
Package localstate persists small local JSON documents with explicit commit outcomes at the atomic rename boundary. |
|
logfile
Package logfile provides a private size-bounded rotating file writer.
|
Package logfile provides a private size-bounded rotating file writer. |
|
pluginhost
Package pluginhost supervises direct-child executable plugins.
|
Package pluginhost supervises direct-child executable plugins. |
|
pluginlog
Package pluginlog owns bounded, non-blocking plugin diagnostic delivery.
|
Package pluginlog owns bounded, non-blocking plugin diagnostic delivery. |
|
pluginverify
Package pluginverify exercises the built-in package contract without certifying an independent protocol implementation.
|
Package pluginverify exercises the built-in package contract without certifying an independent protocol implementation. |
|
presentation
Package presentation defines BUSY Bar-specific plugin output and selection policy.
|
Package presentation defines BUSY Bar-specific plugin output and selection policy. |
|
releaseartifact
Package releaseartifact defines deterministic public-release metadata and files.
|
Package releaseartifact defines deterministic public-release metadata and files. |
|
releasecheck
Package releasecheck evaluates machine-checkable public-release inputs.
|
Package releasecheck evaluates machine-checkable public-release inputs. |
|
releasekeys
Package releasekeys loads the tracked catalog verification trust set.
|
Package releasekeys loads the tracked catalog verification trust set. |
|
secrets
Package secrets resolves durable opaque references without placing values in configuration, process arguments, or environment variables.
|
Package secrets resolves durable opaque references without placing values in configuration, process arguments, or environment variables. |
|
soak
Package soak provides fail-closed process accounting for the release soak.
|
Package soak provides fail-closed process accounting for the release soak. |
|
plugins
|
|
|
codexquota
Package codexquota publishes bounded Codex account quota observations.
|
Package codexquota publishes bounded Codex account quota observations. |
|
macresources
Package macresources publishes bounded Mac CPU, memory, and network observations.
|
Package macresources publishes bounded Mac CPU, memory, and network observations. |
|
sdk
|
|
|
internal/jsonnames
Package jsonnames checks JSON object names before typed or raw-value decoding.
|
Package jsonnames checks JSON object names before typed or raw-value decoding. |
|
plugin
Package plugin provides the public author API and runtime for executable bsbctl plugins.
|
Package plugin provides the public author API and runtime for executable bsbctl plugins. |
|
protocol
Package protocol defines the public, exact bsbctl plugin protocol 1.0 application contract.
|
Package protocol defines the public, exact bsbctl plugin protocol 1.0 application contract. |
|
rpc
Package rpc implements bounded bidirectional JSON-RPC 2.0 over a byte stream.
|
Package rpc implements bounded bidirectional JSON-RPC 2.0 over a byte stream. |
Click to show internal directories.
Click to hide internal directories.