⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.0.1

grok-bot

adamanz@adamanz⭐ 17 stars· last commit 8d ago· 0 open issues

>-

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 17 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Grok Bot Skill

License: MIT Agent Skill skills.sh Install

Cursor / Claude Code / Codex skill to chat with Grok Bot teammates and create new Grok Bots from the terminal — without clicking through the desktop UI.

This is the xAI Grok Bot desktop app (cloud computer + named teammates). It is not the Cursor Cloud Agents API (api.cursor.com/v1/agents).

Install

npx skills add adamanz/grok-bot-skill -g -a cursor

Works with other agents too:

npx skills add adamanz/grok-bot-skill -g -a claude-code
npx skills add adamanz/grok-bot-skill -g -a codex
npx skills add adamanz/grok-bot-skill --all

Or clone it yourself:

git clone https://github.com/adamanz/grok-bot-skill.git ~/.cursor/skills/grok-bot

Then ask Cursor: “list my Grok Bots” or “message Reed”.

Requirements

  • macOS with the Grok Bot desktop app installed and signed in
  • An eligible plan (SuperGrok Heavy, Cursor Ultra, or Cursor Teams Premium)
  • Python 3.10 or newer, plus macOS security and openssl commands. No pip packages are needed.

The CLI uses your local Grok Bot session. It never prints tokens, gateway URLs, or Keychain material.

What you can do

CommandPurpose
statusSign-in + cloud computer health
listList Grok Bot teammates
chatSend a prompt and wait for a reply
sendFire-and-forget a prompt
createSpin up a new named Grok Bot
updateEdit name, title, or standing rules
transcriptRead recent conversation
SCRIPT="$HOME/.cursor/skills/grok-bot/scripts/grokbot.py"

python3 "$SCRIPT" status
python3 "$SCRIPT" list
python3 "$SCRIPT" chat --name Reed --prompt "What are you waiting on from me?"
python3 "$SCRIPT" create --name Reed --title "Chief of staff" \
  --description "Draft-only daily brief. Never send messages."

See examples.md for more prompts and SKILL.md for agent instructions.

Both send and chat return a messageId and accept --message-id UUID. Reuse the same UUID, bot, and prompt when retrying uncertain delivery to avoid duplicate messages. Use a new UUID for each new message. To retain the ID even if the process is interrupted, generate it before sending:

MESSAGE_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
python3 "$SCRIPT" send --name Reed --prompt "Summarize your progress" --message-id "$MESSAGE_ID"

Keep MESSAGE_ID for retries. After a chat error during polling, check transcript before sending again. Without the original ID, a retry could send the message twice.

chat waits to observe the bot running and then becoming idle. Queued messages can leave the bot idle before work starts. If that transition is not observed within --timeout, output includes timedOut: true and the latest transcript. A very fast reply can finish between polls, so a timeout means completion is unconfirmed; inspect newEntries or use transcript before deciding to retry.

Session troubleshooting

The CLI reads both legacy scoped:v1: tokens and the active account in the newer cursor-accounts store. It does not choose an inactive saved account or fall back to a stale legacy token when a saved-account store is present.

If no saved session exists, open Grok Bot and sign in with Cursor. If the app is already signed in, fully quit and reopen it to save the session. For an unexpected-format error, update this skill and select your signed-in account in the app. Never paste sand-secrets.json or Keychain contents into an issue.

Development

Run the regression tests from the repository root:

python3 -m unittest discover -s scripts -p 'test_*.py' -v

Tests use synthetic credentials and simulated HTTP responses. They do not access your Keychain, contact Grok Bot, or send messages. OpenSSL is required for the encrypted-session fixtures.

Why this exists

Grok Bot teammates live on a shared cloud computer. The official path is the desktop app. This skill lets your coding agent:

  • message an existing bot and bring the reply back into chat
  • create a focused teammate (one job, standing rules, draft-only first task)
  • stay out of the Cursor Cloud Agents API when you asked for a Grok Bot

Safety

  • Do not paste passwords, API keys, or 2FA into prompts. Take over Agent Computer in the Grok Bot app instead.
  • Separate bots are not a security boundary — they share one computer.
  • The CLI decrypts the local session only to call the API. Treat sand-secrets.json and Keychain as secrets.

Discover

License

MIT

// HOW IT'S BUILT

// FILES

11 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md3.5 KBf5003000ebe1upstream ↗
    ---
    name: grok-bot
    description: >-
      Chat with Grok Bot teammates, message a named Grok Bot, create a new Grok Bot,
      list Grok Bots, read a Grok Bot transcript, or operate the xAI Grok Bot
      desktop app from Cursor, Claude Code, or Codex instead of the UI. Use when
      the user mentions Grok Bot, Grok teammates, Reed, Agent Computer, spinning
      up a new bot, or talking to Grok from the terminal.
    license: MIT
    metadata:
      author: adamanz
      version: "1.0.0"
      homepage: https://github.com/adamanz/grok-bot-skill
    ---
    
    # Grok Bot
    
    Talk to existing Grok Bot teammates and create new ones through the local CLI.
    Do not drive the Grok Bot desktop UI and do not call the gateway by hand.
    
    ## Workflow
    
    1. Run `status`, then `list`.
    2. Message an existing bot with `chat` (waits for a reply) or `send` (fire-and-forget).
    3. Create a new bot with `create` only when the user asked for a new teammate.
    4. Prefer one focused job per bot. Put standing rules in `--description`. Keep first tasks draft-only.
    
    The CLI is `scripts/grokbot.py` next to this file. Resolve that path from the
    installed skill directory (often `~/.cursor/skills/grok-bot/scripts/grokbot.py`).
    
    ```bash
    SCRIPT="$(dirname "$0")/scripts/grokbot.py"
    # or, after a global Cursor install:
    SCRIPT="$HOME/.cursor/skills/grok-bot/scripts/grokbot.py"
    
    python3 "$SCRIPT" status
    python3 "$SCRIPT" list
    python3 "$SCRIPT" chat --name Reed --prompt "What are you waiting on from me?"
    python3 "$SCRIPT" create --name Reed --title "Chief of staff" --description "Draft-only daily brief. Never send messages."
    python3 "$SCRIPT" transcript --name Reed --limit 20
    ```
    
    Output is JSON. Summarize it for the user. Never paste tokens, gateway URLs, or raw keychain material into chat.
    
    ## Create rules
    
    A new bot needs:
    
    - `--name` — short, unique
    - `--title` — one job, not "general helper"
    - `--description` — outcome, sources, and what it must not do without approval
    
    Do not create a second bot with the same name unless the user asks. The CLI refuses duplicates unless `--force` is passed.
    
    After create, send one concrete first task with `chat` unless the user only wanted the empty teammate.
    
    ## Chat rules
    
    - Resolve bots by `--name` when unique; use `--id` if names collide.
    - Use `chat` when the user expects an answer in this conversation.
    - Use `send` for long-running work the user will check in the Grok Bot app.
    - If `stillRunning` is true, say so and offer to poll again. Do not invent a reply.
    - Do not send passwords, API keys, or 2FA codes. Tell the user to take over **Agent Computer** in the Grok Bot app.
    - Do not approve local-computer access unless the user explicitly asked for it.
    
    ## Safety
    
    - The CLI decrypts the Grok Bot session from Keychain and `sand-secrets.json`. Treat that as a secret broker. Never print or log tokens.
    - All of a user's bots share one cloud computer. Do not treat separate bots as a security boundary.
    - This is not the Cursor Cloud Agents API (`api.cursor.com/v1/agents`). Do not create a coding cloud agent when the user asked for a Grok Bot.
    
    ## Troubleshooting
    
    | Symptom | What to do |
    |---|---|
    | Not signed in / unexpected token format | Ask the user to open Grok Bot and sign in with Cursor |
    | Keychain read failed | Ask them to unlock the login keychain and retry |
    | Access not granted | Eligible plans: SuperGrok Heavy, Cursor Ultra, Cursor Teams Premium |
    | Computer still starting | Wait and rerun `status` until box is running |
    | No bot with that name | `list` and confirm the name |
    
    If the CLI is missing a command the user needs, read `scripts/grokbot.py --help`. Do not invent new gateway routes in chat.
    
  • README.md3.1 KBd76fe44af019upstream ↗
    # Grok Bot Skill
    
    [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
    [![Agent Skill](https://img.shields.io/badge/Agent%20Skill-SKILL.md-111)](https://agentskills.io)
    [![skills.sh](https://skills.sh/b/adamanz/grok-bot-skill)](https://skills.sh/adamanz/grok-bot-skill)
    [![Install](https://img.shields.io/badge/install-npx%20skills%20add-000)](https://github.com/vercel-labs/skills)
    
    **Cursor / Claude Code / Codex skill** to chat with [Grok Bot](https://grok.com) teammates and create new Grok Bots from the terminal — without clicking through the desktop UI.
    
    This is the xAI **Grok Bot** desktop app (cloud computer + named teammates). It is **not** the Cursor Cloud Agents API (`api.cursor.com/v1/agents`).
    
    ## Install
    
    ```bash
    npx skills add adamanz/grok-bot-skill -g -a cursor
    ```
    
    Works with other agents too:
    
    ```bash
    npx skills add adamanz/grok-bot-skill -g -a claude-code
    npx skills add adamanz/grok-bot-skill -g -a codex
    npx skills add adamanz/grok-bot-skill --all
    ```
    
    Or clone it yourself:
    
    ```bash
    git clone https://github.com/adamanz/grok-bot-skill.git ~/.cursor/skills/grok-bot
    ```
    
    Then ask Cursor: **“list my Grok Bots”** or **“message Reed”**.
    
    ## Requirements
    
    - macOS with the **Grok Bot** desktop app installed and signed in
    - An eligible plan (SuperGrok Heavy, Cursor Ultra, or Cursor Teams Premium)
    - Python 3 (stdlib only — no pip packages)
    
    The CLI uses your local Grok Bot session. It never prints tokens, gateway URLs, or Keychain material.
    
    ## What you can do
    
    | Command | Purpose |
    |---|---|
    | `status` | Sign-in + cloud computer health |
    | `list` | List Grok Bot teammates |
    | `chat` | Send a prompt and wait for a reply |
    | `send` | Fire-and-forget a prompt |
    | `create` | Spin up a new named Grok Bot |
    | `update` | Edit name, title, or standing rules |
    | `transcript` | Read recent conversation |
    
    ```bash
    SCRIPT="$HOME/.cursor/skills/grok-bot/scripts/grokbot.py"
    
    python3 "$SCRIPT" status
    python3 "$SCRIPT" list
    python3 "$SCRIPT" chat --name Reed --prompt "What are you waiting on from me?"
    python3 "$SCRIPT" create --name Reed --title "Chief of staff" \
      --description "Draft-only daily brief. Never send messages."
    ```
    
    See [examples.md](examples.md) for more prompts and [SKILL.md](SKILL.md) for agent instructions.
    
    ## Why this exists
    
    Grok Bot teammates live on a shared cloud computer. The official path is the desktop app. This skill lets your coding agent:
    
    - message an existing bot and bring the reply back into chat
    - create a focused teammate (one job, standing rules, draft-only first task)
    - stay out of the Cursor Cloud Agents API when you asked for a Grok Bot
    
    ## Safety
    
    - Do not paste passwords, API keys, or 2FA into prompts. Take over **Agent Computer** in the Grok Bot app instead.
    - Separate bots are not a security boundary — they share one computer.
    - The CLI decrypts the local session only to call the API. Treat `sand-secrets.json` and Keychain as secrets.
    
    ## Discover
    
    - [skills.sh/adamanz/grok-bot-skill](https://skills.sh/adamanz/grok-bot-skill)
    - Search GitHub: `grok-bot skill`, `cursor grok bot`, `xai grok teammates`
    - Agent Skills spec: [agentskills.io](https://agentskills.io)
    
    ## License
    
    MIT
    
  • scripts/grokbot.py18 KBdaf2cc8d6a9cupstream ↗
    #!/usr/bin/env python3
    """Talk to Grok Bot teammates and create new ones. Never prints secrets."""
    
    from __future__ import annotations
    
    import argparse
    import base64
    import hashlib
    import json
    import subprocess
    import sys
    import time
    import urllib.error
    import urllib.request
    from pathlib import Path
    from typing import Any
    
    SECRETS_PATH = Path.home() / "Library/Application Support/Grok Bot/sand-secrets.json"
    BACKEND = "https://api2.cursor.sh"
    CLIENT_VERSION = "0.18.0"
    
    
    class GrokBotError(RuntimeError):
        pass
    
    
    def _die(message: str, code: int = 1) -> None:
        print(json.dumps({"error": message}), file=sys.stderr)
        raise SystemExit(code)
    
    
    def _decrypt_access_token() -> str:
        if not SECRETS_PATH.exists():
            raise GrokBotError(
                "Grok Bot is not signed in on this Mac. Open Grok Bot and sign in with Cursor first."
            )
        secrets = json.loads(SECRETS_PATH.read_text())
        stored = secrets.get("cursor-access-token")
        if not isinstance(stored, str) or not stored.startswith("scoped:v1:"):
            raise GrokBotError("Grok Bot access token is missing or in an unexpected format.")
        rest = stored[len("scoped:v1:") :]
        raw = base64.b64decode(rest[rest.index(":") + 1 :])
        if not raw.startswith(b"v10"):
            raise GrokBotError("Grok Bot access token is not in the expected v10 envelope.")
        try:
            password = subprocess.check_output(
                [
                    "security",
                    "find-generic-password",
                    "-s",
                    "Grok Bot Safe Storage",
                    "-a",
                    "Grok Bot Key",
                    "-w",
                ],
                text=True,
            ).rstrip("\n")
        except subprocess.CalledProcessError as exc:
            raise GrokBotError(
                "Could not read Grok Bot Safe Storage from Keychain. Unlock the login keychain and retry."
            ) from exc
        key = hashlib.pbkdf2_hmac("sha1", password.encode(), b"saltysalt", 1003, dklen=16)
        proc = subprocess.run(
            [
                "openssl",
                "enc",
                "-aes-128-cbc",
                "-d",
                "-K",
                key.hex(),
                "-iv",
                (b" " * 16).hex(),
                "-nopad",
            ],
            input=raw[3:],
            capture_output=True,
            check=False,
        )
        if proc.returncode != 0:
            raise GrokBotError("Failed to decrypt the Grok Bot access token.")
        plaintext = proc.stdout
        pad = plaintext[-1]
        if pad < 1 or pad > 16 or plaintext[-pad:] != bytes([pad]) * pad:
            raise GrokBotError("Failed to unpad the Grok Bot access token.")
        return plaintext[:-pad].decode()
    
    
    def _connect(access_token: str, service: str, method: str, body: dict[str, Any] | None = None) -> Any:
        url = f"{BACKEND}/{service}/{method}"
        headers = {
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json",
            "Connect-Protocol-Version": "1",
            "x-cursor-client-type": "sand",
            "x-cursor-client-version": CLIENT_VERSION,
            "x-sand-box-namespace": "prod",
            "x-ghost-mode": "false",
        }
        req = urllib.request.Request(
            url,
            data=json.dumps(body or {}).encode(),
            headers=headers,
            method="POST",
        )
        try:
            with urllib.request.urlopen(req, timeout=90) as resp:
                raw = resp.read().decode()
                return json.loads(raw) if raw else {}
        except urllib.error.HTTPError as exc:
            detail = exc.read().decode(errors="replace")
            raise GrokBotError(f"{service}/{method} failed HTTP {exc.code}: {_safe_error(detail)}") from exc
    
    
    def _safe_error(raw: str) -> str:
        try:
            parsed = json.loads(raw)
        except json.JSONDecodeError:
            return raw[:240]
        message = parsed.get("message") or parsed.get("code") or "request failed"
        debug = None
        details = parsed.get("details")
        if isinstance(details, list) and details:
            debug = (details[0].get("debug") or {}).get("error")
        return f"{message}" + (f" ({debug})" if debug else "")
    
    
    def _ensure_box(access_token: str) -> dict[str, str]:
        box = _connect(access_token, "aiserver.v1.GrokBotService", "EnsureSandBox", {})
        gateway_url = box.get("gatewayUrl") or box.get("gateway_url")
        gateway_token = box.get("gatewayToken") or box.get("gateway_token")
        network_token = box.get("networkToken") or box.get("network_token")
        if not gateway_url or not gateway_token or not network_token:
            raise GrokBotError("EnsureSandBox did not return a gateway URL and tokens. Is the computer still starting?")
        return {
            "gateway_url": str(gateway_url).rstrip("/"),
            "gateway_token": str(gateway_token),
            "network_token": str(network_token),
            "cluster": str(box.get("cluster") or ""),
            "pod_id": str(box.get("podId") or box.get("pod_id") or ""),
        }
    
    
    def _gateway(box: dict[str, str], path: str, body: dict[str, Any] | None = None) -> Any:
        url = box["gateway_url"] + path
        headers = {
            "Authorization": f"Bearer {box['gateway_token']}",
            "x-anyrun-network-token": box["network_token"],
            "Content-Type": "application/json",
        }
        req = urllib.request.Request(
            url,
            data=json.dumps({} if body is None else body).encode(),
            headers=headers,
            method="POST",
        )
        try:
            with urllib.request.urlopen(req, timeout=90) as resp:
                raw = resp.read().decode()
                return json.loads(raw) if raw else {}
        except urllib.error.HTTPError as exc:
            detail = exc.read().decode(errors="replace")
            raise GrokBotError(f"{path} failed HTTP {exc.code}: {_safe_error(detail)}") from exc
    
    
    def _session() -> tuple[str, dict[str, str]]:
        access = _decrypt_access_token()
        return access, _ensure_box(access)
    
    
    def _summarize_agent(agent: dict[str, Any], *, full: bool = False) -> dict[str, Any]:
        description = agent.get("description") or ""
        preview = agent.get("lastMessagePreview") or ""
        if not full and len(description) > 180:
            description = description[:177] + "..."
        if not full and len(preview) > 180:
            preview = preview[:177] + "..."
        return {
            "id": agent.get("id"),
            "name": agent.get("name"),
            "title": agent.get("title") or "",
            "description": description,
            "isActive": agent.get("isActive"),
            "isRunning": agent["isRunning"]
            if "isRunning" in agent
            else agent.get("isRunningTurn"),
            "hasUnread": agent.get("hasUnread"),
            "lastMessagePreview": preview,
            "origin": agent.get("origin"),
        }
    
    
    def _list_agents(box: dict[str, str]) -> list[dict[str, Any]]:
        rows = _gateway(box, "/api/listAgents", {})
        if isinstance(rows, dict):
            rows = rows.get("agents") or rows.get("rows") or []
        if not isinstance(rows, list):
            raise GrokBotError("listAgents returned an unexpected payload.")
        return [row for row in rows if isinstance(row, dict)]
    
    
    def _resolve_agent(box: dict[str, str], *, agent_id: str | None, name: str | None) -> dict[str, Any]:
        agents = _list_agents(box)
        if agent_id:
            for agent in agents:
                if agent.get("id") == agent_id:
                    return agent
            raise GrokBotError(f"No Grok Bot with id {agent_id}.")
        if name:
            matches = [agent for agent in agents if str(agent.get("name") or "").lower() == name.lower()]
            if not matches:
                available = ", ".join(str(agent.get("name") or "?") for agent in agents) or "(none)"
                raise GrokBotError(f"No Grok Bot named {name!r}. Available: {available}")
            if len(matches) > 1:
                raise GrokBotError(f"Multiple Grok Bots named {name!r}; pass --id.")
            return matches[0]
        raise GrokBotError("Pass --id or --name.")
    
    
    def _extract_agent(payload: Any) -> dict[str, Any]:
        if isinstance(payload, dict) and isinstance(payload.get("agent"), dict):
            return payload["agent"]
        if isinstance(payload, dict) and payload.get("id"):
            return payload
        raise GrokBotError("The gateway did not return an agent object.")
    
    
    def _transcript_entries(payload: Any) -> list[dict[str, Any]]:
        if isinstance(payload, list):
            return [row for row in payload if isinstance(row, dict)]
        if isinstance(payload, dict):
            for key in ("entries", "items", "messages", "transcript"):
                value = payload.get(key)
                if isinstance(value, list):
                    return [row for row in value if isinstance(row, dict)]
        return []
    
    
    def _entry_text(entry: dict[str, Any]) -> str:
        for key in ("text", "content", "preview", "message"):
            value = entry.get(key)
            if isinstance(value, str) and value.strip():
                return value
            if isinstance(value, dict):
                nested = value.get("text") or value.get("content")
                if isinstance(nested, str) and nested.strip():
                    return nested
        return ""
    
    
    def cmd_status(_: argparse.Namespace) -> None:
        access = _decrypt_access_token()
        access_status = _connect(access, "aiserver.v1.DashboardService", "GetSandAccessStatus", {})
        run_state = _connect(access, "aiserver.v1.GrokBotService", "GetSandBoxRunState", {})
        box = _ensure_box(access)
        try:
            health = _gateway_get(box, "/health")
        except GrokBotError as exc:
            health = {"error": str(exc)}
        print(
            json.dumps(
                {
                    "access": access_status.get("state") or access_status,
                    "box": run_state.get("state") or run_state,
                    "cluster": box["cluster"],
                    "podIdPresent": bool(box["pod_id"]),
                    "health": {
                        "ok": bool(isinstance(health, dict) and health.get("ok")),
                        "isBusy": health.get("isBusy") if isinstance(health, dict) else None,
                        "activeAgentId": health.get("activeAgentId") if isinstance(health, dict) else None,
                    },
                },
                indent=2,
            )
        )
    
    
    def _gateway_get(box: dict[str, str], path: str) -> Any:
        url = box["gateway_url"] + path
        headers = {
            "Authorization": f"Bearer {box['gateway_token']}",
            "x-anyrun-network-token": box["network_token"],
        }
        req = urllib.request.Request(url, method="GET", headers=headers)
        try:
            with urllib.request.urlopen(req, timeout=30) as resp:
                raw = resp.read().decode()
                return json.loads(raw) if raw else {}
        except urllib.error.HTTPError as exc:
            detail = exc.read().decode(errors="replace")
            raise GrokBotError(f"{path} failed HTTP {exc.code}: {_safe_error(detail)}") from exc
    
    
    def cmd_list(args: argparse.Namespace) -> None:
        _, box = _session()
        agents = _list_agents(box)
        print(json.dumps([_summarize_agent(agent, full=args.full) for agent in agents], indent=2))
    
    
    def cmd_create(args: argparse.Namespace) -> None:
        _, box = _session()
        existing = [
            agent
            for agent in _list_agents(box)
            if str(agent.get("name") or "").lower() == args.name.lower()
        ]
        if existing and not args.force:
            raise GrokBotError(
                f"A Grok Bot named {args.name!r} already exists ({existing[0].get('id')}). "
                "Use a different name, or pass --force to create another."
            )
        created = _gateway(
            box,
            "/api/createAgent",
            {
                "name": args.name,
                "description": args.description or "",
                "origin": "user",
                "isKickstartRequested": not args.no_kickstart,
            },
        )
        agent = _extract_agent(created)
        agent_id = agent.get("id")
        if agent_id and (args.title or args.description):
            updated = _gateway(
                box,
                "/api/updateAgent",
                {
                    "id": agent_id,
                    "profile": {
                        "name": args.name,
                        "title": args.title or "",
                        "description": args.description or "",
                    },
                },
            )
            agent = _extract_agent(updated) if isinstance(updated, dict) else agent
        print(json.dumps(_summarize_agent(agent, full=True), indent=2))
    
    
    def cmd_update(args: argparse.Namespace) -> None:
        _, box = _session()
        agent = _resolve_agent(box, agent_id=args.id, name=args.name)
        profile = {
            "name": args.rename or agent.get("name") or "",
            "title": args.title if args.title is not None else agent.get("title") or "",
            "description": args.description
            if args.description is not None
            else agent.get("description") or "",
        }
        updated = _gateway(box, "/api/updateAgent", {"id": agent["id"], "profile": profile})
        print(json.dumps(_summarize_agent(_extract_agent(updated), full=True), indent=2))
    
    
    def cmd_send(args: argparse.Namespace) -> None:
        _, box = _session()
        agent = _resolve_agent(box, agent_id=args.id, name=args.name)
        result = _gateway(
            box,
            "/api/sendPrompt",
            {"agentId": agent["id"], "prompt": args.prompt},
        )
        print(
            json.dumps(
                {
                    "accepted": bool(isinstance(result, dict) and result.get("accepted", True)),
                    "agent": _summarize_agent(agent),
                },
                indent=2,
            )
        )
    
    
    def cmd_transcript(args: argparse.Namespace) -> None:
        _, box = _session()
        agent = _resolve_agent(box, agent_id=args.id, name=args.name)
        payload = _gateway(box, "/api/getAgentTranscript", {"id": agent["id"]})
        entries = _transcript_entries(payload)
        if args.limit:
            entries = entries[-args.limit :]
        print(
            json.dumps(
                {
                    "agent": _summarize_agent(agent),
                    "entries": [
                        {
                            "id": entry.get("id") or entry.get("entryId"),
                            "kind": entry.get("kind") or entry.get("type"),
                            "author": entry.get("authorId") or entry.get("role") or entry.get("author"),
                            "text": _entry_text(entry),
                        }
                        for entry in entries
                    ],
                },
                indent=2,
            )
        )
    
    
    def cmd_chat(args: argparse.Namespace) -> None:
        _, box = _session()
        agent = _resolve_agent(box, agent_id=args.id, name=args.name)
        before = _transcript_entries(_gateway(box, "/api/getAgentTranscript", {"id": agent["id"]}))
        before_ids = {entry.get("id") or entry.get("entryId") for entry in before}
        sent = _gateway(box, "/api/sendPrompt", {"agentId": agent["id"], "prompt": args.prompt})
        if isinstance(sent, dict) and sent.get("accepted") is False:
            raise GrokBotError("sendPrompt was not accepted.")
        deadline = time.time() + args.timeout
        latest = agent
        while time.time() < deadline:
            time.sleep(args.poll)
            agents = _list_agents(box)
            latest = next((row for row in agents if row.get("id") == agent["id"]), latest)
            running = bool(latest.get("isRunning") or latest.get("isRunningTurn") or latest.get("isComposingMessage"))
            if not running:
                break
        after = _transcript_entries(_gateway(box, "/api/getAgentTranscript", {"id": agent["id"]}))
        new_entries = [
            entry
            for entry in after
            if (entry.get("id") or entry.get("entryId")) not in before_ids
        ]
        print(
            json.dumps(
                {
                    "agent": _summarize_agent(latest, full=True),
                    "stillRunning": bool(
                        latest.get("isRunning") or latest.get("isRunningTurn") or latest.get("isComposingMessage")
                    ),
                    "newEntries": [
                        {
                            "id": entry.get("id") or entry.get("entryId"),
                            "kind": entry.get("kind") or entry.get("type"),
                            "author": entry.get("authorId") or entry.get("role") or entry.get("author"),
                            "text": _entry_text(entry),
                        }
                        for entry in new_entries
                    ],
                },
                indent=2,
            )
        )
    
    
    def _add_agent_selector(parser: argparse.ArgumentParser) -> None:
        parser.add_argument("--id", help="Grok Bot UUID")
        parser.add_argument("--name", help="Grok Bot display name")
    
    
    def main() -> None:
        parser = argparse.ArgumentParser(description="Chat with Grok Bot and create new teammates.")
        sub = parser.add_subparsers(dest="command", required=True)
    
        sub.add_parser("status", help="Check sign-in and cloud computer health")
    
        list_p = sub.add_parser("list", help="List Grok Bots")
        list_p.add_argument("--full", action="store_true", help="Do not truncate descriptions")
    
        create_p = sub.add_parser("create", help="Spin up a new Grok Bot")
        create_p.add_argument("--name", required=True)
        create_p.add_argument("--title", default="")
        create_p.add_argument("--description", default="")
        create_p.add_argument("--no-kickstart", action="store_true")
        create_p.add_argument("--force", action="store_true", help="Allow a duplicate name")
    
        update_p = sub.add_parser("update", help="Edit a Grok Bot profile")
        _add_agent_selector(update_p)
        update_p.add_argument("--rename")
        update_p.add_argument("--title")
        update_p.add_argument("--description")
    
        send_p = sub.add_parser("send", help="Send a message without waiting")
        _add_agent_selector(send_p)
        send_p.add_argument("--prompt", required=True)
    
        chat_p = sub.add_parser("chat", help="Send a message and wait for new replies")
        _add_agent_selector(chat_p)
        chat_p.add_argument("--prompt", required=True)
        chat_p.add_argument("--timeout", type=int, default=90)
        chat_p.add_argument("--poll", type=float, default=2.0)
    
        transcript_p = sub.add_parser("transcript", help="Read a Grok Bot conversation")
        _add_agent_selector(transcript_p)
        transcript_p.add_argument("--limit", type=int, default=20)
    
        args = parser.parse_args()
        commands = {
            "status": cmd_status,
            "list": cmd_list,
            "create": cmd_create,
            "update": cmd_update,
            "send": cmd_send,
            "chat": cmd_chat,
            "transcript": cmd_transcript,
        }
        try:
            commands[args.command](args)
        except GrokBotError as exc:
            _die(str(exc))
    
    
    if __name__ == "__main__":
        main()
    
  • .claude-plugin/marketplace.json539 B464b288fc675upstream ↗
    {
      "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
      "name": "grok-bot-skill",
      "owner": {
        "name": "Adam Anzuoni",
        "url": "https://github.com/adamanz"
      },
      "metadata": {
        "description": "Chat with Grok Bot teammates and create new Grok Bots from Cursor, Claude Code, or Codex",
        "version": "1.0.0"
      },
      "plugins": [
        {
          "name": "grok-bot",
          "description": "Chat with xAI Grok Bot teammates and create new Grok Bots via CLI",
          "source": "./",
          "skills": ["./"]
        }
      ]
    }
    
  • .gitignore85 B129537552227upstream ↗
    .DS_Store
    __pycache__/
    *.pyc
    .env
    .env.local
    sand-secrets.json
    *.pem
    .idea/
    .vscode/
    
  • AGENTS.md407 B1970838a9b6aupstream ↗
    # Grok Bot Skill
    
    This repository is an [Agent Skill](https://agentskills.io) for the xAI Grok Bot desktop app.
    
    Install:
    
    ```bash
    npx skills add adamanz/grok-bot-skill -g
    ```
    
    When the user wants to chat with a Grok Bot, list Grok Bots, create a new Grok Bot teammate, or operate Grok Bot from the terminal, follow [SKILL.md](SKILL.md) and run `scripts/grokbot.py`. Do not use the Cursor Cloud Agents API.
    
  • CHANGELOG.md233 B1ba0966384bfupstream ↗
    # Changelog
    
    ## 1.0.0 — 2026-08-17
    
    - First public release of the Grok Bot Agent Skill
    - CLI: `status`, `list`, `create`, `update`, `send`, `chat`, `transcript`
    - macOS session via Grok Bot desktop app (no third-party Python deps)
    
  • examples.md1.4 KBc6243578becaupstream ↗
    # Examples
    
    Resolve the CLI from the installed skill directory:
    
    ```bash
    SCRIPT="$HOME/.cursor/skills/grok-bot/scripts/grokbot.py"
    ```
    
    ## Check that Grok Bot is signed in
    
    ```bash
    python3 "$SCRIPT" status
    ```
    
    ## List teammates
    
    ```bash
    python3 "$SCRIPT" list
    python3 "$SCRIPT" list --full
    ```
    
    ## Chat and wait for a reply
    
    ```bash
    python3 "$SCRIPT" chat --name Reed --prompt "What are you waiting on from me?"
    ```
    
    ## Send without waiting
    
    ```bash
    python3 "$SCRIPT" send --name Reed --prompt "Draft today's brief. Do not send anything."
    ```
    
    ## Create a focused teammate
    
    ```bash
    python3 "$SCRIPT" create \
      --name Reed \
      --title "Chief of staff" \
      --description "Draft-only daily brief from calendar and inbox. Never send messages or approve spend."
    ```
    
    Then give it one first task:
    
    ```bash
    python3 "$SCRIPT" chat --name Reed --prompt "Ask me for 3-5 priorities, then draft a brief."
    ```
    
    ## Read recent messages
    
    ```bash
    python3 "$SCRIPT" transcript --name Reed --limit 20
    ```
    
    ## Update standing rules
    
    ```bash
    python3 "$SCRIPT" update --name Reed --title "Chief of staff" \
      --description "Draft-only. Never send Slack, email, or calendar invites."
    ```
    
    ## Prompts that should trigger this skill
    
    - “Message my Grok Bot”
    - “List my Grok Bots”
    - “Create a Grok Bot named Reed as chief of staff”
    - “What did Reed say last?”
    - “Talk to Grok Bot from Cursor, not the desktop app”
    
  • LICENSE1.0 KBafd9f9acc2c2upstream ↗
    MIT License
    
    Copyright (c) 2026 Adam Anzuoni
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.
    
  • package.json781 B51afd492513fupstream ↗
    {
      "name": "grok-bot-skill",
      "version": "1.0.0",
      "private": true,
      "description": "Cursor and Agent Skill to chat with Grok Bot teammates and create new Grok Bots from the CLI",
      "license": "MIT",
      "keywords": [
        "agent-skill",
        "agent-skills",
        "cursor",
        "cursor-skill",
        "grok-bot",
        "grok",
        "xai",
        "xai-grok",
        "claude-code",
        "claude-skills",
        "codex",
        "skills.sh",
        "macos",
        "cli"
      ],
      "files": [
        "SKILL.md",
        "scripts",
        "examples.md",
        "AGENTS.md"
      ],
      "repository": {
        "type": "git",
        "url": "git+https://github.com/adamanz/grok-bot-skill.git"
      },
      "homepage": "https://github.com/adamanz/grok-bot-skill#readme",
      "bugs": {
        "url": "https://github.com/adamanz/grok-bot-skill/issues"
      }
    }
    
  • SECURITY.md541 Bc9106b03c7f0upstream ↗
    # Security
    
    This skill talks to Grok Bot using the signed-in desktop session on your Mac.
    
    - Never commit `sand-secrets.json`, Keychain dumps, JWTs, or gateway URLs.
    - The CLI must not print tokens. If you see a token in output, treat it as leaked and sign in again.
    - Do not send passwords, API keys, or 2FA codes in Grok Bot prompts. Use **Agent Computer** takeover in the app.
    - All Grok Bots on an account share one cloud computer. Do not treat bot names as isolation.
    
    Report issues at https://github.com/adamanz/grok-bot-skill/issues.
    

Plain-text copy, no login: /skill-bundles/adamanz-grok-bot-skill.md

// REPO STATS

17 stars
0 open issues
Last commit: 8d ago