Offload maintainer skill

The offload skill provides a high-performance, parallelized workflow for offloading intensive developer tasks to a remote workstation. It leverages a Node.js orchestrator to run complex validation playbooks concurrently in a dedicated terminal window.

Why use offload?

Protect local resources: Heavy build and lint suites are offloaded to a beefy remote workstation.
Context efficiency: The main Gemini session remains interactive while background tasks provide high-fidelity feedback.
True parallelism: Infrastructure validation, CI checks, and behavioral proofs run simultaneously, compressing a 15-minute process into 3 minutes.
Behavioral verification: The worker physically exercises the new code to provide empirical proof that it works.

Playbooks

review (default): Build, CI check, static analysis, and behavioral proofs.
fix: Iterative fixing of CI failures and review comments.
ready: Final full validation (clean install + preflight) before merge.
open: Provision a worktree and drop directly into a remote tmux session.

Scenarios and workflows

First-time setup

Run the setup command once to configure your remote environment:

npm run offload:setup

Offloading a task

To start an offload task for a pull request:

npm run offload <PR_NUMBER> [action]

Monitoring progress

Check status from your local shell without switching windows:

npm run offload:check <PR_NUMBER>

Cleanup

Wipe old PR worktrees and kill inactive sessions:

npm run offload:clean

Technical details

This skill uses an isolated Gemini profile on the remote host (~/.gemini-deep-review) to ensure that verification tasks do not interfere with your primary configuration.

Directory structure

scripts/orchestrator.ts: Local orchestrator (syncs scripts and pops terminal).
scripts/worker.ts: Remote engine (provisions worktree and runs playbooks).
scripts/check.ts: Local status poller.
scripts/clean.ts: Remote cleanup utility.
SKILL.md: Instructional body used by the Gemini CLI agent.

Contributing

If you want to improve this skill:

Modify the TypeScript scripts in scripts/.
Update SKILL.md if the agent's instructions need to change.
Test your changes locally using npm run offload <PR>.

Testing

The orchestration logic for this skill is fully tested. To run the tests:

npx vitest .gemini/skills/offload/tests/orchestration.test.ts

These tests mock the external environment (SSH, GitHub CLI, and the file system) to ensure that the orchestration scripts generate the correct commands and handle environment isolation accurately.

Future roadmap: Offload V2 (Fleet)

The current version of offload focuses on a persistent SSH workstation. The long-term vision for this tool includes:

Elastic compute: Moving from a single machine to a fleet of ephemeral remote containers (for example, using Cloud Run Jobs or GKE Pods).
Immutable base images: Building a Docker container for every commit to main to ensure a guaranteed, pristine verification environment.
Stateless execution: Eliminating the need for manual cleanup by using on-demand, disposable compute nodes for every offload task.
Massive parallelism: Enabling dozens of simultaneous PR reviews and implementations across the elastic fleet.

3.4 KiB Raw Blame History