grokbot-local-agent

Hand heavy work from Grok Bot to a local coding agent—and wake the Bot back up when the job is done.

English | 简体中文

A small set of scripts that lets Grok Bot delegate work to Pi on the same machine, then use a webhook to wake the Bot for verification and reporting. Here, “local” means local to the Bot's Linux cloud computer, not your personal Mac.

Documentation and agent templates are maintained in English. Bots should still respond in the user's preferred language.

Heavy Grok Bot usage can consume a subscription allowance quickly. Batch file edits, coding, long document drafts and research can instead run through Pi using the user's separate model account.

Simply starting a background agent is not enough:

• The worker does not automatically send its final answer back to the Bot.
• A long-running task may finish after the Bot's conversation turn has ended.
• Without durable tracking and a wakeup, neither the Bot nor the user knows whether the delegated work succeeded.

bin/pi-task wraps a call in a task with an ID, status and artifacts under ~/.pi/tasks/<ID>/. On completion it sends only {source, id, owner, state, exit_code} to a webhook. A routine wakes the Bot, which reads the files, verifies the outcome, reports it and acknowledges the task.

Each task records the dispatching Bot's agent ID using run --owner <agent-id> or PI_TASK_OWNER. If neither is supplied, owner is null and a warning is emitted. Owner-filtered pending, list and ack help keep Bots from reporting each other's work. Always pass --owner when acknowledging: an unfiltered ack does not enforce ownership.

flowchart TD
  B["Grok Bot"] -->|"Shell background mode"| T["pi-task run<br/>~/.pi/tasks/ID/"]
  T -->|"stdin: prompt / abort"| P["pi --mode rpc<br/>configured working directory"]
  P --> F["Files / shell / web tools"]
  P -->|"stdout: events"| T
  T -->|"POST id / owner / state / exit_code"| W["Webhook"]
  W --> R["Routine wakes Bot"]
  R --> B
  B --> Q["pi-task pending --owner own-id"]
  Q --> V["Verify result.md / git diff / tests"]
  V --> S["Report to user"]
  S --> A["pi-task ack --owner own-id"]
  T -.->|"Recover missed notifications"| Q

Notifications optimize latency; disk state is the source of truth. After a missed webhook, restart or interrupted conversation, the next wakeup can recover unreported outcomes using pi-task pending. Do not rerun work just because a notification was missed.

This is a lightweight second pair of hands on the Bot's machine, not an isolated worker service. Do not assume the cloud computer provides a dedicated VM sandbox, unlimited process lifetime or strong permission isolation.

The author's workflow uses three layers:

1. Grok Bot: conversation, orchestration, connectors and verification.
2. Pi: batch edits, small scripts, drafts and research.
3. Cursor Cloud Agent, when available: larger projects intended for ongoing development and GitHub delivery.

That is a workflow preference, not a requirement or guarantee of any provider's features. Long-running project work may be better served by a dedicated cloud coding environment than by maintaining this notification chain.

Run these steps on the Bot's computer. See the setup guide for details. UI labels, provider availability and approvals may vary by host.

Install Node in your user environment if it is not already available; the PATH below assumes a Node installation at ~/.node22. No sudo is needed.

export PATH=$HOME/.node22/bin:$HOME/.local/bin:$PATH
node --version
npm i -g --prefix ~/.local @earendil-works/pi-coding-agent
pi --version && which pi

Run pi in an interactive terminal, enter /login, select the subscription option/provider offered by your installation, and complete the authorization. Do not ask an agent to inspect or copy ~/.pi/agent/auth.json. pi --list-models deepseek lists models without exposing credentials; the smoke test below checks actual execution.

The current default is deepseek/deepseek-flash. Choose a model available to your account; pi-task run --model provider/model supports overrides.

From this repository:

mkdir -p ~/tools/pi-call && cp -a bin/. ~/tools/pi-call/
chmod +x ~/tools/pi-call/pi-run ~/tools/pi-call/pi-call.mjs ~/tools/pi-call/pi-task ~/tools/pi-call/pi-task.mjs

Wrappers locate their .mjs files beside themselves and add ~/.local/bin to PATH. Ensure both node and pi are available to the Bot's shell. Persist the appropriate PATH in your shell setup. The fixed pi-run model is set in that wrapper.

~/tools/pi-call/pi-run /tmp "Reply with only OK" --timeout 120
echo "exit=$?"

Expect OK and exit=0.

Create a webhook-triggered routine using the template. Store its URL and raw Bearer token using the host's secure input facility as PI_NOTIFY_URL and PI_NOTIFY_SECRET, not in files or prompts.

Dispatch with --owner YOUR_AGENT_ID; obtain your Bot's ID from its profile location, such as /home/box/agent-data/agents/YOUR_AGENT_ID/profile.json. Run the end-to-end check and verify both the notify event and the Bot's verified report.

Install skills/pi-agent/SKILL.md as a Bot skill, or include its rules in the Bot's instructions.

tools/pi-telegram-monitor/ pushes Pi sessions to a Telegram private chat in real time, so you can follow delegated work from your phone:

• One progress message per session, edited in place: the instruction, tool calls with argument summaries, reply previews and a status (running / done).
• A separate result message with the full final reply, split into parts if long.
• Send-only: it never reads updates or accepts commands from Telegram.
• Likely secrets (API keys, GitHub tokens, Bearer values, bot tokens, long hex/base64 strings) are masked before sending; thinking and tool output bodies are not sent.

Setup:

1. Create a bot with @BotFather and copy its token.
2. Message the bot once and find your numeric chat ID.
3. Store TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID with the host's secure input facility, not in files or prompts.
4. Copy the directory to the Bot's computer and run ./start.sh.

start.sh is idempotent. To survive restarts, call it from an existing periodic routine or startup check whose shell has both variables; if the token is not available there, skip rather than writing it to a file.

MIT.