waterbrother

A local coding CLI with codex/claude-style interactive workflows, local tool calls, session persistence, approval controls, and bring-your-own-model provider support across OpenAI, Anthropic, OpenRouter, Ollama, SpaceXAI, and compatible APIs.

iOS computer terminals

The npm package includes tmux 3.7c for macOS 15+ and Linux on Intel/AMD x64 and ARM64. New installations use it automatically when opening persistent shells or computer coding agents from the iOS app. An existing tmux installation is preferred to preserve compatibility with its running sessions. WATERBROTHER_TMUX can select a specific executable. No additional tmux install, npm install hook, or runtime download is needed. The PTY bridge also requires Python 3 on the computer.

Windows computer connections run natively on Windows Node, using the installed Windows Tailscale app and the pairing saved under %USERPROFILE%\.waterbrother. Windows 10 version 1809 or newer (x64 or ARM64) is required. The package includes Microsoft node-pty/ConPTY binaries; WSL, Python, Go, and build tools are not required. Start Tailscale on Windows, then run waterbrother companion in PowerShell or CMD. If Windows Firewall prompts for Node, permit access on the network used by Tailscale. The phone must be able to reach the advertised Tailscale address on port 18789; a healthy loopback URL alone does not demonstrate remote reachability.

Native Windows terminals start CMD, which supports npm-installed Grok, Claude, and Codex command shims. PowerShell or an installed WSL distribution can also be started from that shell. Phone disconnects do not terminate the ConPTY sessions. Keep the companion running: unlike tmux on macOS/Linux, restarting the Windows companion ends its processes. Reopening the same saved inbox starts a replacement process; it does not resume the old process. Native Windows validation is recorded in the release notes; platform-independent tests alone are not Windows validation.

Run waterbrother windows-test on Windows to verify the bundled ConPTY runtime, terminal output, resize, input, phone detach/reconnect snapshots, and isolation. It creates temporary test sessions and does not touch existing companion sessions.

If you previously started 0.17.7 through WSL, stop that companion before starting the native Windows companion. The Windows pairing is reused when present. A pairing created only inside WSL requires pairing the Windows companion from the phone; do not copy private node credentials or delete the original pairing files.

Upstream runtime provenance and license notices are in vendor/tmux/.

Web docs interface

This repo includes a static docs web interface:

• / landing page
• /onboarding onboarding + API key guide
• /channels messaging-channel guide
• /install install instructions
• /usage usage guide
• /commands command reference
• /prod-readiness production-readiness checklist and release blockers
• /changelog release notes
• /faq FAQ

It is Vercel-ready via vercel.json (clean URLs, no build step required).

Implemented features

• iOS app (ios/) with on-device model GUI plus Tailscale attach to a live TUI
• waterbrother listen [--tailscale] [--port 18789] advertises /wb/health and streams tui_frame events
• Interactive and one-shot chat modes
• Codex-style non-interactive commands:
  • waterbrother exec <prompt>
  • waterbrother review <prompt>
  • waterbrother resume [session-id] [prompt]
  • waterbrother resume --last
• First-run onboarding wizard in terminal
  • asks for provider first
  • asks for API key when the selected provider requires one
  • tries a live provider model list after credentials, shows when that live list is in use, then falls back to the built-in catalog
  • prompts for default model and agent profile
  • can optionally configure Telegram during onboarding and offer to open the Telegram guide in your browser
  • if Telegram is configured for startup, the TUI autostarts the background Telegram gateway on launch
• Multi-provider chat integration through provider adapters and model registry
• Vision command for local images: waterbrother vision <image-path> <prompt>
• Authenticated GitHub repo reading for GitHub URLs, including private repos when gh is logged in
• Built-in webpage reading and web search tools for pasted URLs and open-web research prompts
• MCP stdio server support via config-driven mcpServers
• Interactive URL drop support: paste a public https://... URL directly and Waterbrother will read and summarize it
• Multiline paste stays buffered until explicit Enter, with a prompt-row placeholder like [Pasted Content 14083 chars]
• Agent profiles: coder, designer, reviewer, planner
• Model discovery command (waterbrother models list)
• Local model catalog (waterbrother models catalog)
• Active runtime model status (waterbrother models status)
• Named runtime provider/model presets (waterbrother runtime-profiles ...)
• Messaging gateway and channel readiness commands (waterbrother gateway status, waterbrother channels status)
• Onboarding guide command (waterbrother onboarding)
• Local self-update command (waterbrother update)
  • git-clone installs pull latest source, install deps, and run checks
  • npm installs upgrade with npm install -g @tritard/waterbrother@latest
• Environment diagnostics (waterbrother doctor)
• Tool calling for file, shell, search, and git tasks
• Diff preview in approval prompts: see exactly what will change before approving file writes and replacements
• Fuzzy whitespace-tolerant matching in replace_in_file to reduce failed edits
• Shell working directory tracking (cd commands update the shell cwd for subsequent calls)
• Approval policy for mutating/shell tools: auto, on-request, never
  • supports path-aware allow/ask/deny rules via config
  • supports command-aware shell allow/ask/deny rules via config
  • includes apply_patch, make_directory, and restore_checkpoint in approval-protected actions
  • restore_checkpoint is treated as high-risk and always requires explicit approval
  • On-request prompt supports keyboard-first actions:
  • ↑/↓ changes the highlighted approval row
  • Enter or y approve once
  • p saves a session approval rule for the current shell-command prefix or tool
  • Esc denies and optionally provides alternate guidance
  • the chooser renders in a bordered block with the default action highlighted
  • the footer shows a short rules indicator when session approval rules are active
• AI-powered commit command: waterbrother commit [--push]
• Split config layers:
  • user config (~/.waterbrother/config.json)
  • project overrides (.waterbrother/config.json)
• Session persistence (~/.waterbrother/sessions/*.json)
• Two-tier project memory:
  • global instructions (~/.waterbrother/WATERBROTHER.md)
  • project instructions (WATERBROTHER.md) — both merged into system prompt
• Accurate token tracking using API usage data when available (falls back to estimation)
• Manual compaction command (/compact) for long-running sessions
• Session forking with /fork
• Session cost tracking with /cost
• Working tree inspection with /diff
• Git-backed local checkpoints with restore support (/checkpoints, /rewind [id])
• Deterministic patch application tool (apply_patch) with preflight validation
• Turn contracts (new)
  • agent must declare intended scope before edits or risky shell calls
  • contract includes summary, allowed paths, expected commands, and verification commands
  • runtime blocks out-of-scope mutations automatically
• Turn receipts (new)
  • every tool-heavy or mutating turn writes a local receipt under .waterbrother/receipts/
  • receipt captures contract, files touched, checkpoint, verification results, and command/tool provenance
  • inspect with /receipts, /receipt last, /receipt <id>
  • summary printing is configurable with receiptMode / --receipts auto|off|verbose
  • default auto suppresses noisy receipt lines for minimal read-only turns
• Automatic post-edit verification
  • verification commands from the turn contract run automatically after edits
  • optional default verification commands available through config
• Auto-compaction near context limits (autoCompactThreshold, default 0.9)
• Interactive slash controls with command palette
  • / opens command menu
  • ↑/↓ changes selection
  • Enter accepts selected command
• Prompt editor quality-of-life
  • click within the active prompt to place the insertion cursor, including wrapped rows
  • drag across replies, logs, status text, or the draft to select; Ctrl+C copies the selection instead of interrupting, and right-click also copies a transcript selection
  • Ctrl+F opens a live filter over the current conversation; ↑/↓ navigates and Enter reveals a match without losing the draft
  • the mouse wheel scrolls the displayed conversation without entering a history input mode; typing or Escape returns to the live composer, and holding a drag at a screen edge extends selection through scrollback
  • Ctrl+O or Page Up explicitly opens the conversation browser; arrows and Page keys scroll, and Enter expands or collapses large tool output
  • /find <query> prints bounded conversation matches without conflicting with /search web search
  • ↑/↓ recalls prior prompts when the editor is not navigating wrapped text or a menu
  • unfinished local text survives an incoming iPhone turn and returns on the next prompt
  • long drafts use a scrolling viewport that keeps the insertion point visible; bracketed pastes stay in the editor until Enter
  • Alt+Enter inserts a newline, and supported terminals can also use Shift+Enter
  • Down on the final draft row moves to the end; slash-menu navigation still takes precedence
  • asynchronous stdout/stderr notices are placed above the active editor and the exact draft is redrawn atomically
  • rapidly failing autostart gateways use bounded exponential backoff and pause instead of flooding the prompt or spawning forever
  • emoji, combining accents, CJK text, wrapping, selection, deletion, and mouse placement use terminal-aware grapheme widths
  • slash suggestions rank common and fuzzy matches, continue through literal subcommands, and never insert <required> or [optional] template text
  • abbreviated command completion fills the editor before execution, so a guessed command can be reviewed before a second Enter
  • set WATERBROTHER_TUI_MOUSE=0 to preserve native terminal mouse behavior in an incompatible emulator
• Read-only file tools can inspect common home folders such as ~/Desktop, ~/Downloads, and ~/Documents without falling back to shell; /desktop, /downloads, and /documents are treated as aliases for those locations on macOS
• Turn presentation improvements
  • streaming assistant output for faster perceived response
  • explicit run-state tracking (planning, reading, editing, running, reviewing, done, error) persisted in session metadata
  • heartbeat/stuck detection with interrupt hint during long-running steps
  • spinner/progress animation while model or tools are running
  • live visible trace lines during turns for phases like thinking and tool use, with verbose-only run-state heartbeat details
  • per-turn summary with duration, tool outcomes, and token usage when available
  • compact trace grouping so tool retries do not spam the status line
  • formatted code-fence rendering with line numbers
• Headless pipe mode for one-shot automation:
  • -p reads prompt from stdin or --prompt
  • --output-format text|json|stream-json
• Production-readiness tracking page for the active P0/P1/P2 release matrix

Quick start

Requirements: 64-bit Node.js 22.13 or newer on the 22.x line, Node.js 24, or Node.js 26. Node.js 24 LTS is recommended. A normal install does not require Python or Visual Studio Build Tools.

User install:

npm install -g @tritard/waterbrother --ignore-scripts
waterbrother

If an upgrade from 0.16.165 or earlier reports better-sqlite3, node-gyp, or Visual Studio errors, close any running Waterbrother processes and repair the stale global install:

npm uninstall -g @tritard/waterbrother
npm install -g @tritard/waterbrother@latest --ignore-scripts

The EPERM ... rmdir cleanup warning can appear after the native dependency has already failed; it is not the root cause. Closing processes that still hold the old global package directory and retrying clears it.

Waterbrother stores sessions in portable JSONL files and does not install native addons. Existing sessions.db data is migrated once, verified record-for-record, and retained as the active fallback if verification does not succeed.

Partners and maintainers ship updates through GitHub Actions, not from personal laptops. The package publish workflow runs only on stable version tags. During the current registry-access recovery, only the final publish step receives the repository's NPM_TOKEN; keep that token granular, package-scoped, and short-lived, then revoke it after npm Trusted Publishing is configured.

Source install for contributors:

git clone https://github.com/PhillipHolland/waterbrother.git
cd waterbrother
npm install --ignore-scripts
npm link

Start interactive mode (first run launches onboarding wizard):

waterbrother --approval on-request

One-shot prompt:

waterbrother "inspect this project and explain the structure"

Non-interactive command forms:

waterbrother exec "summarize the repository architecture"
waterbrother review "review changed files for bugs and missing tests"
waterbrother resume --last "continue and finish the previous task"

Vision/web design prompt with local image:

waterbrother vision ./mockup.png "Suggest concrete CSS and layout improvements"

Git workflow:

waterbrother commit               # stage, diff, generate commit message, confirm
waterbrother commit --push        # same as above, then push
waterbrother pr                   # commit, push, generate PR title+body, create via gh
waterbrother pr --branch=my-feat  # create branch first if on main, then PR

Utility commands:

waterbrother doctor
waterbrother listen --tailscale
waterbrother local
waterbrother local status
waterbrother models list
waterbrother models catalog
waterbrother models status
waterbrother runtime-profiles list
waterbrother channels status
waterbrother gateway status
waterbrother mcp list
waterbrother onboarding
waterbrother update

Local model setup

Waterbrother can load an already downloaded GGUF itself using an installed llama-server, or connect to an existing local model server instead of a hosted API.

Fastest path:

waterbrother local

The first choice loads a downloaded model with Waterbrother managing the engine process. Other choices connect to Ollama or an existing OpenAI-compatible server.

If you are already inside Waterbrother interactive mode, use:

/local
/local status

Managed downloaded models

Install the llama.cpp server separately and make llama-server available on PATH, or set WATERBROTHER_LLAMA_SERVER to its executable path. This feature does not download or execute an installer automatically and does not add a native npm dependency.

waterbrother local list
waterbrother --local-model "path/to/model.gguf"

Inside a session, use /local load [path] to load a model, /local save to make it the startup default, and /local stop to unload it. Saying use my local model also opens the load flow. With a saved model, waterbrother --local explicitly selects it even when resuming a different runtime.

Discovery checks ~/.waterbrother/models, ~/.cache/llama.cpp, and ~/.lmstudio/models. One discovered model is selected automatically; multiple models prompt for a choice. Explicit paths work for other locations. Standalone waterbrother local load <path> verifies the engine and saves the default, then closes that verification process.

The managed server binds only to loopback, uses a random per-process API token, and stops when its owning Waterbrother process exits normally. Existing servers are not stopped. Separate Waterbrother processes currently load separate engines, so avoid opening multiple managed sessions if GPU memory is limited. Initial weight loading and the first full-agent prompt can take longer than later turns. Optional --no-gateways skips Telegram/Discord autostart for one run without changing saved channel settings.

Ollama

waterbrother config set provider ollama
waterbrother config set baseUrl http://127.0.0.1:11434/v1
waterbrother config set model ollama/qwen3:14b
waterbrother models status
waterbrother models list

Notes:

• No API key is required for Ollama by default.
• waterbrother models list asks your local Ollama server for the currently available models.
• waterbrother models catalog still shows the built-in Waterbrother catalog if you want suggested defaults.

Local OpenAI-compatible servers (LM Studio, local gateways, etc.)

waterbrother config set provider openai-compatible
waterbrother config set baseUrl http://127.0.0.1:1234/v1
waterbrother config set model openai-compatible/your-local-model-id
waterbrother models status
waterbrother models list

Notes:

• No API key is required for local OpenAI-compatible servers unless your server specifically expects one.
• This is the path to use for tools like LM Studio or any local endpoint that exposes an OpenAI-style /v1/chat/completions API.

If you are using Discord and want native slash commands to appear immediately in one server, set channels.discord.guildId before running waterbrother discord sync-commands.

Web research examples:

waterbrother "Read https://docs.anthropic.com/en/api/messages and summarize tool use"
waterbrother "Search the web for the latest model provider docs about tool calling and cite the sources"

# interactive
/provider
/provider anthropic
/providers
/runtime
/channels
/gateway
/onboarding telegram
/runtime-profile save review-anthropic
/runtime-profile load review-anthropic
/runtime-profiles
/model anthropic/claude-sonnet-4-20250514
/models
/models all

# config
waterbrother config set provider anthropic --scope project
waterbrother config set model anthropic/claude-sonnet-4-20250514 --scope project

# inspect runtime
waterbrother models status
waterbrother runtime-profiles show review-anthropic
waterbrother channels status
waterbrother gateway status

# interactive
/read https://docs.anthropic.com/en/api/messages
/search latest model provider tool calling docs
/open 1

Messaging foundation

Waterbrother now includes the first messaging-control foundation.

• Services targeted first:
  • Telegram
  • Discord
  • Signal
• Current scope:
  • normalized channel config
  • gateway/channel readiness reporting
  • service-specific onboarding
• Live now:
  • Telegram single-user remote control
• Not shipped yet:
  • Discord live adapter
  • Signal live adapter
  • group DM collaboration

Use the new commands to prepare and validate channel setup:

waterbrother channels list
waterbrother channels status
waterbrother channels show telegram
waterbrother gateway status
waterbrother gateway pairings
waterbrother gateway pair telegram <user-id>
waterbrother gateway run telegram
waterbrother onboarding telegram
waterbrother onboarding discord
waterbrother onboarding signal

Rollout order:

1. single-user remote terminal control
2. status and observation from linked channels
3. approvals over messaging
4. only then group DM collaboration

Shared project foundation is now live:

• enable it with waterbrother project share
• inspect it with waterbrother room status
• control conversation vs execution with waterbrother room mode chat|plan|execute
• manage collaborators with waterbrother room members, waterbrother room invites, waterbrother room invite, waterbrother room invite accept, and waterbrother room remove
• inspect recent collaboration activity with waterbrother room events
• manage the shared backlog with waterbrother room tasks, waterbrother room task add, and waterbrother room task move
• assign, claim, and discuss shared work with waterbrother room task assign, waterbrother room task claim, waterbrother room task comment, and waterbrother room task history
• choose a shared execution preset with waterbrother room runtime <profile>
• claim or release the shared operator lock with waterbrother room claim and waterbrother room release
• shared project metadata lives in .waterbrother/shared.json
• human collaboration notes live in ROUNDTABLE.md

Waterbrother self-awareness is now live:

• waterbrother about
• waterbrother capabilities
• waterbrother project-map
• waterbrother state
• interactive:
  • /about
  • /capabilities
  • /project-map
  • /state
• Waterbrother now writes .waterbrother/self-awareness.json
• local questions like what is roundtable? are answered from repo state before generic model fallback

Current Telegram behavior:

• if the TUI is open, Telegram prompts are injected into the live TUI session and the work is visible in the terminal
• if no live TUI session is attached, Telegram falls back to a remote run with approval=never
• Telegram now exposes self-awareness directly with /about and /state
• replies are rendered as Telegram-safe HTML, with code blocks and stripped raw Markdown symbols
• the gateway sends typing activity and edits one in-progress message into the final reply before falling back to chunked follow-up messages
• pending pairings are explicit and expire automatically after 12 hours unless approved
• paired Telegram users drive the same live session and permissions as the terminal operator when the TUI bridge is attached
• Telegram now supports remote workspace control with /project, /project use <path|name>, /project new <name>, /project share, plus the lower-level /cwd, /use <path>, /desktop, and /new-project <name> commands
• Telegram owners can pair visible chat participants conversationally or with /pair <user-id|@username>, and owner requests like “add Austin as editor” now pair the person if needed and add them to the shared project directly
• Telegram also answers live state questions from room state now, including prompts like “is Austin paired?”, “is Austin in the project?”, “who is in the room?”, and “what project is this chat bound to?”
• Telegram owners can also use conversational project and member requests like “share this project in this chat”, “switch to TelegramTest”, or “add Austin as editor”, and Waterbrother routes those through the same project and shared-room actions
• In Telegram groups, directly addressed execution requests now run conversationally in execute mode when the operator lock is held; /run <prompt> remains the explicit execution form
• shared projects now support /room, /events, /members, /invites, /whoami, /people, /tasks, /mode, /claim, /release, /invite, /accept-invite, /approve-invite, /reject-invite, /remove-member, /room-runtime, and /task ... from Telegram
• Telegram now supports /whoami for Telegram-id and shared-room membership visibility, plus /events for recent shared-room activity
• /room now includes pending invite count plus task ownership summaries
• local /status now includes sharedRoom with pending invites, task ownership summary, and recent shared-room event activity
• the TUI now prints a small Roundtable event feed when new shared-room activity lands
• Telegram now posts a Roundtable ownership notice when shared task ownership changes via assign/claim/move
• shared Telegram execution only runs when the shared room is in execute mode
• room administration is owner-only, and only owners/editors can hold the operator lock
• /room status now shows the active executor surface plus provider/model/runtime identity
• repo-first concept resolution now covers Waterbrother itself, Roundtable, Telegram, shared rooms, the gateway, runtime profiles, approvals, and sessions
• collaboration how-to questions now answer from local state too, including:
  • how to invite a partner
  • how to share the current project
  • how to make a new project
• in Telegram groups, Waterbrother only responds when directly targeted: slash commands, @botname mentions, or replies to a bot message
• in Telegram groups, directly targeted messages are now classified as chat, planning, or execution; explicit execution should use /run <prompt>
• in Telegram group chat or plan flows, targeted Waterbrother/project questions are now answered directly from local repo state instead of returning only a generic planner hint
• in shared plan-mode groups, targeted task: and todo: messages are captured directly into the Roundtable task queue
• pairing is now explicit: first DM creates a pending request, then approve locally with waterbrother gateway pair telegram <user-id>

Release flow

Partners should ship updates by pushing a version tag, not by running npm publish locally.

1. Until npm Trusted Publishing is configured, store a granular, package-scoped publish token as the NPM_TOKEN repository secret. The workflow exposes it only to the publish step. Replace and revoke this token after configuring a GitHub Actions trusted publisher for PhillipHolland/waterbrother and publish.yml.
2. If you already committed the feature/docs slice, run one command from a tracked-clean repo:

npm run release:patch

That command now:

• bumps the patch version
• commits package.json and package-lock.json
• tags the release
• pushes main
• pushes the release tag
• waits until the npm registry reports the new version

3. If you want the feature plus version bump to ship as one release commit, skip the separate feature commit and run:

npm run release:patch:tracked

That mode now prints the exact tracked files it will ship and asks for confirmation before proceeding. It stages the current tracked worktree slice plus release metadata into the single Release vX.Y.Z commit. It ignores the repo's local checkpoint noise, but it still excludes untracked scratch files.

If you already know you want that tracked slice, use the explicit non-interactive form:

npm run release:patch:tracked:yes

For non-patch releases, use:

npm run release:ship -- minor
npm run release:ship -- major
npm run release:ship -- 0.16.200
npm run release:minor:tracked
npm run release:major:tracked
npm run release:minor:tracked:yes
npm run release:major:tracked:yes

GitHub Actions publishes from .github/workflows/publish.yml only after lifecycle-script-free installation, dependency signature and deny-list checks, production audit, source smoke tests, and a packed global-install smoke test pass. npm registry signatures remain verifiable. Public provenance attestations are not available while the source repository is private; do not enable --provenance unless the repository becomes public.

Users update with:

npm install -g @tritard/waterbrother@latest --ignore-scripts

This lets partners such as Umair and Austin ship releases without using the publisher's local machine or Touch ID.

Long-running session controls:

# inside interactive mode
/compact
/compact 32
/cost
/fork
/diff
/run inspect the project and summarize the architecture
/receipt-mode
/receipt-mode off
/contract
/receipts
/receipt last
/checkpoints
/rewind
/memory init
/memory add Always run tests before final answer.
/memory reload

# config tuning
waterbrother config set autoCompactThreshold 0.9
waterbrother config set traceMode verbose
waterbrother config set receiptMode verbose
waterbrother config set provider openai --scope project
waterbrother config set model openai/gpt-4.1 --scope project
waterbrother config set-json approvalPolicy '{"autoApprovePaths":["src/**"],"askPaths":["package.json"],"denyShellPatterns":["git\\s+reset\\s+--hard"]}' --scope project
waterbrother config set-json verification '{"commands":["npm run lint","npm test"],"timeoutMs":180000}' --scope project
waterbrother config set-json mcpServers '{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","."]}}' --scope project

Pipe mode examples:

printf 'summarize this repo' | waterbrother -p
printf 'read https://example.com and summarize it' | waterbrother -p --output-format json
printf 'inspect package.json' | waterbrother -p --output-format stream-json

Config scope notes:

• waterbrother config set ... defaults to user scope (~/.waterbrother/config.json)
• add --scope project to save repo-local overrides in .waterbrother/config.json
• waterbrother config get ... and waterbrother config list default to merged runtime values

MCP setup example:

waterbrother config set-json mcpServers '{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","."]}}' --scope project
waterbrother mcp list

Task console

Waterbrother treats serious work as tasks, not chat turns.

Commands

| Command | Description | |---------|-------------| | /feature <name> | Start a new task (creates branch, sets up tracking) | | /tasks | List recent tasks | | /task | Show active task details | | /decide [goal] | Run decision pass — get structured implementation options | | /choose <option> | Choose a decision option and lock contract | | /redecide | Clear decision and re-plan | | /surgeon <paths...> | Set contract scope directly, skip /decide | | /build <prompt> | Execute within task contract | | /review | Show structured review panel | | /challenge | Adversarial re-review of last changes | | /accept | Accept reviewed changes | | /tighten <paths...> | Narrow contract scope | | /close | Close the active task | | /panel | Show/toggle operator panel |

Typical flow

/feature auth-rework
/decide add Google login without breaking auth API
/choose minimal
/build implement the adapter layer
/review
/accept
/close

Supported in this release:

• stdio MCP servers
• automatic tool discovery at startup
• tool routing through normal approval + trace flow
• interactive inspection with /mcp