### Install Waitbus CLI and Initialize

Source: https://github.com/astrogilda/waitbus/blob/main/README.md

Install the Waitbus CLI tool using `uv` or `pipx`. Then, run `waitbus init` for a one-time setup of directories, SQLite schema, and scaffold files.

```bash
uv tool install waitbus              # or: pipx install waitbus
waitbus init                         # one-time setup: state dirs, SQLite schema, scaffold files
```

--------------------------------

### Install and Initialize Waitbus

Source: https://github.com/astrogilda/waitbus/blob/main/README.md

Install the waitbus package and perform the initial setup, including creating state directories, setting up the SQLite schema, and scaffolding necessary files. The `install-credentials` command is optional and specifically for GitHub CI integration.

```bash
uv tool install waitbus
waitbus init
waitbus install-credentials github-webhook-secret
```

--------------------------------

### Install waitbus CLI

Source: https://github.com/astrogilda/waitbus/blob/main/benchmarks/BENCHMARKING.md

Installs the waitbus CLI tool. Ensure your project is set up for development.

```bash
pip install -e .
```

--------------------------------

### Install waitbus CLI and Daemon

Source: https://github.com/astrogilda/waitbus/blob/main/docs/demo/README.md

Installs the waitbus daemon and CLI tools using uv. This is the first step to running the demo.

```bash
uv tool install waitbus
```

--------------------------------

### Start Waitbus Services and Daemons

Source: https://github.com/astrogilda/waitbus/blob/main/README.md

Commands to start the core daemons, background timers, and enable units for automatic startup on login. Ensure systemd user services are configured correctly.

```bash
# Start the core daemons
systemctl --user start waitbus-listener.service
systemctl --user start waitbus-broadcast.socket

# Start the background timers
systemctl --user start waitbus-etag-poll.timer
systemctl --user start waitbus-watchdog.timer

# Health check — exits 1 on any missing required config or stopped unit
waitbus doctor

# Watch webhook deliveries arrive in real time
waitbus read-events watch
```

```bash
systemctl --user enable waitbus-broadcast.socket \
    waitbus-etag-poll.timer waitbus-watchdog.timer
# The webhook listener is opt-in; `install-credentials github-webhook-secret` enables it.
```

--------------------------------

### Install waitbus with plugin verification toolchain

Source: https://github.com/astrogilda/waitbus/blob/main/docs/CUSTOM_SOURCES.md

Install the optional extra for the verification toolchain. This enables in-process attestation verification.

```bash
pip install 'waitbus[plugin-verify]'
```

--------------------------------

### Install Agent Recipes

Source: https://github.com/astrogilda/waitbus/blob/main/examples/agent_pydantic_ai/README.md

Install the necessary dependencies for the agent recipes, including `pydantic-ai-slim` and `langchain-core`. This command uses `uv` for package management.

```sh
uv sync --group agent-recipes
# (pip does not support PEP 735 dependency-groups; with pip, install the deps directly:
#   pip install pydantic-ai-slim langchain-core)
```

--------------------------------

### Install waitbus-langgraph

Source: https://github.com/astrogilda/waitbus/blob/main/adapters/waitbus-langgraph/README.md

Install the waitbus-langgraph package using pip. Requires a running waitbus broadcast daemon.

```bash
pip install waitbus-langgraph
```

--------------------------------

### Clone, Install, and Run Full 24-Hour Soak Test

Source: https://github.com/astrogilda/waitbus/blob/main/docs/SOAK_TEST.md

Set up the waitbus project on a soak host by cloning the repository, installing dependencies, and running a 24-hour soak test with standard suspend cycles. Output is redirected to 'soak.log'.

```bash
git clone https://github.com/astrogilda/waitbus.git
cd waitbus
uv sync --all-extras

# Two-mode with standard suspend cycles:
nohup python -m scripts.soak \
    --duration 24h \
    --rate 5 \
    --inject-suspend-cycles standard \
    --output soak-verdict.json > soak.log 2>&1 &

# Watch progress:
tail -F soak.log

# When done:
jq '.overall_passed, .verdicts' soak-verdict.json
```

--------------------------------

### Install and Verify waitbus Plugin

Source: https://github.com/astrogilda/waitbus/blob/main/docs/CUSTOM_SOURCES.md

Install a waitbus plugin using pip and restart the waitbus daemons. Use `waitbus source list`, `waitbus source show`, and `waitbus source verify` to confirm registration and publisher binding.

```sh
pip install waitbus-circleci
# Restart waitbus daemons so the entry-point walk picks up the plugin.
systemctl --user restart waitbus-listener waitbus-broadcast

# Verify the plugin registered and is bound to its publisher:
waitbus source list
waitbus source show circleci
waitbus source verify circleci
```

--------------------------------

### Install waitbus-pydantic-ai

Source: https://github.com/astrogilda/waitbus/blob/main/adapters/waitbus-pydantic-ai/README.md

Install the package using pip. Requires a running waitbus broadcast daemon.

```bash
pip install waitbus-pydantic-ai
```

--------------------------------

### Install waitbus Package

Source: https://github.com/astrogilda/waitbus/blob/main/SKILL.md

Install the waitbus package using pip, uv tool, or pipx. Ensure your Python environment is set up correctly.

```bash
pip install waitbus
```

```bash
uv tool install waitbus
```

```bash
pipx install waitbus
```

--------------------------------

### Install waitbus Custom Source Plugin

Source: https://github.com/astrogilda/waitbus/blob/main/examples/custom_source_plugin/README.md

Install the custom plugin into your Python environment. This can be done directly from a local path or from a published wheel.

```sh
pip install /path/to/examples/custom_source_plugin
```

```sh
pip install waitbus-circleci
```

--------------------------------

### Install System Services

Source: https://github.com/astrogilda/waitbus/blob/main/README.md

Install system services for Waitbus. On Linux, this involves copying and enabling 8 systemd-user units. On macOS, it involves copying and bootstrapping 4 LaunchAgent plists.

```bash
waitbus install-systemd              # Linux: copy + enable the 8 systemd-user units
waitbus install-launchd              # macOS: copy + bootstrap the 4 LaunchAgent plists
```

--------------------------------

### Initialize waitbus and Systemd Units

Source: https://github.com/astrogilda/waitbus/blob/main/SKILL.md

Run these commands once to initialize waitbus, install GitHub webhook credentials if needed, and set up systemd user units for background services.

```bash
waitbus init
```

```bash
waitbus install-credentials github-webhook-secret
```

```bash
waitbus install-systemd
```

--------------------------------

### Install waitbus Claude Code Plugin

Source: https://github.com/astrogilda/waitbus/blob/main/README.md

Use this command to install the waitbus plugin for Claude Code. Alternatively, use the marketplace entry once published.

```bash
claude --plugin-dir ~/.local/share/waitbus/plugin
```

--------------------------------

### Reproduce waitbus demo GIF

Source: https://github.com/astrogilda/waitbus/blob/main/README.md

This command reproduces the waitbus cross-harness demo GIF shown in the documentation. Ensure you have make installed.

```bash
make hero
```

--------------------------------

### Run waitbus demo

Source: https://github.com/astrogilda/waitbus/blob/main/README.md

This command runs a gentler, single-agent demo of waitbus, suitable for a quick start.

```bash
waitbus demo
```

--------------------------------

### Run Hero Swarm Demo

Source: https://github.com/astrogilda/waitbus/blob/main/examples/hero_swarm/README.md

Execute the hero swarm demo from the repository root. Ensure the 'agent-recipes' group is installed, as it provides the necessary Pydantic AI and LangGraph frameworks.

```bash
uv run --group agent-recipes python -m examples.hero_swarm
```

--------------------------------

### Basic StateGraph Usage with waitbus-langgraph

Source: https://github.com/astrogilda/waitbus/blob/main/adapters/waitbus-langgraph/README.md

Demonstrates how to build a StateGraph using waitbus-langgraph nodes. This example sets up a node to wait for a specific bus event and then routes based on event delivery or timeout.

```python
from langgraph.graph import END, START, StateGraph
from waitbus_langgraph import event_router, wait_node

builder = StateGraph(MyState)
builder.add_node("wait_on_bus", wait_node('fields.conclusion="failure"', source="github", timeout=600.0))
builder.add_node("triage", my_triage_node)
builder.add_edge(START, "wait_on_bus")
builder.add_conditional_edges("wait_on_bus", event_router(on_event="triage", on_timeout=END))
builder.add_edge("triage", END)
graph = builder.compile()
```

--------------------------------

### Install Optional Credentials

Source: https://github.com/astrogilda/waitbus/blob/main/README.md

Optionally install HMAC secrets for securing the GitHub webhook listener and Alertmanager. Re-running these commands rotates the existing credential.

```bash
waitbus install-credentials github-webhook-secret   # optional: HMAC for the GitHub webhook listener (opt-in)
waitbus install-credentials alertmanager-hmac       # optional: alertmanager / watchdog HMAC
```

--------------------------------

### Check CLI versions

Source: https://github.com/astrogilda/waitbus/blob/main/benchmarks/BENCHMARKING.md

Verifies that the Claude and Gemini CLIs are installed and accessible. Sign-in may be required.

```bash
claude --version
```

```bash
gemini --version
```

--------------------------------

### Custom Source Plugin Directory Structure

Source: https://github.com/astrogilda/waitbus/blob/main/examples/custom_source_plugin/README.md

Example directory structure for a custom Waitbus source plugin written in Python.

```text
my-waitbus-plugin/
    pyproject.toml
    src/
        my_waitbus_plugin/
            __init__.py
            plugin.py
```

--------------------------------

### Install Hint for Match-CEL Evaluator

Source: https://github.com/astrogilda/waitbus/blob/main/docs/CONSUMER_API.md

This error message indicates that the 'cel' extra is required to use the --match-cel flag. Install it using pip.

```bash
to use --match-cel, install waitbus[cel]
```

--------------------------------

### CPU Pinning and Execution

Source: https://github.com/astrogilda/waitbus/blob/main/benchmarks/BENCHMARKING.md

Example of pinning a process to specific CPU cores and running a Python module. Ensure the specified cores are isolated for accurate results.

```bash
taskset -c 2,3 uv run python -m benchmarks.bench_ttfae_pytest ...
```

--------------------------------

### Configure Kernel for CPU Isolation

Source: https://github.com/astrogilda/waitbus/blob/main/benchmarks/BENCHMARKING.md

Example of kernel command-line parameters for advanced CPU isolation. These settings help dedicate cores to specific tasks.

```bash
Add `isolcpus=2,3 nohz_full=2,3 rcu_nocbs=2,3` to GRUB_CMDLINE_LINUX.
```

--------------------------------

### Run Waitbus Demo

Source: https://github.com/astrogilda/waitbus/blob/main/README.md

Execute the Waitbus demo command to allocate a temporary state directory, boot the broadcast daemon, and run a two-phase demonstration of its waiting capabilities.

```bash
uvx waitbus demo          # one command, no install needed
```

--------------------------------

### Start waitbus Broadcast Daemon

Source: https://github.com/astrogilda/waitbus/blob/main/docs/demo/README.md

Starts the waitbus broadcast daemon in the background. This daemon is responsible for broadcasting events.

```bash
waitbus broadcast serve &
```

--------------------------------

### Run All Adapter Tests

Source: https://github.com/astrogilda/waitbus/blob/main/adapters/README.md

A script to execute all adapter test suites from the repository root.

```bash
scripts/run_adapter_tests.sh
```

--------------------------------

### Install GitHub Webhook Secret Credentials

Source: https://github.com/astrogilda/waitbus/blob/main/SKILL.md

Rotate or install GitHub webhook secret credentials. This is often required after a signature rejection.

```bash
waitbus install-credentials github-webhook-secret
```

--------------------------------

### Pre-deploy Gate: Verify Attestation and Pin

Source: https://github.com/astrogilda/waitbus/blob/main/docs/EXIT_CODES.md

Implement this script as a pre-deployment gate to fail closed if the live attestation disagrees with the recorded pin, or if the necessary tooling is not installed. It checks for successful verification, missing attestation/tooling, missing pin, or publisher mismatch.

```bash
# Pre-deploy gate: fail closed if the live attestation disagrees
# with the recorded pin, OR if the live extra is not installed.
waitbus allowlist verify circleci
case $? in
    0)  echo "circleci publisher binding is intact" ;; 
    65|78) echo "FAIL: cannot verify (no attestation OR no tooling)" && exit 1 ;; 
    66) echo "FAIL: pin missing for circleci" && exit 1 ;; 
    76) echo "FAIL: publisher mismatch -- inspect via `waitbus allowlist verify` output" && exit 1 ;; 
esac
```

--------------------------------

### Quick Liveness Overview

Source: https://github.com/astrogilda/waitbus/blob/main/SKILL.md

Provides a quick overview of the liveness status of Waitbus.

```bash
waitbus status
```

--------------------------------

### Platform-Specific Installations for Waitbus

Source: https://github.com/astrogilda/waitbus/blob/main/README.md

Install waitbus systemd units on Linux or LaunchAgents on macOS. These commands are platform-specific and will error if run on the incorrect operating system.

```bash
waitbus install-systemd
```

```bash
waitbus install-launchd
```

--------------------------------

### Start Waitbus Broadcast Socket Unit

Source: https://github.com/astrogilda/waitbus/blob/main/SKILL.md

Start the systemd user socket unit for the Waitbus broadcast daemon. The service unit is pulled in on first subscriber connect.

```bash
systemctl --user start waitbus-broadcast.socket
```

--------------------------------

### Declare Entry-Point in pyproject.toml

Source: https://github.com/astrogilda/waitbus/blob/main/docs/CUSTOM_SOURCES.md

Define the plugin's entry point for Waitbus to discover. The `waitbus.sources.v1` group is used for version 1 sources, and the key must match the canonical source name.

```toml
[project]
name = "waitbus-circleci"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["waitbus>=0.5,<0.6"]

[project.entry-points."waitbus.sources.v1"]
circleci = "waitbus_circleci:plugin"
```

--------------------------------

### Waitbus config.toml Plugin Policy

Source: https://github.com/astrogilda/waitbus/blob/main/docs/CUSTOM_SOURCES.md

Configure plugin autoloading, allowed, and denied plugins. Defaults to autoloading enabled with empty allow/deny lists.

```toml
[plugins]
autoload = true          # walk the entry-point group at startup
allow    = []            # if autoload=false, only these names load
deny     = []            # always-applied blocklist

```

--------------------------------

### Declare Plugin Entry-Point in pyproject.toml

Source: https://github.com/astrogilda/waitbus/blob/main/examples/custom_source_plugin/README.md

Configuration for a custom Waitbus source plugin in `pyproject.toml`, specifying dependencies and the entry-point for Waitbus to discover the plugin.

```toml
[project]
name = "my-waitbus-plugin"
dependencies = ["waitbus>=0.5,<0.6"]

[project.entry-points."waitbus.sources.v1"]
my_source = "my_waitbus_plugin:plugin"
```

--------------------------------

### macOS LaunchAgent Plists

Source: https://github.com/astrogilda/waitbus/blob/main/README.md

List of LaunchAgent plists installed by `waitbus install-launchd` on macOS systems, located in `~/Library/LaunchAgents/`.

```text
dev.waitbus.listener.plist     dev.waitbus.broadcast.plist
dev.waitbus.etag-poll.plist    dev.waitbus.watchdog.plist
```

--------------------------------

### Linux Systemd Units

Source: https://github.com/astrogilda/waitbus/blob/main/README.md

List of systemd-user units installed by `waitbus install-systemd` on Linux systems, located in `~/.config/systemd/user/`.

```text
waitbus-listener.service    waitbus-broadcast.socket
waitbus-broadcast.service   waitbus-etag-poll.service
waitbus-etag-poll.timer     waitbus-watchdog.service
waitbus-watchdog.timer      waitbus-forward@.service
```

--------------------------------

### Broadcast Daemon Subscribe Frame

Source: https://github.com/astrogilda/waitbus/blob/main/SKILL.md

Example JSON payload for subscribing to the broadcast daemon. Filters and event types can be specified.

```json
{"proto": 1,
 "filters": ["owner/repo", "*", "owner/*"],
 "event_types": ["workflow_run", "workflow_job",
                 "prometheus_alert", "prometheus_watchdog"],
 "since": "01HZ...26chars",
 "envelope": "diffs"}
```

--------------------------------

### Initialize Waitbus Database

Source: https://github.com/astrogilda/waitbus/blob/main/SKILL.md

Re-run waitbus init if the database is missing. This command is idempotent.

```bash
waitbus init
```

--------------------------------

### Configure waitbus Plugin Autoloading

Source: https://github.com/astrogilda/waitbus/blob/main/examples/custom_source_plugin/README.md

Configure waitbus to discover and load installed plugins. The `autoload` setting in `config.toml` controls this behavior.

```toml
[plugins]
autoload = true   # default — all installed waitbus.sources.v1 plugins are loaded
# allow = ["circleci"]   # if autoload=false, explicitly allow specific plugins
# deny = []              # always-applied blocklist
```

--------------------------------

### Tap into waitbus Events

Source: https://github.com/astrogilda/waitbus/blob/main/docs/demo/README.md

Starts a listener to observe all events broadcast by the waitbus daemon. Useful for debugging and understanding event flow.

```bash
waitbus broadcast tap &
```

--------------------------------

### Touch a File to Trigger Event

Source: https://github.com/astrogilda/waitbus/blob/main/docs/demo/watched-dir/README.md

Use this command to create a new file in the watched directory, which will trigger a file system event.

```bash
touch watched-dir/$(date +%s)
```

--------------------------------

### Verify Release Artifacts with GH Attestation

Source: https://github.com/astrogilda/waitbus/blob/main/README.md

Use this command to verify the integrity of release artifacts. It requires the `gh` CLI and Python to be installed.

```bash
gh attestation verify $(python -c "import waitbus; print(waitbus.__file__)") \
  --repo astrogilda/waitbus
```

--------------------------------

### Trigger Docker Event

Source: https://github.com/astrogilda/waitbus/blob/main/docs/demo/README.md

Starts Docker containers using docker compose, which triggers a docker event. The event is generated when containers exit.

```bash
docker compose up
```

--------------------------------

### Show Plugin Registration Details

Source: https://github.com/astrogilda/waitbus/blob/main/examples/custom_source_plugin/README.md

Inspect the full registration details of a specific custom source plugin.

```sh
waitbus source show circleci
```

--------------------------------

### Invoke PR Monitor Manually

Source: https://github.com/astrogilda/waitbus/blob/main/SKILL.md

Example of manually invoking the pr-monitor tick command for specific PRs, as it's designed for session-scoped, direct invocation.

```bash
waitbus pr-monitor tick --pr 7
```

--------------------------------

### Dry Run for Database Migrations

Source: https://github.com/astrogilda/waitbus/blob/main/SECURITY.md

Command to preview the SQL and Python code that will be executed during a schema migration. This allows operators to review changes before applying them.

```bash
waitbus db migrate --dry-run
```