Skip to content
Back to search

offloader

Local MCP server and Antigravity plugin for offloading coding, reviews, and image tasks to Codex (Pareto auto-routing), OpenCode, and DeepSeek.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/egxl--offloader/badge.svg)](/listings/egxl--offloader)

HTML

<a href="/listings/egxl--offloader"><img src="/api/listings/egxl--offloader/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Build the Server

npm install
npm run build

If using OpenAI Codex via a ChatGPT subscription, sign in once:

npm run codex-login
npm run codex-status

2. Install as an Antigravity Plugin (Optional Skill Sync)

Install or link this repository under `~/.gemini/config/plugins/offload-worker`. On MCP startup, `sync-skills.cjs` scans `~/.gemini/config/skills` first, then each installed plugin's `skills/` directory in alphabetical order, and links any folder containing `SKILL.md` into `$CODEX_HOME/skills` (default `~/.codex/skills`) using directory junctions on Windows and symlinks on macOS/Linux. Existing user entries in `$CODEX_HOME/skills` take precedence, and `.system` is reserved.

3. Configure `mcp_config.json`

Point Antigravity's `offload-worker` entry to `dist/src/index.js` and preload `sync-skills.cjs` if you want automatic skill linking on startup:

{
  "mcpServers": {
    "offload-worker": {
      "command": "node",
      "args": [
        "--require",
        "/path/to/offload-worker/sync-skills.cjs",
        "/path/to/offload-worker/dist/src/index.js"
      ],
      "env": {
        "DEFAULT_OFFLOAD_PROVIDER": "codex",
        "OPENCODE_API_KEY": "your-opencode-key"
      },
      "timeoutSeconds": 600
    }
  }
}

On Windows, you can alternatively load `sync-skills.cjs` relative to the user's home directory via `--import`:

"--import=data:text/javascript,import { homedir } from 'node:os'; import { join } from 'node:path'; import { pathToFileURL } from 'node:url'; await import(pathToFileURL(join(homedir(), '.gemini/config/plugins/offload-worker/sync-skills.cjs')));"

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 216 lines
  1. # Offload Worker (`antigravity-offload-mcp`)
  2. A local stdio MCP server and Antigravity plugin that delegates token-heavy coding, multi-file refactoring, test generation, codebase audits, log/file analysis, and image generation to external providers while keeping Antigravity as a lightweight orchestrator.
  3. ## Features
  4. - **Multi-Provider Routing & Automatic Fallback:** Routes tasks to OpenAI Codex (ChatGPT subscription or API key), OpenCode Go (subscription), OpenCode Console (pay-as-you-go), or the DeepSeek API, with automatic fallback across configured providers.
  5. - **Pareto-Guided Codex Model & Effort Selection:** Reads `$CODEX_HOME/models_cache.json` dynamically and selects the best cost/intelligence `(model, reasoningEffort)` pair for each task tier (`quick`, `standard`, `deep`, `frontier`, and `vision` for image inputs), upgrading automatically when newer model versions appear.
  6. - **Local File Context Without Token Bloat:** Passes workspace-relative `file_paths` as on-disk focus hints to Codex, or reads up to 512 KiB locally for HTTP providers with workspace path-traversal enforcement.
  7. - **Stateful Thread & Session Continuity:** Preserves Codex `thread_id` across turns (without mutating cached model defaults on resume) and attaches `x-opencode-session` (`ses_...`) headers for OpenCode prompt cache routing.
  8. - **Image Generation & Editing:** Exposes Codex `$imagegen` (`gpt-image-2`) through `generate_image`, supporting reference `input_images`, iterative `thread_id` refinement, and copying generated PNGs into the workspace.
  9. - **Automatic Codex Skill Sync:** Links Antigravity skills (`~/.gemini/config/skills` and installed plugin `skills/` directories) into `$CODEX_HOME/skills` at MCP server startup via `sync-skills.cjs`.
  10. ---
  11. ## Requirements
  12. - **Node.js** 20.6 or newer
  13. - At least one configured provider:
  14. - **Codex:** Signed in via `npm run codex-login` (`codex login`) or `CODEX_API_KEY` / `OPENAI_API_KEY`
  15. - **OpenCode Go / Console:** `OPENCODE_GO_API_KEY` or `OPENCODE_API_KEY`
  16. - **DeepSeek:** `DEEPSEEK_API_KEY`
  17. ---
  18. ## Installation & Setup
  19. ### 1. Build the Server
  20. ```bash
  21. npm install
  22. npm run build
  23. ```
  24. If using OpenAI Codex via a ChatGPT subscription, sign in once:
  25. ```bash
  26. npm run codex-login
  27. npm run codex-status
  28. ```
  29. ### 2. Install as an Antigravity Plugin (Optional Skill Sync)
  30. Install or link this repository under `~/.gemini/config/plugins/offload-worker`. On MCP startup, `sync-skills.cjs` scans `~/.gemini/config/skills` first, then each installed plugin's `skills/` directory in alphabetical order, and links any folder containing `SKILL.md` into `$CODEX_HOME/skills` (default `~/.codex/skills`) using directory junctions on Windows and symlinks on macOS/Linux. Existing user entries in `$CODEX_HOME/skills` take precedence, and `.system` is reserved.
  31. ### 3. Configure `mcp_config.json`
  32. Point Antigravity's `offload-worker` entry to `dist/src/index.js` and preload `sync-skills.cjs` if you want automatic skill linking on startup:
  33. ```json
  34. {
  35. "mcpServers": {
  36. "offload-worker": {
  37. "command": "node",
  38. "args": [
  39. "--require",
  40. "/path/to/offload-worker/sync-skills.cjs",
  41. "/path/to/offload-worker/dist/src/index.js"
  42. ],
  43. "env": {
  44. "DEFAULT_OFFLOAD_PROVIDER": "codex",
  45. "OPENCODE_API_KEY": "your-opencode-key"
  46. },
  47. "timeoutSeconds": 600
  48. }
  49. }
  50. }
  51. ```
  52. On Windows, you can alternatively load `sync-skills.cjs` relative to the user's home directory via `--import`:
  53. ```json
  54. "--import=data:text/javascript,import { homedir } from 'node:os'; import { join } from 'node:path'; import { pathToFileURL } from 'node:url'; await import(pathToFileURL(join(homedir(), '.gemini/config/plugins/offload-worker/sync-skills.cjs')));"
  55. ```
  56. ---
  57. ## MCP Tools
  58. ### `offload_task`
  59. Delegates coding, testing, refactoring, debugging, reviews, or analysis to the active provider (with automatic fallback when `allow_fallback` is not `false`).
  60. | Parameter | Type | Description |
  61. | --- | --- | --- |
  62. | `prompt` | `string` *(required)* | Task instruction for the worker model. |
  63. | `provider` | `"codex" \| "opencode-go" \| "opencode" \| "deepseek"` | Explicit provider override. |
  64. | `allow_fallback` | `boolean` | Fall back across configured providers on errors (default: `true`). |
  65. | `model` | `string` | Explicit model ID (for Codex, omit to use Pareto auto-selection). |
  66. | `task_tier` | `"auto" \| "quick" \| "standard" \| "deep" \| "frontier"` | Codex Pareto routing tier (default: `"auto"`). |
  67. | `codex_sandbox` | `"read-only" \| "workspace-write" \| "danger-full-access"` | Codex sandbox mode (default: `"read-only"`). |
  68. | `codex_reasoning_effort` | `"minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "max" \| "ultra"` | Explicit Codex reasoning effort override. |
  69. | `file_paths` | `string[]` | Workspace-contained file paths to pass as focus paths (Codex) or attach inline up to 512 KiB (HTTP). |
  70. | `workspace_dir` | `string` | Base workspace directory for `file_paths`, `input_images`, and `output_file`. Defaults to `cwd`. |
  71. | `output_file` | `string` | Workspace-relative path to write the response text (do **not** combine with `workspace-write` or `danger-full-access` on Codex). |
  72. | `input_images` | `string[]` | Workspace image paths to attach (`codex` provider only). |
  73. | `thread_id` | `string` | Codex thread ID to resume an existing conversation. |
  74. | `session_id` | `string` | Stable OpenCode session ID (`ses_...`) for cache routing. |
  75. | `system_prompt` | `string` | Optional system instruction override. |
  76. | `temperature` | `number` (`0`–`2`) | Sampling temperature for HTTP providers. |
  77. | `max_tokens` | `integer` | Output token cap for HTTP providers. |
  78. | `include_reasoning` | `boolean` | Include `<reasoning>` output when returned. |
  79. ### `list_offload_models`
  80. Reports provider configuration/auth status and lists available models for the selected (or default) provider, supporting case-insensitive substring `filter`. For `codex`, it reads `$CODEX_HOME/models_cache.json` and annotates visible models with Pareto badges, default effort, and supported reasoning levels.
  81. ### `generate_image`
  82. Generates or edits PNG images via Codex's built-in `$imagegen` (`gpt-image-2`) capability.
  83. | Parameter | Type | Description |
  84. | --- | --- | --- |
  85. | `prompt` | `string` *(required)* | Image generation or editing prompt (`$imagegen` is prefixed automatically if absent). |
  86. | `output_file` | `string` | Workspace-relative target path (e.g., `"assets/hero.png"`). Additional generated images receive `-2`, `-3` suffixes. |
  87. | `workspace_dir` | `string` | Base directory for `output_file` and `input_images`. |
  88. | `input_images` | `string[]` | Workspace reference images for editing or style guidance. |
  89. | `thread_id` | `string` | Previous `generate_image` thread ID for iterative refinement. |
  90. | `model` | `string` | Optional Codex model override. |
  91. ---
  92. ## Automatic Codex Model & Reasoning-Effort Selection
  93. When `provider` resolves to `codex` and `model` / `codex_reasoning_effort` are omitted, `offload_task` inspects `$CODEX_HOME/models_cache.json` (default `~/.codex/models_cache.json`), filters to entries with `visibility === "list"`, sorts by `priority` ascending, and picks the lowest-priority non-legacy model (`upgrade == null`, non-legacy description) in each Pareto family:
  94. | `task_tier` | Preferred Codex Family | Reasoning Effort | Typical Use Cases |
  95. | --- | --- | --- | --- |
  96. | `auto` *(default)* | Inferred from prompt, `file_paths` count, and sandbox | Per inferred tier | Automatic routing when you do not specify a tier. |
  97. | `quick` | `*-luna` (`read-only`), `*-sol` (writes enabled) | `medium` on Luna, `low` on Sol | Short summaries, PR/commit descriptions, docstrings, simple read-only tasks. |
  98. | `standard` | `*-sol` | `medium` | Everyday coding, localized edits, unit tests. |
  99. | `deep` | `*-sol` | `high` | Multi-file refactors (`>= 3` files), debugging, code reviews, audits. |
  100. | `frontier` | `*-astra` | `high` | Architecture, migrations, concurrency/race debugging, security threat modeling, `>= 6` files. |
  101. | `input_images` set | `*-terra` | `medium` (`high` for `deep`/`frontier`) | UI screenshots, visual debugging, computer-use inspection. |
  102. ### Routing Rules & Precedence
  103. 1. **Override Precedence:** Explicit tool arguments (`model`, `codex_reasoning_effort`) > environment overrides (`CODEX_MODEL`, `CODEX_REASONING_EFFORT`) > Pareto router (`task_tier` or `"auto"` heuristic) > Codex SDK default (`chatgpt-subscription-default`).
  104. 2. **Effort Clamping:** Auto-selected reasoning efforts are clamped to the chosen model's `supported_reasoning_levels` (nearest lower supported effort, then `default_reasoning_level`). Explicit `xhigh`, `max`, and `ultra` values pass directly when requested.
  105. 3. **Graceful Fallbacks:** Missing families fall back to `*-sol`, then the first visible cached model. If `models_cache.json` is missing or unreadable, omitted fields fall back to the Codex SDK default.
  106. 4. **Prompt Cache Preservation:** Resuming a `thread_id` without explicit `model`, `codex_reasoning_effort`, or non-`auto` `task_tier` preserves the thread's existing model and effort.
  107. ---
  108. ## Provider Resolution & Environment Variables
  109. When `provider` is omitted, the server resolves the active provider in this order:
  110. `DEFAULT_OFFLOAD_PROVIDER` -> `OPENCODE_GO_API_KEY` (or `OPENCODE_API_KEY` + `OPENCODE_USE_GO=1|true`) -> `OPENCODE_API_KEY` -> `DEEPSEEK_API_KEY` -> Codex auth (`CODEX_API_KEY` / `OPENAI_API_KEY` / `$CODEX_HOME/auth.json`) -> `opencode`.
  111. | Variable | Default | Purpose |
  112. | --- | --- | --- |
  113. | `DEFAULT_OFFLOAD_PROVIDER` | Auto-detected | Force default provider: `codex`, `opencode-go`, `opencode`, or `deepseek`. |
  114. | `OFFLOAD_FALLBACK_ORDER` | `codex,opencode-go,opencode,deepseek` | Comma-separated fallback chain across configured providers. |
  115. | `CODEX_HOME` | `~/.codex` | Codex directory for `auth.json`, `models_cache.json`, `generated_images/`, and synced `skills/`. |
  116. | `CODEX_MODEL` | Unset | Default Codex model slug when `model` argument is omitted. |
  117. | `CODEX_REASONING_EFFORT` | Unset | Default Codex effort (`minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra`) when omitted. |
  118. | `CODEX_AUTO_SELECT` | Enabled | Set to `0` or `false` to disable Pareto auto-selection and use only overrides/SDK defaults. |
  119. | `CODEX_WINDOWS_SANDBOX` | `unelevated` | Windows sandbox mode passed for `workspace-write` (`prefer_mxc: true`). |
  120. | `CODEX_API_KEY` / `OPENAI_API_KEY` | Unset | Optional API key auth for Codex instead of ChatGPT subscription login. |
  121. | `OPENCODE_GO_API_KEY` | Unset | API key for OpenCode Go subscription endpoint. |
  122. | `OPENCODE_API_KEY` | Unset | API key for OpenCode Console (also reused by OpenCode Go). |
  123. | `OPENCODE_USE_GO` | Unset | Set `1` or `true` to prefer `opencode-go` when using `OPENCODE_API_KEY`. |
  124. | `OPENCODE_MODEL` | `deepseek-v4.1-flash` | Default model for `opencode`. |
  125. | `OPENCODE_GO_MODEL` | `kimi-k3` | Default model for `opencode-go`. |
  126. | `OPENCODE_BASE_URL` | `https://opencode.ai/inference` | Base URL override for OpenCode Console. |
  127. | `OPENCODE_GO_BASE_URL` | `https://opencode.ai/inference/go` | Base URL override for OpenCode Go. |
  128. | `DEEPSEEK_API_KEY` | Unset | API key for DeepSeek API. |
  129. | `DEEPSEEK_MODEL` | `deepseek-chat` | Default model for `deepseek`. |
  130. | `DEEPSEEK_BASE_URL` | `https://api.deepseek.com/v1` | Base URL override for DeepSeek API. |
  131. ---
  132. ## Recommended Global Rule (`~/.gemini/GEMINI.md`)
  133. Add the following to `~/.gemini/GEMINI.md` (or your project `AGENTS.md`) so Antigravity delegates automatically and writes diff-backed PR descriptions:
  134. ```markdown
  135. # Global Offloading Rule
  136. When `offload-worker` tools (`offload_task`, `generate_image`) are available in `<mcp_servers>`:
  137. 1. **Delegate heavy work first:** Before reading/editing multiple files or writing substantial code/tests/refactors inline, call `offload_task` (`provider="codex"`, `codex_sandbox="workspace-write"` for edits/tests; `"read-only"` for reviews/audits). Do not pre-read large target files in Antigravity first.
  138. 2. **Image tasks:** Use `generate_image` with `output_file` for image creation or editing.
  139. 3. **Fallback on errors:** If `codex` hits quota, rate limits, auth errors, or fails, allow `offload_task` to fall back to `opencode-go`, `opencode`, or `deepseek` (or retry explicitly with one of those `provider` values). If all offload providers fail or `offload_task` is disabled in the current session, execute directly.
  140. 4. **Skip offloading for trivial turns:** Answer simple questions, 1-line commands, or single small lookups directly without spawning an offload call.
  141. 5. **Verify after writes:** Run targeted tests or `git diff --stat` after `workspace-write` tasks before reporting completion.
  142. 6. **PR descriptions:** Before `gh pr create` (or `gh pr edit`), run a `read-only` `offload_task` against `git diff origin/main...HEAD` (or the target base branch) to generate a structured PR body in normal prose (no caveman compression) with grouped `### Changes` (exact file paths and symbol names) and `### Verification` (exact test/build output). Write the PR body to a scratch `.md` file and pass it via `gh pr create --body-file <path>` to avoid PowerShell newline/backtick mangling.
  143. ```
  144. Rule 6 prevents weak PR descriptions caused by summarizing only `offload_task`'s short reply, PowerShell `--body "..."` newline/backtick mangling, or terse prose bleeding into PRs.
  145. ---
  146. ## Project Layout & Development
  147. ```text
  148. src/
  149. index.ts MCP server registration & tool schemas
  150. codex.ts Codex SDK runner, auth status, and $imagegen integration
  151. codex-models.ts models_cache.json discovery & Pareto model/effort router
  152. providers.ts OpenCode / DeepSeek HTTP clients, provider resolution, fallback chain
  153. files.ts Workspace-contained file reading/writing & 512 KiB attachment limit
  154. skills/
  155. offload-worker/ Bundled Antigravity / Codex skill instructions
  156. sync-skills.cjs Startup skill junction/symlink synchronizer
  157. test/
  158. server.test.ts Unit & in-memory/stdio MCP integration tests
  159. sync-skills.test.cjs Skill synchronization tests (uses local mcp_config.json)
  160. ```
  161. Run build and test verification:
  162. ```bash
  163. npm run build
  164. npm test
  165. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.