grok-search

Grok Search

Use Grok Search for freshness-first research.

Prefer it when the task is about:

• breaking news
• X/Twitter chatter
• fast-moving narratives
• “what are people saying now?”
• quick multi-source synthesis
• comparing official claims vs community discussion

Do not default to Grok Search for:

• official docs lookup
• API/reference pages
• pricing / plan details
• direct page text extraction
• canonical source retrieval

For those, prefer exa-search.

Workflow

1. Use --mode news for fresh updates.
2. Use --mode social for X/Twitter and discourse-heavy prompts.
3. Use --mode research for broad multi-source synthesis.
4. Use --mode docs-compare when you want official claims plus community interpretation.
5. Use --plain for human-readable terminal output.
6. Use --profile <id> when testing one key or diagnosing failover.
7. Use --ignore-cooldown only when you intentionally want to override a temporary cooldown and force another try.

Config

Preferred key resolution order:

1. --api-key
2. GROK_API_KEY
3. GROK_API_KEYS (comma-separated)
4. config.local.json
5. config.json
6. ~/.codex/config/grok-search.json

Recommended setup for this workspace: keep the real key(s) inside the skill folder in config.local.json so the whole skill can be backed up and moved as one directory.

Single key

{
  "profiles": [
    { "id": "main", "api_key": "YOUR_GROK_API_KEY" }
  ]
}

Multiple keys with auto failover

{
  "profiles": [
    { "id": "main", "api_key": "KEY_1" },
    { "id": "backup-1", "api_key": "KEY_2" },
    { "id": "backup-2", "api_key": "KEY_3" }
  ],
  "base_url": "https://your-grok-endpoint.example",
  "model": "grok-4.1-fast",
  "timeout_seconds": 120,
  "extra_body": {},
  "extra_headers": {},
  "cooldown": {
    "enabled": true,
    "state_file": "runtime/cooldowns.json",
    "default_minutes": 15,
    "rate_limit_minutes": 20,
    "quota_minutes": 60,
    "auth_minutes": 360
  }
}