grokbot-tui

Terminal chat for your Grok Bot bots and channels.

This is not an official xAI or Cursor product. There is no public Grok Bot chat API. The TUI posts to the host gateway (POST {gatewayUrl}/api/{method} with a bearer token). Command names and response shapes can change without notice. Treat the gateway token and every transcript as secrets.

• Node.js 22 or newer
• An interactive terminal (TTY)
• Ghostty if you want host images drawn with Kitty graphics (other terminals show placeholders)

npm install -g grokbot-tui
grok-tui

Without a global install:

npx grokbot-tui

From a clone:

git clone https://github.com/smarzban/grokbot-tui.git
cd grokbot-tui
npm install
cp .env.example .env
npm start

npm start -- --mock
# or: npm run start:mock
# or: grok-tui --mock

The mock host includes Ada, a channel, and a sample photo so you can exercise the lobby, chat, scroll, and images without a live gateway.

Pick one path. Do not put port 1340 on the public internet.

1. Open Grok Bot and sign in.
2. Allow the Keychain prompt for "Grok Bot Safe Storage" when asked.
3. Run grok-tui or npm start with no token in .env.

The TUI reads ~/Library/Application Support/Grok Bot/gateway-descriptor.json, decrypts the session, and keeps the gateway URL path (only a trailing slash is trimmed). A GROKBOT_GATEWAY_URL alone, without a token, does not block this desktop path.

Put both values in .env:

GROKBOT_GATEWAY_URL=http://127.0.0.1:1340
GROKBOT_GATEWAY_TOKEN=...

GROKBOT_GATEWAY_URL=http://<tailscale-or-localhost-tunnel>:1340
GROKBOT_GATEWAY_TOKEN=...

Optional: GROK_TUI_DEFAULT_AGENT=Ada opens that bot or channel and skips the lobby.

Connectivity check is listAgents. There is no separate health probe.

• Open the lobby and pick a bot or a channel (channels show members)
• Chat in a framed alternate-screen UI
• In a 1:1 chat, wait for the reply (default wait cap is 10 minutes; Esc cancels the wait and asks the host to interrupt when supported)
• In a channel, send without blocking; idle poll picks up each member's turn and "X is answering…" when a member is running
• Scroll history with PageUp / PageDown, the wheel, Home / End, and Ctrl+u / Ctrl+d
• Mention channel members with @ plus a prefix; Tab or Enter inserts @Name
• Paste a local image path as the message text to draw it in Ghostty
• Leave chat for the lobby with Esc (when not waiting) or Ctrl+b

Out of scope in v1: creating or deleting agents or channels, seating members, streaming replies, Slack, rich markdown, and uploading attachments from the compose box.

Footer in chat: Enter send · Esc lobby · Ctrl+c quit.

See .env.example. Never print, log, or commit GROKBOT_GATEWAY_TOKEN or the desktop session payload. Only these names are read (legacy SAND_* / GROK_BOT_* names are ignored).

Ghostty speaks the Kitty graphics protocol. You do not need viu, chafa, or a Ghostty config toggle.

• Host attachments and bot images are fetched through the gateway (readAttachmentImage for box paths such as /home/box/sand-data/...), cached under the system temp dir, then painted when the full image block is on screen.
• Paste a local image path as the message to draw that file the same way.
• Filename-only turns stay [image] filename.
• iTerm and Terminal.app usually show placeholders, not Kitty placements.

npm start -- --mock seeds Ada with fixtures/mock-photo.png and a name-only placeholder so you can check both paths.

• Tokens stay in memory (env or desktop session). They are not written to logs or the UI.
• Error text redacts bearer tokens and GROKBOT_GATEWAY_TOKEN=… fragments.
• The TUI shows transcript text only, not raw gateway payloads.
• Destructive host commands (deleteAgent, box reset, and similar) are not exposed.

npm start          # tsx src/cli.tsx
npm run start:mock
npm test
npm run typecheck
npm run build      # writes dist/ for the grok-tui bin

Tests cover the mock host, scripted gateway fetch, desktop Keychain decrypt, layout/compose/keys/mouse, poll/roster, config, and chat poll snapshots. Full Ink screen renders are not in CI yet.

1. Update CHANGELOG.md and bump package.json / package-lock.json.
2. Commit on main, tag vX.Y.Z, and push the branch and tag.
3. The release workflow runs tests, publishes to npm via a Trusted Publisher, and opens or updates the GitHub release from the changelog section.

Trusted Publisher on npm must match this repo exactly: owner smarzban, repository grokbot-tui, workflow filename release.yml. The workflow uses Node 24 (npm ≥ 11.5.1) for OIDC publish — do not set NODE_AUTH_TOKEN / NPM_TOKEN in that job.

CI on pull requests uses .github/workflows/ci.yml.