grokodex

<div align="center"> <img alt="Grokodex" src="assets/logo.svg" width="128" height="128" /> # Tool List ### Invoke Local Grok in Codex / Claude Code <p> Delegate coding · Imagine image generation · Search X<br/> skills + MCP plugin · Pre-built bundle · Git marketplace one-click installation </p> <p> <a href="https://github.com/anlostsheep/grokodex/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/anlostsheep/grokodex?style=flat&logo=github"></a> <a href="https://github.com/anlostsheep/grokodex/network/members"><img alt="Forks" src="https://img.shields.io/github/forks/anlostsheep/grokodex?style=flat&logo=github"></a> <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-16a34a"></a> <a href="https://github.com/anlostsheep/grokodex/releases/tag/v0.2.0"><img alt="Version" src="https://img.shields.io/badge/version-0.2.0-blue"></a> <a href="https://nodejs.org/"><img alt="Node" src="https://img.shields.io/badge/node-%3E%3D18.18-339933?logo=nodedotjs&logoColor=white"></a> <img alt="Codex" src="https://img.shields.io/badge/Codex-plugin-412991"> <img alt="Claude Code" src="https://img.shields.io/badge/Claude%20Code-plugin-D97706"> </p> <p> <a href="#核心特性">Core Features</a> · <a href="#快速开始">Quick Start</a> · <a href="#grok-鉴权">Grok Authentication</a> · <a href="#mcp-工具">MCP Tools</a> · <a href="#权限说明">Permission Description</a> · <a href="#常见问题">FAQ</a> · <a href="#版本与发版">Version and Release</a> </p> </div> > [!NOTE] > This project is open-sourced under the **[MIT](./LICENSE)** license. Please comply with the service terms of **xAI / Grok**, your third-party upstream, and **Codex / Claude Code**. > Grokodex **does not replace** the native Grok CLI, only calls it through MCP in the host. **Current Version [0.2.0](./CHANGELOG.md)** · Plugin ID: `grokodex` · Repository: [`anlostsheep/grokodex`](https://github.com/anlostsheep/grokodex) ``` Codex / Claude Code ──skills + MCP──► grokodex-bridge (node) │ ▼ Native Grok CLI (Official / API Key / Third-party upstream) ``` --- ## Core Features | Capability | Description | | :-- | :-- | | Dual-host plugin | **Codex** and **Claude Code** in the same monorepo, Git marketplace installation | | Four-tool MCP | `grok_setup` / `grok_run` / `grok_imagine` / `grok_x_search` | | Four skills | Guided tool invocation; default **restricted permissions** (`restricted`) | | Pre-built bundle | Submit `plugins/grokodex/bridge/dist/bundle.mjs`, users **no need** `npm install` | | Flexible authentication | Official `grok login`, **or** `XAI_API_KEY`, **or** third-party/self-built OpenAI compatible upstream | | Leader warm-up process | Default enabled, accelerate headless; can be disabled | | Session continuation | Optional `host_thread_id`, multi-round `grok_run` connect to the same Grok conversation | --- ## Quick Start ### 1. Prerequisites | Dependency | Description | | :-- | :-- | | **Node.js ≥ 18.18** | Must be in **PATH** (public installation command name `node`) | | **Grok CLI** | [Installation script](https://x.ai/cli) / `grok` in PATH, or set `GROK_PATH` | | **Available upstream authentication** | See [Grok Authentication](#grok-鉴权) (**not mandatory**, only for OAuth) | | **Codex and/or Claude Code** | Support plugin marketplace native version | ```bash # macOS / Linux / WSL — Only install CLI curl -fsSL https://x.ai/cli/install.sh | bash # Windows PowerShell irm https://x.ai/cli/install.ps1 | iex ``` ### 2. Install Plugin (Git marketplace) **Codex** ```bash codex plugin marketplace add anlostsheep/grokodex codex plugin add grokodex@grokodex # Specify version example: # codex plugin marketplace add anlostsheep/grokodex --ref v0.2.0 ``` Completely exit and restart Codex App → Confirm plugin enabled → New session. **Claude Code** ```bash claude plugin marketplace add anlostsheep/grokodex claude plugin install grokodex@grokodex ``` Restart / New session → `/mcp` or `/plugins` confirm **plugin internal** MCP `connected`. > [!TIP] > If prompted *MCP skipped – same command/URL as already-configured "grokodex"*：It means there is **another** handwritten/project `.mcp.json` or old MCP and plugin competing for the name. Close or delete the duplicate `grokodex` MCP, only leave the plugin one, then open a new session. ### Upgrade Codex Plugin Codex **no** separate `plugin upgrade`. To upgrade: Refresh **marketplace snapshot**, then **reinstall plugin**, finally restart App. Marketplace configuration name is **`grokodex`** (not `anlostsheep/grokodex`). `marketplace remove` only accepts name (letters, numbers, `_`, `-`), with `/` will report invalid name. **A. Follow main installation (no `--ref`)** ```bash codex plugin marketplace upgrade grokodex codex plugin remove grokodex@grokodex codex plugin add grokodex@grokodex ``` Completely exit and restart Codex App → New session. **B. Specify tag installation (e.g., `--ref v0.2.0`)** `marketplace upgrade` only refreshes **registered ref**, not automatically jump to new tag. Change version need to uninstall marketplace, then specify new tag: ```bash codex plugin remove grokodex@grokodex codex plugin marketplace remove grokodex codex plugin marketplace add anlostsheep/grokodex --ref v0.3.0 # Change to target tag codex plugin add grokodex@grokodex ``` Restart Codex App → New session. **C. Local development (personal marketplace)** If used `./scripts/install-codex-plugin.sh` (`grokodex@personal`), after repository update, re-run the script, it will synchronize with public Git `grokodex@grokodex`. **Optional verification** ```bash codex plugin marketplace list codex plugin list --marketplace grokodex # Snapshot version (package / plugin manifest) # cat ~/.codex/.tmp/marketplaces/grokodex/package.json | head -5 ``` > [!IMPORTANT] > Only `plugin remove` **will not** change marketplace source. If prompted *marketplace 'grokodex' is already added from a different source*, first execute `codex plugin marketplace remove grokodex`, then `add` (if necessary, add `--ref`). ### 3. First Invocation 1. Terminal confirm Grok available: `grok whoami` or `grok -m <model> -p "ping"` 2. In host invoke **`grok_setup`** 3. Then **`grok_run`** (e.g., prompt: `Reply with exactly: pong`) 4. Image generation → `grok_imagine`; Search X → `grok_x_search` **Business tasks use MCP**, do not use shell bypass `grok` (install CLI / modify `~/.grok/config.toml` / login excluded). ### 4. Local Development Installation (Optional) Modify this repository code: ```bash ./scripts/install-codex-plugin.sh # → personal marketplace ./scripts/install-claude-plugin.sh # → grokodex-local # Optional: --no-build / --no-leader ``` --- ## Grok Authentication Grokodex only invokes native **Grok Build CLI**. How the upstream connects is determined by **Grok's own configuration**——**no need** to only `grok login`. | Method | Applicable | Practice | | :-- | :-- | :-- | | **A. Official session** | xAI subscription / official account | `grok login` → `~/.grok/auth.json` | | **B. Official API Key** | Console Key | `export XAI_API_KEY=...` (old name `GROK_CODE_XAI_API_KEY` still available) | | **C. Third-party / self-built** | OpenAI compatible relay, Sub2API, etc. | `~/.grok/config.toml` write `[model.*]`, or `GROK_MODELS_BASE_URL` + key | **C Example (recommended by model segment):** ```toml # ~/.grok/config.toml [model.my-upstream] model = "grok-4.5" base_url = "https://api.example.com/v1" name = "My Upstream Grok" env_key = "MY_UPSTREAM_API_KEY" api_backend = "responses" # chat_completions | responses | messages context_window = 128000 # [models] # default = "my-upstream" ``` ```bash export MY_UPSTREAM_API_KEY="sk-..." grok models grok -m my-upstream -p "ping" ``` > [!IMPORTANT] > - Custom model configured `api_key` / `env_key`, **the model uses the key**, will not use the official session to hit the third-party. > - Key **do not** submit git; prefer `env_key`. > - Complete third-party upstream description: [Grok Build Access Third-party API](https://blog.silascoding.com/ai/grok/third-party-api) (take native `~/.grok/docs` as standard). --- ## MCP Tools | Tool | Effect | Description | | :-- | :-- | :-- | | `grok_setup` | Diagnose native grok | Path / version / authentication detection; suggest invocation first. `auth file present` **≠** session definitely valid | | `grok_run` | Universal headless delegation | Default **restricted** (`restricted`); can explicitly `inherit`; can pass `model` | | `grok_imagine` | Imagine image generation | Narrow permissions; product default `.grokodex/images` | | `grok_x_search` | X / Twitter search | Read-only; `semantic` / `keyword` | Unified JSON: `ok` + failure `error.code` / `hint`. Claude interface may display `mcp__…__grok_run`, logical name is still above. ### `grok_run` Common Parameters | Parameter | Description | | :-- | :-- | | `prompt` | **Required**, task description | | `cwd` | Working directory (default host workspace) | | `permission_mode` | `restricted` (default) or `inherit` (inherit host, need user explicit request) | | `host_sandbox` | Only `inherit`: `read-only` / `workspace-write` / `danger-full-access` | | `host_thread_id` | Host thread ID, for multi-round continuation (e.g., `codex:<id>` / `claude:<id>`) | | `fresh` | `true` force new Grok session | | `session_id` | Advanced: explicit Grok session ID | | `model` / `max_turns` / `timeout_ms` / `extra_rules` | Optional | `codex_sandbox` is an old alias of `host_sandbox`; two fields conflict → `INVALID_ARGS`. --- ## Permission Description | Level | Description | When to use | | :-- | :-- | :-- | | **`restricted` (default)** | Can read and write in current project; high-risk shell **reject**; not automatically always-approve | **Daily default**; no parameter passed is this level | | **`inherit`** | Try to have same permissions as current host session | Only when user explicitly says "same permissions / Full Access"; **prohibit** automatic promotion due to task difficulty | `inherit` must be able to resolve **`host_sandbox`** (parameter → environment variable → optional read Codex configuration), otherwise `INHERIT_UNAVAILABLE`, **will not** silently grant full. | `host_sandbox` | Meaning | | :-- | :-- | | `read-only` | Read-only | | `workspace-write` | Workspace writable (close to default restricted) | | `danger-full-access` | High-risk fully open; high cost and risk, only use when explicitly requested | `grok_imagine` / `grok_x_search` **never** fully inherit shell. --- ## Leader and Session Continuation | Concept | Description | Default | | :-- | :-- | :-- | | **Leader** | Native Grok warm-up process, less cold start | Enabled (`GROKODEX_USE_LEADER=1`) | | **one-shot** | Each separate `grok` | `GROKODEX_USE_LEADER=0` or install `--no-leader` | | **Session continuation** | Multi-round `grok_run` connect to the same Grok conversation (`--resume`) | Enabled; pass `host_thread_id` | **Leader ≠ Session Continuation** (process warm-up vs. conversation thread continuation). | Environment Variable | Default | Meaning | | :-- | :-- | :-- | | `GROKODEX_USE_LEADER` | true | Whether to use leader | | `GROKODEX_LEADER_FALLBACK` | true | Leader failure, whether to one-shot | | `GROKODEX_LEADER_ENSURE` | true | Whether to try to start leader | | `GROKODEX_SESSION_REUSE` | true | Whether to resume by host map | | `GROKODEX_SESSION_RESUME_FALLBACK` | true | Resume failure, whether to retry without resume | Codex suggests `host_thread_id=codex:$CODEX_THREAD_ID`; Claude suggests `claude:$CLAUDE_CODE_SESSION_ID`. ## Environment Variables (Summary) **Grok CLI / Upstream (Non-Grokodex Exclusive)** | Variable | Description | | :-- | :-- | | `GROK_PATH` | Grok binary path | | `XAI_API_KEY` | Official or gateway API Key | | `GROK_MODELS_BASE_URL` | Global OpenAI compatible base (including `/v1`) | | `GROK_MODELS_LIST_URL` | Optional, model list URL | **Grokodex Bridge** | Variable | Description | | :-- | :-- | | `GROKODEX_DEFAULT_PERMISSION` | Default permission level (defaults to `restricted`) | | `GROKODEX_ALLOW_INHERIT` | Whether to allow inherit | | `GROKODEX_HOST_SANDBOX` | Host capability level when inheriting | | `GROKODEX_X_SEARCH_TIMEOUT_MS` | Defaults to `90000` | | `GROKODEX_IMAGINE_TIMEOUT_MS` | Defaults to `120000` | --- ## Repository Structure ```text plugins/grokodex/ # Publicly installable unit (submit to git) .mcp.json # Claude: CLAUDE_PLUGIN_ROOT .mcp.codex.json # Codex: relative path bridge/dist/bundle.mjs skills/ assets/ .agents/plugins/ # Codex marketplace list .claude-plugin/ # Claude marketplace list bridge/ skills/ hosts/ # Development source scripts/ # package / install / release ``` --- ## Versioning and Release | Item | Convention | | :-- | :-- | | Unique version source | `package.json` → `"version"` | | Synchronization | `npm run package:plugin` writes plugin and marketplace | | Tag | `v0.2.0` format, can use `marketplace add --ref` | | User upgrade | See [Upgrading Codex Plugins](#upgrading-codex-plugins) (`upgrade` or change tag) | | Changes | [`CHANGELOG.md`](./CHANGELOG.md) | ```bash # Daily code changes (no version bump) npm test && npm run package:plugin && npm run check:plugin # Formal release (clean workspace) ./scripts/release.sh patch|minor|major [--push] # Or: ./scripts/release.sh 0.2.1 --push ``` --- ## Frequently Asked Questions | Issue | Solution | | :-- | :-- | | Plugin installed but times out / MCP `-32000` | Check local Grok: `grok whoami` or `grok -m … -p "ping"`, not plugin reinstallation | | Log `User unauthorized` + infinite Reconnecting | Official session expired; `grok login` then **restart host**. If `relay_connected`, it's likely not a proxy issue | | `Device not configured` | Login status/device not ready; official path re-login; `whoami` may be misleading in non-TTY shells | | `grok_setup` shows auth file but still fails | Currently, mainly checks if `auth.json` exists; **does not** prove token is still accepted by the official API | | Claude won't start / can't find `bundle.mjs` | Requires **≥0.2.0** ( `${CLAUDE_PLUGIN_ROOT}` ). Old version relative paths resolve to **session workspace** | | MCP skipped / two Grokodex | Disable handwritten or project `.mcp.json` MCP, leave only plugin MCP | | Third-party upstream still times out | Fix `config.toml` then, bad official session + default leader may still connect to `code.grok.com`; use `GROKODEX_USE_LEADER=0` or fix login | | Changed source code but host doesn't reflect changes | Source code directory ≠ installed plugin; need `package:plugin` submission or run install script | | Codex version can't be upgraded / *different source* | `marketplace remove` using name **`grokodex`**, not `anlostsheep/grokodex`; see [Upgrading Codex Plugins](#upgrading-codex-plugins) | For more terms ( `restricted` / `inherit` / leader, etc.), see the collapsed section below. <details> <summary><strong>Term Quick Reference</strong></summary> | Term | Meaning | | :-- | :-- | | Host | Codex / Claude Code, etc. clients | | Bridge | This plugin's MCP implementation, relaying to `grok` | | Marketplace | Plugin directory; this repository is a Git marketplace, not the official default store | | MCP | Protocol for hosts to call external tools; this plugin uses local stdio | | Restricted | Default restricted permission | | Inherit | Inherits host permissions (requires user confirmation + `host_sandbox`) | | Leader | Grok warm process | | One-shot | No leader, single run | | Host_thread_id | Host thread ID for session continuation | | CLAUDE_PLUGIN_ROOT | Claude-injected plugin root path variable | </details> --- ## Limitations (Non-Goals) - Do not replace the host's default model with Grok - Requires local **Grok CLI + available upstream** to function (including most Cloud agents) - Do not manage third-party keys within Grokodex - Do not implement a full Grok TUI / ACP nested UI - Do not enter OpenAI / Anthropic **official default plugin stores** (only Git marketplace) - Do not silently auto-elevate permissions --- ## Contribution and Support - Issues / PRs: <https://github.com/anlostsheep/grokodex/issues> - When reporting issues, please include: `grok --version`, `grok whoami` summary (**do not** post `auth.json` / key), whether it's a third-party upstream issue, and whether `User unauthorized` occurs, and host type --- ## Star History If this project has been helpful, feel free to star it. <!-- star-history:start --> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/star-history/star-history-dark.svg"> <img alt="Star history" src="assets/star-history/star-history-light.svg"> </picture> <!-- star-history:end --> <p align="center"> <a href="https://www.star-history.com/?type=date&repos=anlostsheep%2Fgrokodex">star-history.com</a> · <a href="https://github.com/anlostsheep/grokodex/stargazers">Stargazers</a> </p> --- <div align="center"> **[MIT License](./LICENSE)** · Copyright (c) 2026 Grokodex contributors </div>