docs

Integrations

facades, connectors, agent clients, and hooks — what bro plugs into.

bro keeps vendor details behind facades. Commands ask for tasks, reviews, agents, or specs; the configured connector supplies the backend.

Review hosts

GitHub (gh)

The GitHub connector implements the reviews facade over authenticated gh: PR state, threads, checks, and merge operations.

GitLab (glab)

The GitLab connector implements the same reviews facade over authenticated glab: merge-request state, threads, checks, and merge operations. GitLab support is intentionally a review facade, not a claim that every GitHub surface exists on GitLab. GitLab.com is detected from the origin remote; self-hosted instances can be selected through connectors.reviews.

Task backends (facades and connectors)

bro's task facade is backend-agnostic. Commands like bro next, drill/work planning, and the agent loop call the tasks facade; a configured connector supplies the backend. bro convoy currently requires Beads (molecules/formulas and bead-backed DAG state) and does not run against Linear or Jira alone; other task-backend support is opt-in per command as documented. The facade contract keeps vendor details pluggable — not every backend implements beads-specific features (publish/import projections, certain metadata shapes), and bro documents honest absences per connector rather than assuming parity.

Beads (bd)

bd is the default task and memory backend. Drill frames, review debt, retros, and work claims use the task facade; the JSONL ledger remains the evidence record even when the beads projection is disabled.

Linear

Linear is supported as an opt-in tasks backend via @broject/linear.

  • Selection: connectors.tasks = "linear" in bro.config.json (name-only opt-in; a git remote never auto-selects Linear).
  • Auth/prerequisites: LINEAR_API_KEY (Linear → Settings → Security & access), sent verbatim in the Authorization header. LINEAR_TEAM is required when the workspace has more than one team; optional if there's exactly one.
  • Version availability: Linear support is available in the current bro package line (shipped with @broject/linear).
  • Capabilities: issues as TaskStore/TaskStoreAsync, bro query integration (provider = "linear"), mapping to bro states/deps/children with <!-- bro: {...} --> trailer metadata.
  • Honest absences: publish is not implemented (no bead→issue projection mapping in this milestone). Some beads-specific projections (e.g. certain import flows) may not map 1:1 to Linear — see the package README for mapping details.

Jira (Cloud and Data Center/Server)

Jira is supported as an opt-in tasks backend via @broject/jira, with separate connectors for Cloud and Data Center/Server.

  • Selection: name-only opt-in — connectors.tasks = "jira" (Cloud) or connectors.tasks = "jira-dc" (Data Center/Server). Nothing in the repo remote/structure auto-selects Jira.
  • Auth/prerequisites: the atlassian CLI must be installed and authenticated (atlassian auth login or ATLASSIAN_TOKEN). For Data Center, ATLASSIAN_TOKEN must be a personal access token (Bearer). Pin the site via JIRA_BASE_URL/ATLASSIAN_BASE_URL for Cloud. jira-dc requires a site base via JIRA_DC_BASE_URL (or the CLI config baseUrl) so it never defaults to api.atlassian.com; do not share JIRA_BASE_URL with it. Set JIRA_PROJECT/ATLASSIAN_PROJECT if the site has multiple visible projects.
  • Version availability: Jira support is available in the current bro package line (shipped with @broject/jira).
  • Capabilities: issue CRUD/state/deps/children over the atlassian CLI's REST passthrough, JQL via bro query, Cloud (ADF) and DC (plain text) body mapping with <!-- bro: {...} --> trailer support.
  • Honest absences: publish is not implemented (no bead→issue projection mapping in this milestone). Custom link types are resolved by name against the site's link types (no faking as comments). Some beads-specific features may not be supported — see the package README for details.

Keeping your existing tracker

If you already use Linear or Jira (or any supported tracker), you do not need to migrate to beads to use bro's task facade. Set connectors.tasks to the appropriate backend and configure auth/prerequisites above. bro commands that consume the tasks facade will route through that connector. Beads-specific features (e.g. certain projections/imports) remain beads-centric; connectors document their capabilities and honest absences explicitly.

Facade → connector → capabilities (quick matrix)

FacadeConnectorsSelectionNotes
reviewsgithub (gh), gitlab (glab)Detected from origin remote (GitHub/GitLab.com) or configured via connectors.reviewsPR/MR state, threads, checks, merge operations.
tasksbeads (bd, default), github, linear, jira, jira-dcConfigured via connectors.tasks (name-only opt-in). Beads is the default.Issue/task state, deps, claim/close where supported. Not all beads-specific projections are implemented on every backend.
queriesgithub, gitlab, atlassian, linearConfigured via connectors.queries or per bro query stepPlan-driven fan-out across providers.
agentsNative/tmux/Gas City backendsConfigured via connectors.agentsDetached agents/workers.
specsNative + tool-layout matchersDetected or explicitly configuredSpec-driven workflows.

Agent clients

ClientAdapter
Devinplugins/devin/bro
Claude Coderepo root (.claude-plugin/plugin.json + skills/); hooks in plugins/claude/bro/hooks/
Codexrepo root (plugin.json + skills/); hooks in plugins/codex/bro/hooks/
Cursorplugins/cursor/bro
OpenCodebro plugins install opencode — native plugin (server + TUI + RPC)
Kilobro plugins install kilo — module + kilo.json registration
pibro plugins install pi — extension module

Cursor installs from .cursor-plugin/marketplace.json. The adapter's hooks/hooks.json uses Cursor event names; bro hooks (0.3.0) translates that stdin (conversation_id, loop_count, shell command) into the shared contract and writes Cursor output (additional_context, followup_message, permission). Cloud agents do not run sessionStart, so the first beforeSubmitPrompt rehydrates once and preCompact clears that mark. stop allows a single follow-up. A plain bro or bd command is auto-approved even when the workspace has not opted in — an empty permission reply would block the command — and a chained command stays a prompt.

OpenCode v2 loads a plugin as a directory — and it raises the TUI half only for a package that also has a server, so bro's three modules (the server entrypoint, the TUI half and the RPC contract they share) land together: bro plugins install materializes them into $XDG_CONFIG_HOME/opencode/plugins/bro/ or, locally, into .opencode/plugins/bro/. Kilo and pi get the same treatment: a module file in the client's extension dir, with Kilo's global install also registered in kilo.json's plugin array. All three use the same bro hook bus; OpenCode has no pre-stop hook, so the first stop-gate blocker is fed back as one synthetic prompt and later stop checks are skipped rather than re-evaluated (stop_hook_active).

Agent backends

The agents facade can resolve native detached processes, tmux, or Gas City. Selection belongs under connectors.agents; backend knobs live under the agents section. A respawn reuses the dead worker's agent ID, worktree, and stored prompt.

Sverka

bro check is the check facade. Sverka executes the repository workflow; bro reports its steps and findings and mirrors its exit code. --evaluate also collects SARIF artifacts and applies the Sverka policy gate.

Hooks

Connectors contribute fail-open probes at lifecycle boundaries:

  • Session start rehydrates state and injects matched lessons or SDD policy.
  • Parallel work contributes a nudge when another live session owns work in the same repository.
  • Prompt submit adds contextual policy and matched lessons.
  • Post-tool drains the mailbox with bro comms notify and injects lessons matched by the tool trace.
  • Stop contributes gate findings from the active connectors.

The hook runner owns the per-session arming policy. A connector reports state; it does not decide whether ambient repository state should block this session. Probes are bounded and fail-open, so a missing or wedged backend does not wedge the agent.

Capability matrix

Not every host can do everything — the matrix below is the declared contract, enforced cell-by-cell against the shipped manifests and adapters by host-matrix.test.ts. Bump HOOK_MATRIX_VERSION in packages/cli/src/host-matrix.ts when any cell changes; the table here is its rendering.

bro eventClaudeCodexDevinCursorOpenCodeKilopiOMP
session-startSessionStartSessionStartSessionStartsessionStartsession.hook("context")chat.system.transformsession_startsession_start
post-compaction—PostCompactPostCompaction———session_compactsession_compact
pre-compactPreCompactPreCompact—preCompactsession.hook("compaction")—session_before_compactsession_before_compact
prompt-submitUserPromptSubmitUserPromptSubmitUserPromptSubmitbeforeSubmitPromptsession.hook("prompt")chat.system.transformbefore_agent_startbefore_agent_start
post-toolPostToolUse + PostToolUseFailure (Bash)PostToolUse (Bash)PostToolUse (exec)postToolUse + postToolUseFailure (Shell)tool.execute.after—tool_resulttool_result
pre-toolPreToolUse (Bash)PreToolUse (Bash)——tool.execute.before——tool_call
permission—PermissionRequestPermissionRequestbeforeShellExecutionpermission.hook("evaluate")permission.ask——
stopStop → blockStop → blockStop → blockstop → one follow-upsession.idle → re-promptsession.idle → warn logagent_before_settle → re-promptsession_stop → block

— is a declared gap: the host lacks the surface or bro deliberately does not wire it (Claude's PostCompact/PermissionRequest, OMP's permission plane, pi's block-only tool_call). Hosts that cannot halt a stop turn bro's decision:block into UX — a follow-up prompt or a log line — never enforcement.

Post-tool outcome is normalized per host: Claude splits success and failure into two events; Devin sends tool_response.success; Cursor's translator maps its split events; the extension adapters synthesize it from isError; Codex cannot observe it (PostToolUse fires on non-zero exits), so Codex arms on the hint and the journal records no ok.

Completion is sync on the manifest hosts — run.sh blocks the event, bounded by its timeout — and async on the extension/plugin adapters, whose handlers resolve while work (a settle refresh, a notification lane) continues in the background.

Three boundaries, stated once:

  • Advisory ≠ enforcement. Nudges, context injection, re-prompts and toasts are UX. They are never a compliance or merge gate — the only enforced decisions are the ones a host's own block/rewrite/ approve slots apply.
  • bro policy ≠ host permissions. The stop gate and merge policy own repo state (markers, beads, PR gates). The host's permission plane stays the user's security surface; bro answers permission events, it does not widen them.
  • Opt-in approval is scoped. The approve column approves only bro/bd self-tools — a workspace opting in to bro calling itself unprompted, not a statement about any other tool.

The data ref

bro work sync keeps runtime artifacts outside the review surface on refs/bro/data. Tracked source stays in branches; the data ref is for untracked runtime state.

On this page