robbin / grokbot-local-agent

# 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.
## Why this exists
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.
## How it works
`bin/pi-task` wraps a call in a task with an ID, status and artifacts under
`~/.pi/tasks/ /`. 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 `
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.
 [code] 
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.
## Scope and limitations
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.
## Repository layout
| Path | Purpose |
| --- | --- |
| `bin/pi-call.mjs` | One-shot RPC client: starts Pi, sends a prompt, waits for agent_settled and prints the final reply. Node 22+, no third-party dependencies. |
| `bin/pi-run` | Synchronous shortcut with a fixed model, high thinking and read/write/exec tools. |