convez.ai
SkillIntegração & APIsIntermediário
restarter

bb-bash — Bitbucket Cloud CLI para Agentes IA

restarter/bb-bash

CLI Bitbucket zero-config para agentes IA — gerenciar PRs direto do terminal

Ver no GitHub
InicialPluginScore · de 0 a 100

CLI bash single-file para Bitbucket Cloud, otimizado para agentes de código IA. Detecta repositório automaticamente, gerencia pull requests (criar, revisar, aprovar, mesclar) via terminal ou chat, sem configuração por projeto. Inclui snippets para Claude Code, Rules, Skills e integração nativa com agentes IA populares.

Instalação

$npx convez-ai restarter/bb-bash

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
1
Saúde
42%
Último commit
há 1 mês
Versão
v0.3.2
Issues abertas
1
Contribuidores
2

Casos de uso

  • Automação de fluxo de pull requests em projetos Bitbucket
  • Integração com agentes IA (Claude Code, Cursor, Copilot) para revisão de código
  • Comentários inline e aprovação/rejeição de PRs sem sair do editor
  • CI/CD e DevOps — gerenciar PRs programaticamente em pipelines

Veredito

Ferramenta bem pensada para quem usa Bitbucket Cloud com agentes IA. Zero-config e single-file tornam instalação trivial; integração nativa (Rules, Skills, snippets) elimina wiring manual. Público específico (Bitbucket + IA agents) mas execução sólida.

README

A tradução para o português deste README ainda está na fila.

bb-bash (bbb)

Bitbucket Cloud CLI built for AI coding agents — single-file bash with zero-config repo auto-detect and inline PR review, plus CLAUDE.md snippet, Rule, and Skill bundled out of the box.

bbb (the binary) wraps the Bitbucket Cloud REST API 2.0 so you and your AI agent can drive PR review, inline comments, approve, decline, merge, and create — all from chat or terminal, without leaving your editor. cd into any Bitbucket-Cloud-backed repo and run bbb pr list — workspace/repo are auto-detected from git remote, no per-project setup. No build step, no package manager: one bash script, two dependencies (curl, jq).

The drop-in artifacts (CLAUDE.md / AGENTS.md snippets + Claude Code Rule + Claude Code Skill) teach the AI agents you already use (Claude Code, Cursor, Copilot Chat, Codex, Aider, …) how to call bbb — no manual wiring. See For AI agents for what each artifact does.

Install

curl --proto '=https' --tlsv1.2 -fsSL \
    https://raw.githubusercontent.com/restarter/bb-bash/main/scripts/install.sh | bash

Re-run the same command to update; your .env is never touched.

Manual install, env-var overrides, and security-inspection one-liner: see docs/installation.md.

Setup

1. Create a Bitbucket API token

Go to https://id.atlassian.com/manage-profile/security/api-tokens. Required scopes:

  • read:repository:bitbucket
  • read:pullrequest:bitbucket
  • write:pullrequest:bitbucket
  • read:pipeline:bitbucket — optional, only for bbb pr checks to show Bitbucket Pipelines; gracefully omitted otherwise

2. Configure credentials

Edit ~/.local/share/bb-bash/.env:

BB_BASH_EMAIL="you@example.com"
BB_BASH_TOKEN="<api-token>"

Workspace/repo are auto-detected from git remote. Override with BB_BASH_WORKSPACE + BB_BASH_REPO (outside a git repo) or BB_BASH_REMOTE=<name> to pick a specific remote.

For AI agents

Run bbb install-agent inside your project — or with --global for every project at once — to drop integration artifacts so the AI agents you already use (Claude Code, Cursor, Copilot Chat, Codex, Aider, …) know how to call bbb without extra prompting.

Flags

FlagPurpose
--rule / --skill / --claude / --agentsPick the artifact(s) to install — see the table below
--globalInstall into ~/.claude/ instead of the current project; Claude Code auto-loads from there in every project. Works with --rule / --skill / --claude. --agents is project-only — no widely-adopted global path for AGENTS.md.
--dry-runPreview the writes without touching disk
--forceOverwrite an existing artifact (default is skip-if-exists)

Pin to a release tag for reproducibility: BB_BASH_REF=v0.2.0 bbb install-agent .... Full flag reference: docs/commands.md#install-agent.

Examples

bbb install-agent --claude                 # snippet → ./CLAUDE.md (any CLAUDE.md-reading agent)
bbb install-agent --rule --skill           # Claude Code: rule (always-on) + skill (on-demand)
bbb install-agent --rule --global          # global rule — auto-loaded in every project
bbb install-agent --rule --skill --global  # global rule + skill (Claude Code combo)
bbb install-agent --claude --dry-run       # preview without writing

What ships out of the box

Pick any one — each artifact is fully self-contained. Your AI agent gets the same end result (install hint, auth, commands, conventions, workflows). Choose by your tool / preference; combine if you want.

TypeProject installGlobal (--global)LoadingBest for
CLAUDE.md./CLAUDE.md~/.claude/CLAUDE.mdevery turnClaude / Cursor / Copilot via CLAUDE.md
AGENTS.md./AGENTS.md— (project-only)every turncross-tool agents (OpenAI Codex, Aider, Continue, …)
Rule./.claude/rules/bb-bash-rule.md~/.claude/rules/bb-bash-rule.mdsession startshort always-on hint, "bbb exists, here's how"
Skill./.claude/skills/bb-bash/SKILL.md~/.claude/skills/bb-bash/SKILL.mdon-demandfull workflows (review, respond, batch cleanup); zero context cost until invoked

Browse the artifact sources directly: docs/agents/ (README).

Then ask your agent things like

  • "Review PR #42 — leave inline comments on anything risky, then summarize."
  • "List open PRs by alice."
  • "Approve PR #12 and merge with --squash --delete-branch."
  • "Reply to comment 753926626 on PR #42 with: 'Good catch, fixed.'"

The agent already knows the commands because the install dropped a Rule + Skill into .claude/, plus a ## Bitbucket via bb-bash section into your CLAUDE.md / AGENTS.md.

Commands

# From inside any bitbucket.org repo:
bbb pr list                              # open PRs (default)
bbb pr list --state=merged --author=alice
bbb pr show 42
bbb pr diff 42
bbb pr checks 42                         # CI + pipelines status
bbb pr comments 42                       # general + inline comments

bbb pr comment 42 "general comment"
bbb pr inline 42 src/auth.ts 30 "consider extracting"
bbb pr inline --old 42 src/auth.ts 10 "this was important"
bbb pr reply 42 753926626 "Good point, fixed"
bbb pr edit-comment 42 753926626 "Updated text"
bbb pr delete-comment 42 753926626

bbb pr approve 42                        # single
bbb pr approve 42 43 44                  # batch
bbb pr decline 99 100                    # batch close-without-merge
bbb pr merge 42 --squash --delete-branch

bbb pr create main "Title" "Description"
bbb pr update 42 --title="New title"
bbb pr open 42                           # opens in browser

bbb raw "/pullrequests"
bbb raw-post "/pullrequests/42/comments" '{"content":{"raw":"test"}}'

Full command reference: docs/commands.md.

Inline comments

Two modes depending on which side of the diff you're commenting on:

Commandinline fieldUse case
bbb pr inline <id> <path> <line> <text>"to": <line>new / modified code
bbb pr inline --old <id> <path> <line> <text>"from": <line>deleted / old code

Line numbers are real file line numbers, not diff line numbers.

How auto-detect works

bbb resolves workspace/repo per invocation. See docs/design.md for the authoritative precedence chain. tl;dr:

  • Inside a bitbucket.org git repo → workspace/repo derived from origin (or first matching remote).

  • Outside a git repo, or for one-off overrides → set env vars:

    BB_BASH_WORKSPACE=mycompany BB_BASH_REPO=myproject bbb pr list
    
  • Override which remote auto-detect uses:

    BB_BASH_REMOTE=bb bbb pr list    # use 'bb' remote instead of 'origin'
    

Limitations

  • Bitbucket Cloud only — no Bitbucket Server / Data Center.
  • No pending / draft comments — Bitbucket's "Start review" batching is web-UI only; the API publishes every comment immediately.
  • pr list --reviewer=<user> not supported — Bitbucket BBQL doesn't expose reviewers.username filtering. Workaround: pipe bbb pr list through jq. Tracked in bb-bash-oja.
  • pr update --reviewers=u1,u2 uses usernames — Bitbucket has been deprecating usernames as stable identifiers. Migration to account_id / uuid tracked in bb-bash-oja.

Authentication

Basic Auth with email:api-token (Bitbucket required this format since Sept 2025; old App Passwords disabled June 2026).

Security

bbb sources .env directly, so shell metacharacters in values execute on every invocation. Keep .env to plain KEY=value lines — no backticks, no $(...), no unmatched quotes. Switching to a safe parser is tracked as a follow-up.

For inspecting install.sh before running it, see docs/installation.md#security-inspection.

API reference

Contributing

See docs/contributing.md.

Changelog

See CHANGELOG.md.

Ver o original no GitHub

Bom para

Relacionados