Scripts

All scripts are in scripts/. After npm link in the repo, three are on your PATH: session-bus (dist/cli.js), session-bus-setup (setup-client.sh) and claude-push (claude-push.sh). The links point into the checkout and belong to the active Node install; redo npm link after switching Node versions.

setup-client.sh (session-bus-setup)

scripts/setup-client.sh --url <base-url> --item <item-id> [--vault <vault>] [--op-sa-var <VAR>] [--allow-tools] [--dry-run]

Adds the bus and bus-push user-scope MCP entries to Claude Code, replacing existing ones.

Flag	Meaning
--url	Base URL, http(s)://host[:port], no path.
--item	1Password item id (lowercase letters and digits, 20+ characters). Use the id, not the title.
--vault	1Password vault holding the item. The script has a default; pass your own.
--op-sa-var	Name of the env var holding a 1Password service-account token that can read the vault. It is written into the entries as OP_SERVICE_ACCOUNT_TOKEN="$VAR", unexpanded. Pass '' when your normal op login can read the vault.
--allow-tools	Also add mcp__bus to permissions.allow in ~/.claude/settings.json.
--dry-run	Print the two entries and exit. Changes nothing, needs neither claude nor op.

It builds dist/ if missing, then checks that both entries report Connected and that ~/.claude.json contains no sbus_ string. Exit 2 on bad arguments, 1 on a failed check. It never reads or prints the token.

claude-push.sh (claude-push)

scripts/claude-push.sh [name] [claude args...]

Starts claude as a push session. The first argument is the name unless it starts with -. Without a name it uses <short-host>-<repo>, lowercased, with other characters replaced by -. It runs:

env -u DISABLE_TELEMETRY -u CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC \
  SESSION_BUS_NAME=<name> claude --permission-mode default \
  --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}' \
  [your args] --allowedTools mcp__bus --dangerously-load-development-channels server:bus-push

install-unit.sh

bash scripts/install-unit.sh [--dry-run | --print-db] [--launchd | --systemd]

Renders deploy/ templates with absolute paths and installs the unit. Without --launchd/--systemd it picks launchd on macOS and systemd elsewhere. --dry-run prints the rendered unit only; --print-db prints the BUS_DB path only. Both write nothing. Honors BUS_DB, BUS_HOST, BUS_PORT, XDG_STATE_HOME. See Run as a service.

bus-headers.sh

The headersHelper for the bus entry. Prints {"Authorization":"Bearer <token>"} on stdout, reading the token from op read "$SESSION_BUS_OP_REF" or $SESSION_BUS_TOKEN. Nothing about the token goes to stderr. Exit 1 when there is no token.

allow-bus-tools.mjs

node scripts/allow-bus-tools.mjs <settings.json>

Adds mcp__bus to permissions.allow. Idempotent, keeps other keys, writes atomically, and keeps one backup as <file>.bak-session-bus. Exit 1 if the file is not a plain JSON object.

Test scripts

Script	What it checks	Last line
scripts/smoke.sh	Mint a token, start serve on a free port, /healthz, 401 without a token, a second serve exits 3.	SMOKE PASS
scripts/e2e.sh	Real serve and an MCP SDK client: send, kill -9 the server, restart on the same DB, read the message back.	E2E PASS
scripts/gate.sh N	Blocks 0 to N: clean install, typecheck, build, tagged Vitest suite, static checks, smoke, unit rendering, e2e, README and handoff checks.	GATE N PASS

gate.sh deletes and reinstalls node_modules in block 0. All of these need pnpm run build first and use temporary state directories.