macOS desktop
The main window, sidebar, terminal dock and settings, plus menu bar controls, the CLI and ~/.brewping.
What the app looks like
BrewPing on macOS is a single main window: sidebar on the left, conversation in the middle, an optional terminal dock at the bottom, and a settings sheet that opens on top. A menu bar item takes over when the window is closed, keeping the service reachable from your phone.
Main window
The window opens at 1080 x 720 by default with the system title bar. From top to bottom it is: an error banner when something fails, the top bar, the conversation area, and the terminal dock when it is open.
| Region | What is in it |
|---|---|
| Sidebar | Brand row with a live status dot (ONLINE / STARTING… / OFFLINE), New Chat, then the conversation list. Filter by All conversations or By directory, and archived items live in their own section. Settings & pairing sits at the bottom. |
| Top bar | Switch agent, pick model (or Follow agent config), approval mode (safe / ask all / auto), and a terminal toggle for the dock. |
| Conversation | Messages with the agent. The composer reads “Message {agent}, or send from your phone / watch…”; while it is working you see “{agent} is thinking…” and a Stop generating button. With nothing open: “{agent} on standby” and “Type below, or send from iPhone / Apple Watch”. |
| Terminal dock | Raw output of the current agent, titled “{agent} terminal”, with Clear and Collapse. It is off by default. |
Settings
Click Settings & pairing in the sidebar, or use the menu bar. The sheet has five sections:
| Section | Contents |
|---|---|
| General | Interface language, the setup wizard entry, and the trademark notice |
| This Mac | Device name, LAN address, port and service status |
| Model config | Model providers and their credentials |
| Environment & CLI | Detected runtime and CLI agents |
| Pairing | Pairing code and paired devices |
First-run wizard
On first launch a wizard walks through welcome, environment check, Node, agents and models, then finishes. You can choose Skip for now — if you do, a slim banner stays at the top of the conversation area until setup is completed, and you can reopen the wizard from General settings.
Menu bar
The menu bar panel shows a status dot and up to four read-only rows — device name, LAN address, port and service status, where the address and port only appear once the service is up — followed by three buttons:
| Item | What it does |
|---|---|
| Show pairing code (显示配对码) | Reveals the current code, opens the main window on the Pairing section |
| Open main window | Brings the main window forward |
| Quit BrewPing | Terminates the app and stops the service |
Command line
The brewping binary exposes six subcommands. Anything unrecognised prints usage and exits with code 1.
| Command | Behaviour | Timeouts |
|---|---|---|
| brewping start | Starts a PTY session; reuses an existing agent | 60s overall, 200ms poll, 90s restart request |
| brewping status | Prints Status / PID / Session / HTTP | 5s socket timeout |
| brewping send <text> | Sends text into the running session | 60s Unix socket timeout |
| brewping stop | Stops the session and waits for exit | 30s request timeout, up to 20s waiting for exit |
| brewping attach | Attaches your terminal to the live session | 10s ack timeout |
| brewping agent | Runs the built-in agent daemon | — |
# Start a session and check it
brewping start
brewping status # exit code 0 = running
# Send one task
brewping send "Refactor auth middleware, add rate limiting"
# Attach to the live terminal (Ctrl+D detaches)
brewping attach
# Stop
brewping stopTerminal attach
- Attach sends {"cmd":"attach"} over the Unix socket and waits for an ack containing the session id.
- On attach, the last 131072 bytes of output are replayed so you see the current screen immediately.
- Output is polled every 20ms, giving byte-for-byte streaming.
- Press Ctrl+D (byte 0x04) to detach — the session keeps running. "Detached." is printed and the command exits 0.
- The header line reads: Attached to session <first 8 chars> (Ctrl+D to detach).
Inside ~/.brewping
| File | Contents |
|---|---|
| session.json | Session info: id, pid, agent pid, cwd, status, createdAt, exitCode, httpPort, httpIP |
| agent.sock | Unix socket used by start / send / stop / attach |
| agent.log | Agent stdout and stderr, mode 0644 |
| opencode.log | OpenCode output |
| pairing.json | Pairing token, mode 0600 |
| device.json | Device identity |
| approval.json | Global approval mode |
| config.json | Default agent and model preferences |
| workdirs.json | Per-agent working directory preferences |
| commands/ | One JSON file per command |
| conversations/ | Stored conversations |
Service discovery
The Mac advertises itself on the local domain as service type _brewping._tcp. with the default name "BrewPing Agent". The TXT record carries:
| Key | Value |
|---|---|
| version | 0.1 |
| agent | The currently active agent id |
| platform | macOS |
| protocolVersion | 1 |
| deviceId / deviceName | Present when available |
Terminal rendering
Raw PTY output is fed into a character grid of 40 rows by 120 columns. Control characters and escape sequences are interpreted so that what you see is the terminal screen as it would look in a real terminal, not an append-only log. A session that exits reports exit code 127 when the executable could not be launched.