{"id":32848938,"url":"https://github.com/mikedemarais/grok-skill","last_synced_at":"2025-11-14T16:01:35.782Z","repository":{"id":323060271,"uuid":"1091961958","full_name":"mikedemarais/grok-skill","owner":"mikedemarais","description":"Claude Code Skill that routes Twitter/X prompts to Grok-4 Live Search.","archived":false,"fork":false,"pushed_at":"2025-11-07T20:18:26.000Z","size":19,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-07T22:16:46.322Z","etag":null,"topics":["claude-code","claude-code-skills","claude-skills","grok","openrouter","xai"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikedemarais.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-07T19:25:32.000Z","updated_at":"2025-11-07T22:09:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mikedemarais/grok-skill","commit_stats":null,"previous_names":["mikedemarais/grok-skill"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mikedemarais/grok-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikedemarais%2Fgrok-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikedemarais%2Fgrok-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikedemarais%2Fgrok-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikedemarais%2Fgrok-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikedemarais","download_url":"https://codeload.github.com/mikedemarais/grok-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikedemarais%2Fgrok-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283333713,"owners_count":26818628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-08T02:00:06.281Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","claude-code-skills","claude-skills","grok","openrouter","xai"],"created_at":"2025-11-08T10:00:56.917Z","updated_at":"2025-11-10T12:01:43.502Z","avatar_url":"https://github.com/mikedemarais.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# grok-skill\n\n[![Built with Bun](https://img.shields.io/badge/runtime-bun-000000.svg?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/language-typescript-3178C6.svg?logo=typescript)](https://www.typescriptlang.org/)\n[![OpenRouter](https://img.shields.io/badge/api-OpenRouter-4B8BBE.svg)](https://openrouter.ai)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\nA Claude Code Skill that routes X/Twitter queries to xAI **Grok 4** via **OpenRouter** with **Live Search** turned on and scoped to the **X** source.\n\n## Features\n\n- **Live Search** - Real-time X/Twitter data via Grok 4's Live Search\n- **Handle Filtering** - Multi-value `--include` / `--exclude` for targeted searches\n- **Date Range Queries** - Time-bounded searches with calendar validation\n- **Engagement Filters** - Filter by favorites and views\n- **Network Resilience** - Automatic retries with exponential backoff\n- **Citation Extraction** - Tweet URLs with fallback parsing\n- **Production Ready** - Comprehensive error handling and validation\n\n## Quick Start\n\n```bash\n# 1. Set your OpenRouter API key\nexport OPENROUTER_API_KEY=\"sk-or-...\"\n\n# 2. Run a query (assumes Bun is installed)\nbun scripts/grok.ts --q \"what's trending on X about AI?\"\n```\n\nThat's it! The script returns JSON with summary, citations, and usage stats.\n\n## Install\n\n### 1. Get an OpenRouter API Key\n\nSign up at [openrouter.ai](https://openrouter.ai) and create an API key.\n\n### 2. Set Environment Variable\n\n```bash\n# Set your OpenRouter key\nexport OPENROUTER_API_KEY=\"sk-or-...\"\n\n# Verify it's set\necho \"$OPENROUTER_API_KEY\"\n\n# To persist across sessions, add to your shell profile:\necho 'export OPENROUTER_API_KEY=\"sk-or-...\"' \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n```\n\n### 3. Install Bun (if needed)\n\n```bash\n# macOS/Linux\nbrew install bun || curl -fsSL https://bun.sh/install | bash\n\n# Windows\npowershell -c \"irm bun.sh/install.ps1|iex\"\n```\n\n### 4. Clone and Setup\n\n```bash\n# Clone to Claude Code skills directory\ngit clone https://github.com/mikedemarais/grok-skill.git ~/.claude/skills/grok-skill\n\n# Make script executable\nchmod +x ~/.claude/skills/grok-skill/scripts/grok.ts\n\n# Restart Claude Code to discover the skill\n```\n\n## Usage\n\n```bash\n# Minimal query\nbun scripts/grok.ts --q \"what are people saying about account abstraction on X?\"\n\n# One-off (without shell export)\nOPENROUTER_API_KEY=\"sk-or-...\" bun scripts/grok.ts --q \"latest crypto news\"\n\n# Handles + timeframe + filters\nbun scripts/grok.ts \\\n  --q \"AI developments\" \\\n  --include \"@OpenAI\" \"@AnthropicAI\" \\\n  --from 2025-11-01 --to 2025-11-07 \\\n  --mode on --min-faves 25 --max 12\n\n# Exclude specific handles\nbun scripts/grok.ts \\\n  --q \"crypto market sentiment\" \\\n  --exclude \"@spam_account\" \\\n  --max 20\n```\n\n## Flags\n\n| Flag | Type | Description | Default |\n|------|------|-------------|---------|\n| `--q` | `string` | Query text (required) | - |\n| `--mode` | `on\\|off\\|auto` | Live Search mode | `auto` |\n| `--include` | `@handle...` | X handles to include (max 10) | `[]` |\n| `--exclude` | `@handle...` | X handles to exclude (max 10) | `[]` |\n| `--from` | `YYYY-MM-DD` | Start date for search | - |\n| `--to` | `YYYY-MM-DD` | End date for search | - |\n| `--max` | `1..50` | Max search results | `12` |\n| `--min-faves` | `integer` | Min favorites per tweet (≥ 0) | - |\n| `--min-views` | `integer` | Min views per tweet (≥ 0) | - |\n\n**Environment Variables:**\n- `OPENROUTER_API_KEY` (required) - Your OpenRouter API key\n- `GROK_MODEL` (optional) - Override model (default: `x-ai/grok-4`)\n\n**Constraints:**\n- `--include` and `--exclude` are mutually exclusive\n- Dates must be valid calendar dates in `YYYY-MM-DD` format\n- Handles automatically stripped of '@' prefix and normalized\n\n## Sample Output\n\n```json\n{\n  \"query\": \"AI developments\",\n  \"summary\": \"- **OpenAI releases GPT-5**: Major improvements in reasoning...\\n- **Anthropic Claude updates**: New vision capabilities announced...\\n- **xAI Grok integration**: Now available via OpenRouter API...\",\n  \"citations\": [\n    \"https://x.com/OpenAI/status/1234567890\",\n    \"https://x.com/AnthropicAI/status/9876543210\",\n    \"https://x.com/xai/status/5555555555\"\n  ],\n  \"usage\": {\n    \"prompt_tokens\": 892,\n    \"completion_tokens\": 312,\n    \"total_tokens\": 1204\n  },\n  \"model\": \"x-ai/grok-4\"\n}\n```\n\n## Troubleshooting\n\n### Missing API Key\n```bash\n# Error: \"Missing env OPENROUTER_API_KEY\"\nexport OPENROUTER_API_KEY=\"sk-or-...\"\n```\n\n### HTTP 429 / Rate Limits\nThe client automatically retries with exponential backoff. If you still hit limits:\n- Wait a few minutes and retry\n- Reduce `--max` to make smaller requests\n- Check your OpenRouter account rate limits\n\n### Sparse or No Results\n- Increase `--max` (try 15-20)\n- Remove or relax `--include`/`--exclude` filters\n- Widen or remove date range constraints\n- Use `--mode on` to force Live Search\n\n### Citations are Null\nThis is normal. The script extracts X/Twitter URLs from the summary text as a fallback. Check the `citations` array for discovered links.\n\n### Script Not Executable\n```bash\nchmod +x scripts/grok.ts\n```\n\n## Configuration\n\n### Live Search Parameters\n\n- **mode**: Controls Live Search behavior\n  - `auto` (default) - Model decides whether to search\n  - `on` - Forces Live Search\n  - `off` - Disables search, uses model knowledge only\n\n- **return_citations**: Always `true` to get tweet URLs\n\n- **max_search_results**: Capped at 12 by default for cost/latency\n\n- **sources**: Configured for X/Twitter with optional filters:\n  - `included_x_handles` / `excluded_x_handles`\n  - `post_favorite_count` / `post_view_count`\n\n### Network Resilience\n\n- **Timeout**: 30 seconds per request via AbortController\n- **Retries**: Up to 3 attempts on 408/429/5xx errors\n- **Backoff**: Exponential with jitter (500ms × 2^attempt)\n- **Retry-After**: Honors rate limit headers when provided\n\n### Exit Codes\n\n- `0` - Success\n- `2` - Usage/validation error\n- `3` - Network/timeout error\n- `4` - JSON parse error\n\n## Cost Management\n\n**Typical token usage per query:**\n- Prompt tokens: ~700-1000\n- Completion tokens: ~300-500\n- Total: ~1000-1500 tokens\n\n**Best practices:**\n- Keep `--max ≤ 12` for routine queries\n- Use specific date ranges to limit scope\n- Monitor costs via the `usage` field in output\n- Increase `--max` only when results are sparse\n\n## Contributing\n\nContributions welcome! Please:\n- Open an issue for bugs or feature requests\n- Submit PRs with clear descriptions\n- Follow the existing code style\n- Test changes before submitting\n\n## License\n\nMIT - see [LICENSE](LICENSE)\n\n## Related\n\n- [OpenRouter Documentation](https://openrouter.ai/docs)\n- [Grok 4 API Docs](https://docs.x.ai/docs)\n- [Claude Code Skills Guide](https://docs.claude.com/claude-code/skills)\n- [Bun Runtime](https://bun.sh/docs)\n\n---\n\n**Security Note:** Never commit secrets. If you use a local `.env` file, ensure it's in `.gitignore`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikedemarais%2Fgrok-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikedemarais%2Fgrok-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikedemarais%2Fgrok-skill/lists"}