# BRB

![BRB](https://cdn.jsdelivr.net/npm/@yedan1122/brb/docs/assets/readme.webp)

<!-- section:hero -->

> Bridge Pi Agent workflows with a real ChatGPT conversation.

[English](README.md) | [简体中文](README.zh-CN.md)

BRB is a Pi Agent extension for safely handing a task to ChatGPT, receiving a plan, and returning to the Pi workflow with delivery safety, identity checks, and bounded recovery.

<!-- section:platform-boundaries -->

BRB is an independent open-source local automation tool that connects to a ChatGPT Web
session already signed in by the user through browser automation. BRB is not affiliated
with, authorized by, endorsed by, or sponsored by OpenAI, Google, or Microsoft.

BRB is not designed to bypass CAPTCHAs, usage limits, account restrictions, security
challenges, or other platform protections: when it meets one, it stops, reports why, and
hands the next step back to you. Users are responsible for ensuring that their use of
third-party services complies with the applicable terms, organizational policies, and
rules.

BRB drives Chrome/Edge on the user's own computer and uses a session the user has already
signed in to. BRB does not require the user to provide their ChatGPT password to BRB.

**Data flow:** what moves between Pi, ChatGPT Web, BRB, and your configured AI provider —
and what may be persisted locally — is documented in [docs/data-flow.md](docs/data-flow.md).


<!-- section:release-status -->
<!-- fact:package=@yedan1122/brb -->
<!-- fact:version=0.1.0-beta.10 -->
<!-- fact:release-status=beta-candidate -->
<!-- fact:pi-host-status=beta-candidate -->
<!-- fact:npm-status=published-beta -->

**Status: Public beta** — version `0.1.0-beta.10`, published on npm as `@yedan1122/brb@beta`. BRB is a Pi-only npm package.

## Choose Your Host

<!-- section:host-selection -->

| Host | Status | Interface | Best for |
|---|---|---|---|
| **Pi** | Beta candidate / Primary | `/brb` commands + TUI | Full BRB workflow: handoff, execution, bounded recovery, and onboarding |

Pi automatically handles bounded runtime page stalls. Loss of protocol or session continuity still requires an explicit `/brb resume`.

## Install

<!-- section:install -->

```bash
pi install npm:@yedan1122/brb@beta
```

## Quick Start

<!-- section:quick-start -->

```bash
/brb setup          # environment → login → conversation → Git policy
/brb status         # overview (0 messages)
/brb ask <task>     # send a task to the ChatGPT conversation
```

## How It Works

<!-- section:how-it-works -->

```
Pi Agent ──BRB──CDP── ChatGPT Web
```

## Host Support

<!-- section:host-support -->

| Capability | Pi |
|---|---|
| Status / diagnostics | ✓ |
| Browser launch | ✓ |
| Existing conversation bind | ✓ |
| Account affinity (A17) | ✓ |
| Safe handoff / report | ✓ |
| Interactive onboarding | ✓ |
| Automatic relay loop | ✓ |
| Runtime stall recovery | ✓ |
| Protocol continuity recovery | Manual `/brb resume` |
| TUI / completion | ✓ |

## Why BRB

- **Real ChatGPT threads**: not an API proxy — conversation context and account-side history are preserved.
- **Safe handoff**: capability gate + send-boundary freshness barrier + delivery reconciliation.
- **Account identity binding** (A17): the current principal is re-observed before remote side effects; a mismatch fails closed.
- **Bounded recovery**: recovery adds effort, never permission; give-up requires an explicit human restart.

## Safety Model

Capability registry / fail-closed / no saved passwords / limited auto-create / Git push not automatic by default. See [docs/safety-model.md](docs/safety-model.md).

<!-- section:auto-bind-on-unbound -->

### Unbound-thread onboarding

When a thread without a binding runs a conversation-dependent operation (`ask`, `plan`, `read`, `copy`, `sources`, or `start`), BRB uses `autoCreateOnUnbound` (`ask` by default) to offer one inline choice. Explicit URLs win; ambiguous results are recorded as orphans and never retried. `/brb orphan clear <id>` clears only the local blocker and never deletes a remote conversation.

## Commands

Type `/brb <space>` for completion; see [docs/commands.md](docs/commands.md) for the full list.

## Compatibility

- Node ≥18 (verified on node22); Chrome/Edge + CDP; an existing ChatGPT account (manual login); depends on `@earendil-works/pi-coding-agent`.

## Documentation

<!-- section:documentation -->

- [docs/quick-start.md](docs/quick-start.md)
- [docs/commands.md](docs/commands.md)
- [docs/safety-model.md](docs/safety-model.md)
- [docs/troubleshooting.md](docs/troubleshooting.md)
- Pi detailed reference (Chinese): [docs/pi-reference.zh-CN.md](docs/pi-reference.zh-CN.md)
- Repository: [github.com/yedan1122/brb](https://github.com/yedan1122/brb)

## Development

[CONTRIBUTING.md](CONTRIBUTING.md) — Node/Pi requirements, tests, and security invariants.

> The `package.json` scripts target repository development. The test/tooling harness under `tests/` and `scripts/` is **not shipped** in the npm package; clone the repository to run it.

## License

MIT — [LICENSE](LICENSE)

<!-- section:end -->

<!-- internal-doc-index:start -->
<!-- internal-doc-index:end -->