bgshell-job

Stars1

Forks0

UpdatedJuly 8, 2026 at 10:23

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-agent-harness

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-agent-harness

Operate the vh-agent-harness 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-241

harness-operator

vhqtvn/vh-agent-harness

Operate the {{PROJECT_NAME}} 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-241

media-perception

vhqtvn/vh-agent-harness

Caller-facing routing aid for media-perception in vh-agent-harness — 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-211

media-perception

vhqtvn/vh-agent-harness

Caller-facing routing aid for media-perception in {{PROJECT_NAME}} — 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-211

backlog

vhqtvn/vh-agent-harness

Backlog ledger discipline for vh-agent-harness — 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-211

backlog

vhqtvn/vh-agent-harness

Backlog ledger discipline for {{PROJECT_NAME}} — 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-211

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