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, xAI, and compatible APIs.

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

• 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
• 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

User install:

npm install -g @tritard/waterbrother
waterbrother

Partners and maintainers ship updates through GitHub Actions, not from personal laptops. The package publish workflow runs on version tags and uses the repository NPM_TOKEN secret.

Source install for contributors:

git clone https://github.com/PhillipHolland/waterbrother.git
cd waterbrother
npm install
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 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

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. Add an npm publish token as the repository secret NPM_TOKEN. The token must be able to publish @tritard/waterbrother.
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 still publishes from .github/workflows/publish.yml after npm ci, npm run check, and npm run smoke pass.

Users update with:

npm install -g @tritard/waterbrother@latest

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