bgshell-job

Stars8

Forks0

UpdatedJuly 8, 2026 at 17:59

Launch, monitor, stop, list, or resume long-running non-GPU local shell tasks without relying on one shell timeout. Use this when the user asks to run local build/release/maintenance commands that may outlive one shell call or one OpenCode session.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

vhqtvn

vhqtvn/vh-solara

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Network and Computer Systems AdministratorsComputer and Mathematical Occupations·SOC 15-1244

File Explorer

2 files

SKILL.md

readonly

name	bgshell-job
description	Launch, monitor, stop, list, or resume long-running non-GPU local shell tasks without relying on one shell timeout. Use this when the user asks to run local build/release/maintenance commands that may outlive one shell call or one OpenCode session.
compatibility	opencode

BG Shell Job

Use this for repo-local non-GPU shell work that may outlive one shell call or one OpenCode session.

Required workflow

Prefer a session alias (/session-start <alias>), or pass --session <alias>.
Launch detached via helper:
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py launch --job <name> -- <command ...>
Poll status/logs with short calls:
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py status --job <name> --lines 40
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py logs --job <name> --lines 80
Stop explicitly when needed:
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py stop --job <name> --force
Recover after compaction/session loss:
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py list
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py status --job-dir tmp/agent-runs/<alias>/bg-jobs/<name>
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py resume --job-dir tmp/agent-runs/<alias>/bg-jobs/<name>

Helper behavior

State is saved under:

tmp/agent-runs/<session-alias>/bg-jobs/<job-name>/job.json
tmp/agent-runs/<session-alias>/bg-jobs/<job-name>/job.log

Output

job id and session alias
exact launch/status/stop/resume command used or recommended
current state: queued, starting, running, succeeded, failed, stopped, interrupted
smallest safe next step

When not to use

do not use this for GPU work
do not use this for quick commands that complete inside one shell call
do not use this as a substitute for CI or remote job scheduling

More from this repository

same repository

harness-operator

vhqtvn/vh-solara

Operate the vh-solara agent harness itself — install, self-update, run the upgrade loop, read release migration notes, and use guide/update/doctor. Load this skill when asked to install, update, or operate the harness, or to read what changed in a release.

2026-07-258

backlog

vhqtvn/vh-solara

Backlog ledger discipline for vh-solara — conflict-safe edits to docs/planning/backlog.md (hybrid split-commit) plus DEFER/follow-up curation routing. Load this skill before editing the backlog, when handling a cas_conflict on the backlog, or when deciding where a DEFER/p2 finding should land.

2026-07-228

media-perception

vhqtvn/vh-solara

Caller-facing routing aid for media-perception in vh-solara — decide between in-context perception (vision-capable caller) and single-delegation to the media-perception specialist (text-only caller or heavy/multi-step perception). Load this skill when you hold an image, diagram, chart, video, document/PDF, or audio locator and need to decide how to perceive it.

2026-07-228

debugging-loop

vhqtvn/vh-solara

Debugging loop for existing bugs — build a deterministic red signal FIRST, then reproduce, minimise, hypothesise, instrument, fix, regression-test, with a 3-line post-mortem. Use this when fixing a bug, chasing a failure, or reproducing a defect. Includes an explicit downgrade-to-human handoff when deterministic red is unavailable.

2026-07-158

skill-creator

vhqtvn/vh-solara

Guide for creating and updating repo-local OpenCode skills in this coding repository. Use this whenever a user asks to create, update, improve, validate, or troubleshoot a skill under `.opencode/skills/`, or when archived sessions should be distilled into reusable coding workflows.

2026-07-158

tdd-loop

vhqtvn/vh-solara

Test-driven development loop for new behavior — red, green, refactor, next vertical slice. Use this when adding or changing behavior test-first at pre-agreed seams. Loads when the user asks to TDD a feature, write tests first, drive an implementation with tests, or settle when refactor should happen.

2026-07-158

name	bgshell-job
description	Launch, monitor, stop, list, or resume long-running non-GPU local shell tasks without relying on one shell timeout. Use this when the user asks to run local build/release/maintenance commands that may outlive one shell call or one OpenCode session.
compatibility	opencode

BG Shell Job

Use this for repo-local non-GPU shell work that may outlive one shell call or one OpenCode session.

Required workflow

Prefer a session alias (/session-start <alias>), or pass --session <alias>.
Launch detached via helper:
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py launch --job <name> -- <command ...>
Poll status/logs with short calls:
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py status --job <name> --lines 40
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py logs --job <name> --lines 80
Stop explicitly when needed:
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py stop --job <name> --force
Recover after compaction/session loss:
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py list
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py status --job-dir tmp/agent-runs/<alias>/bg-jobs/<name>
- vh-agent-harness exec python .opencode/skills/bgshell-job/scripts/bgshell_job.py resume --job-dir tmp/agent-runs/<alias>/bg-jobs/<name>

Helper behavior

State is saved under:

tmp/agent-runs/<session-alias>/bg-jobs/<job-name>/job.json
tmp/agent-runs/<session-alias>/bg-jobs/<job-name>/job.log

Output

job id and session alias
exact launch/status/stop/resume command used or recommended
current state: queued, starting, running, succeeded, failed, stopped, interrupted
smallest safe next step

When not to use

do not use this for GPU work
do not use this for quick commands that complete inside one shell call
do not use this as a substitute for CI or remote job scheduling