sand

Unofficial terminal bridge for Grok Bot.

Grok Bot does not ship a CLI that can message your agents. sand is a small workaround:

1. sand "do the thing" queues a prompt into ~/.sand/inbox/
2. A Grok Bot routine (every minute) picks it up and runs it in the target chat
3. sand ls / sand fetch read a local catalog synced from your agents

Built by a Grok Bot agent, for people who live in the terminal.

Not affiliated with xAI / Cursor. Unofficial bridge. The app has no public send-message API yet — when it does, this can go away.

Install

git clone https://github.com/alokwhitewolf/sand.git
cd sand
./install.sh

Or:

curl -fsSL https://raw.githubusercontent.com/alokwhitewolf/sand/main/install.sh | bash

Make sure ~/.local/bin is on your PATH.

One-time agent setup

The CLI alone only writes files. Your Grok Bot agent must drain the inbox.

Follow agent/SETUP.md and paste the routine from agent/ROUTINE.md into the agent that should receive prompts.

Usage

# list chats/agents (after first routine sync)
sand ls

# send to the active/default agent
sand "summarize what we did today"

# send to a specific chat
sand --to sandbox-test "hello"
sand to sandbox-test "hello"

# fetch recent messages from the local cache
sand fetch -n 20
sand fetch sandbox-test -n 10

# inbox / sync status
sand status

# optional: focus the Grok Bot app too
sand --open "ping"

# thread under a message id when useful
sand --to active --reply-to t5u "follow up"

How it works

terminal                         Grok Bot agent
────────                         ──────────────
sand "…"  →  ~/.sand/inbox/id.json
                ↑ poll ~1/min
             routine reads inbox
             runs the prompt in chat
             syncs agents.json + transcript cache
sand ls / fetch  ←  ~/.sand/agents.json + cache/

Each Grok Bot agent is one 1:1 chat. Targeting a "conversation" means targeting that agent id/name.

Layout

~/.sand/
  inbox/     queued prompts from the CLI
  archive/   processed prompts
  outbox/    reserved for agent → CLI replies
  agents.json
  cache/<agentId>/transcript-tail.json

Requirements

• macOS (uses pbcopy-free path; open for optional app focus)
• Grok Bot installed and signed in
• The inbox routine running on at least one agent

License

MIT