pi-bro

A sidekick for you and your Pi agent: plain-language explanations, side questions, diagrams, PR review and second opinions, without cluttering the agent's context.

Packages

Package details

extension

Install pi-bro from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-bro
Package
pi-bro
Version
0.23.0
Published
Oct 13, 2026
Downloads
3,709/mo · 322/wk
Author
tranhoangnguyen0310
License
MIT
Types
extension
Size
5.7 MB
Dependencies
4 dependencies · 3 peers
Pi manifest JSON
{
  "image": "https://raw.githubusercontent.com/tranhoangnguyen03/pi-bro/main/docs/images/social-preview.png",
  "extensions": [
    "./src/bro.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-bro

npm tests node license

A sidekick for you and your Pi agent: plain-language explanations, side questions, diagrams, PR review and second opinions, without cluttering the agent's context.

pi-bro is an extension for Pi, a terminal coding agent. Bro opens its answers in a separate window and runs them through an AI coding CLI you already have and are signed in to, so your main agent's conversation stays clean. Before you install, see what leaves your machine.

Install

pi install npm:pi-bro

Then restart Pi or run /reload, and check your setup:

/bro doctor

To try Bro without installing it, run pi -e npm:pi-bro. To install from GitHub, use pi install git:github.com/tranhoangnguyen03/pi-bro.

Try it

Type this in Pi What happens
/bro Explains the agent's last reply
/bro file docs/report.pdf Explains a document (use your own path)
/bro url https://example.com/article Explains a webpage (use your own link)
/bro btw "what file defines this route?" Asks a side question
/bro show Draws the last turn as a diagram

What it does

Command What you get
/bro, /bro text, /bro file, /bro url Explain. A plain-language version of the agent's last reply, pasted text, a PDF/DOCX/Markdown file, or a public webpage. Three modes: brief, balanced, faithful.
/bro show Show. The last few turns drawn as a shape (call tree, file tree, diff, pseudocode, a sequence diagram, or an HTML layout) instead of prose.
/bro btw Side questions. A separate conversation seeded with recent context, so you can ask without interrupting the agent. ⚠️ Full-permission mode can edit files.
/bro guided-review <PR> Guided Review. An explanation and quality assessment of a GitHub PR, with ranked findings, source evidence and private questions. Needs the Claude or Muse backend.
bro_advisor tool Second opinion. A tool your agent can call mid-task; a fresh backend process investigates and returns advice to the agent. ⚠️ Runs with permissions bypassed.
/bro config, /bro preferences Settings and preferences. Pick the backend, model and effort per feature, and tell Bro how you like answers.

Every command, control and setting is in the user guide. Guided Review has its own guide.

Requirements

  • Pi >=0.84.2 (tested on 0.84.2 and 1.2) and Node.js >=22.19.0.
  • macOS or Linux. Windows is untested; there, cancelling stops only the backend's direct process, not anything it started.
  • At least one backend CLI on your PATH, signed in once from your terminal. You only need the one you use:
Backend CLI Notes
Google Antigravity agy Default for new settings. Needs >=1.1.15. Not for Guided Review.
Claude Code claude Works for every feature, including Guided Review.
Grok Build grok Not for Guided Review.
Codex CLI codex Not for Guided Review.
Muse Code muse Works for every feature, including Guided Review.
  • Guided Review also needs Git and an authenticated gh. Choose Claude or Muse for it in /bro config.
  • PiG support is experimental.

What leaves your machine

Each feature sends data to the backend you chose and its model provider, which may keep it under their own policies. Paths below are under ~/.pi/agent/ (or $PI_CODING_AGENT_DIR).

Feature What is sent What Bro keeps on disk
Explain The agent's last reply, your pasted text, or text extracted from your file or webpage, plus your preferences Nothing; the last result stays in memory
Show User and assistant text from recent turns (no tool calls, tool results, reasoning or images), plus your preferences Diagram pages in pi-bro-<uid>/ in your system temp folder
Side questions Your questions and up to the last 8 turns of conversation text, plus your preferences Nothing; the thread stays in memory
Guided Review The PR description and diff, the files the backend reads, your questions, plus your preferences Reviews and captured source in bro-reviews/, with no automatic cleanup
Advisor The agent's system instructions, tool list and whole conversation, including tool calls and results (reasoning and images omitted), plus your steering Steering in bro-advisor.md and the session file

/bro url also connects straight to the website, which sees your IP address. Bro runs each CLI as you, with your environment. It never reads or copies Pi's provider credentials, but the CLI signs in its own way, which can include API keys set in your environment. Nothing Bro produces enters Pi's conversation unless you insert it, except advisor answers, which return to the agent as tool results.

[!WARNING] These run the backend in your workspace with its permission checks bypassed:

  • Advisor: it can read, edit and run commands. "Advise, don't edit" is only an instruction.
  • BTW full-permission mode (turned on with /mode inside BTW): it is meant to edit files and run commands.
  • Grok, wherever you use it: its sandbox is always off. "Answer only from the supplied context" is only an instruction.

Details per backend: Backends: access and retention and Privacy and safety.

Limits

  • Documents: .md, .markdown, .txt, .pdf, .docx only, no OCR, up to 10 MiB. → Run OCR elsewhere first.
  • Webpages: one public HTML page; no logins, paywalls, page JavaScript or proxy settings. → Save the page as PDF or text and use /bro file.
  • No fallback: if the chosen backend, model or effort fails, Bro shows that backend's error instead of switching. → Run /bro doctor.
  • BTW threads and the last explanation live in memory only and clear on reload or restart.
  • Guided Review runs in local interactive Pi only and does not post to GitHub.

Full list: Troubleshooting and current limits.

Stability

Bro is 0.x: a minor version can change commands or settings. Breaking changes are listed under Breaking in the changelog and the release notes. Each release is published to npm from CI with provenance.

Contributing

npm ci
npm test        # offline: uses fake backend CLIs, never calls a model
pi --tui-mode fullscreen -e ./src/bro.ts

See CONTRIBUTING.md, the code map and the docs index. Report security problems privately as described in SECURITY.md.

License

MIT. See LICENSE and THIRD_PARTY_NOTICES.md.