waterbrother

A local coding CLI that connects to Grok (api.x.ai) with codex/claude-style interactive workflows, local tool calls, session persistence, and approval controls.

Web docs interface

This repo includes a static docs web interface:

• / landing page
• /onboarding onboarding + API key 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 API key
  • offers opening https://console.x.ai/
  • prompts for default model and agent profile
• Grok API integration (/chat/completions)
• 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)
• 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 mcp list
waterbrother onboarding
waterbrother update

Web research examples:

waterbrother "Read https://console.x.ai and summarize how to create an API key"
waterbrother "Search the web for the latest xAI API docs about vision support and cite the sources"

# interactive
/read https://console.x.ai/
/search latest xAI vision docs
/open 1

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. Bump the package version locally:

npm version patch

Use minor or major when appropriate.

3. Push main and the new tag:

git push origin main --tags

4. GitHub Actions runs .github/workflows/publish.yml and publishes the package after npm ci, npm run check, and npm run smoke pass.

5. 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 model grok-4.20-beta-0309-reasoning --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