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:
```bash
npm run offload:setup
```
### Offloading a task
To start an offload task for a pull request:
```bash
npm run offload <PR_NUMBER> [action]
```
### Monitoring progress
Check status from your local shell without switching windows:
```bash
npm run offload:check <PR_NUMBER>
```
### Cleanup
Wipe old PR worktrees and kill inactive sessions:
```bash
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:
1. Modify the TypeScript scripts in `scripts/`.
2. Update `SKILL.md` if the agent's instructions need to change.
3. Test your changes locally using `npm run offload <PR>`.
## Testing
The orchestration logic for this skill is fully tested. To run the tests:
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.
