An opinionated coding agent. Built on Pi.
Want a graphical frontend? Follow the illustrated T3 Code setup guide.
curl -fsSL 'https://raw.githubusercontent.com/tnfssc/bruv/develop/scripts/install.sh' | shSupports Linux x64/arm64, macOS Apple Silicon, and Android Termux arm64 (API 28+). Requires curl and either sha256sum or shasum.
The pair contains one compiled bruv binary and a small POSIX
bruv-claude-compat launcher. Keep them together. The launcher needs /bin/sh
on Linux/macOS or /system/bin/sh on Android. The Android binary runs natively
with /system/bin/linker64; no Bun, Node, glibc or proot runtime is needed.
The installer
downloads Bruv and its matching bruv-claude-compat connector from one release,
verifies both executable checksums, and installs them in ~/.local/bin.
Licenses and notices go in ~/.local/share/bruv/notices/<version>.
It does not use sudo, edit shell profiles, or install T3.
Stop active Bruv/T3 sessions before replacing the pair.
Put ~/.local/bin on your PATH, then start Bruv in your project:
bruvConfigure your provider with /login and choose a model with /model.
Credentials and model access come from your provider; they are not included.
bruv update --check # Check without changing files
bruv update # Update the sibling CLI and connector togetherStop active sessions first and restart afterward. Split/custom binary layouts
need a manual paired reinstall. External T3 updates separately with t3 update;
check its accepted version and setup
before updating.
The bundled guidance tells the agent to act on clear requests, try a small check instead of guessing what is unavailable, and report what it actually found. It favors a simple working change over speculative fallbacks, while keeping security and data-loss protections. Old behavior is kept when you ask for it, rather than carried forward by default.
Project wisdom keeps decisions with the code. Agents read wisdom/values.md
before large changes. They write reasons, checks, and next steps while doing the work.
Wisdom goes with the code, before the last commit or PR—not after the job is done.
Once the task is done or its PR is merged, stop editing that worktree. New work needs a new task and PR.
Set wisdomDir in .bruv/settings.json to use another directory; /wisdom
shows the resolved path. See project wisdom.
- Background jobs and subagents let the agent hand off work and collect results. Tasks can share a checkout or use a separate Git worktree.
/questionskeeps human decisions in a conversation inbox./remoteconnects to human-authorized SSH targets and opens their separate task/question inbox. Remote state can be read offline; answering needs a fresh connection.- Live voice shares the terminal session's tools and history.
/livestarts it,/live modelselects a voice, and/live setupchecks credentials. - Herdr integration reports working, idle, and waiting-for-input state when Bruv runs in a Herdr terminal pane. Herdr is optional.
Inside Bruv, type / to see available commands. In question menus, type to
search, use arrows and Enter to select, and Escape to go back. Local questions
are answered through /questions; remote-owned questions through /remote.
bruv # Start the interactive terminal
bruv -p "Describe this tree" # Run one prompt and exit
bruv -c # Continue the latest session
bruv -r # Pick a saved session to resume
bruv web # Show external T3 setup guidancemacOS Apple Silicon releases include the native audio helper. Linux currently requires a separately built helper. Live uses same-host audio, not browser microphone transport, and sends audio to the selected provider with possible API charges.
Gemini and OpenAI Realtime use session tools directly. GPT-Live (gpt-live-1)
uses your selected coding agent as its backend. /live provider configures
credentials without changing the voice model; model labels indicate local
credential readiness, not verified access. OpenAI Live needs an OpenAI API key;
Codex OAuth alone is not sufficient. Keep keys out of chat.
Live starts in push-to-talk mode. The mic stays open locally, but muted audio is
discarded, not saved or sent. Tap Space to type a space; hold Space in the normal
editor to speak. Release ends the spoken turn. Typing or leaving the editor
mutes the mic. Spoken turns stay in the same conversation as typed turns.
Terminals with key-release events mute immediately. Other terminals infer release
after 250 ms without repeats; this is not a hardware key-up guarantee.
Use /live input to choose push-to-talk or continuous mic before starting.
Continuous mode sends all captured mic audio while Live is on. GPT-Live primary
has no manual input-turn control; use Gemini or OpenAI Realtime for push-to-talk.
/live stop ends voice, not jobs. Speech interruption does not cancel work;
ask explicitly to stop work. GPT-Live transcripts are provisional, and ambiguous
requests may need clarification. For device checks, use /live status,
/live mic-check, or /live speaker-check. Checks ask before opening devices;
they do not connect to Google. bruv --live-self-test checks the embedded helper
without opening devices. See Live onboarding.
Install official T3 separately and launch it normally. Add a separate Claude
protocol instance named Bruv, with the absolute connector binary path,
an isolated SDK history home field and exact custom Bruv model IDs. Auth defaults
to ~/.bruv/agent, shared with ordinary Bruv; SDK history is distinct.
Do not change parent/global CLAUDE_CONFIG_DIR or use Claude login/updater.
bruv web only prints guidance, without installing T3 or rewriting settings.
Official v0.0.46-nightly.20261004.2644 lacks the provider-scoped SDK history fix: basic chat may work, but native fork can fail before Bruv starts. After Stop, Decline any stale approval card before continuing. See the illustrated setup guide for steps and limits.
Install Bun 1.4.2, then:
git clone https://github.com/tnfssc/bruv.git
cd bruv
bun install --frozen-lockfile
bun run check
bun run buildThe build compiles dist/bruv once and writes the small executable
dist/bruv-claude-compat launcher beside it. The connector reports
2.1.280 (Bruv compatibility; bruv <product>) for --version; use
--bruv-version for the product version and paired packaging/update checks.
During an older updater’s private .bruv-update-* staging probe only, the
canonical launcher’s exact --version call retains the old truthful
bruv-claude-compat <product> response. After installation it uses the SDK-facing
compatibility identity above; new packaging/update checks use --bruv-version.
Install your local build:
bun run install:localThe static landing page lives in site/. See the site README
for local preview, content and demo edits, tests, and static hosting/Vercel setup.
State lives under ~/.bruv. CLI sessions/configuration use ~/.bruv/agent;
external T3 owns ~/.bruv/web/userdata and SDK transcripts use
~/.bruv/claude-compat-sdk. Project prompts live in .bruv/;
app environment overrides use BRUV_*.
Existing ~/.die data is not read or migrated. Bruv does not rename or remove
the old executable; old die update versions still expect old asset names.
- Resource limits: output capture, truncation, and cache ownership. Original session history is not deleted.
- Question inbox implementation and CLI surface.
- Project wisdom, worktree setup, and feature notes.
Run bun run perf:terminal for frame measurements or bun run perf:interactions
for isolated provider-free action cases. See the harness guide
for usage, report dashboards and measurement limits. No performance fixes are included.
On GitHub: Actions → Release → Run workflow → develop → Run workflow. The workflow prepares the next patch unless a newer stable version is ready, runs the native/build/updater/licensing gates, then publishes assets from the exact tested commit. The Actions bot needs permission to push develop and tags. Check that Publish succeeds; a preparation commit alone is not a release. See manual release recovery.
MIT. See third-party notices for dependencies.