minion-orchestrator

Orchestrates durable shell jobs and LLM subagents through a Postgres-backed job queue.

Updated Aug 17, 2026
One-click install
npx skills add https://github.com/AMC-JTC/gbrain-1 --skill minion-orchestrator-amc-jtc
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: minion-orchestrator
Source: https://github.com/AMC-JTC/gbrain-1/tree/main/plugin/skills/minion-orchestrator
Command: npx skills add https://github.com/AMC-JTC/gbrain-1 --skill minion-orchestrator-amc-jtc

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Long-running background work dies silently with the session, and completion events get swallowed, leaving users staring at silence while finished results sit unreported. This Skill routes shell jobs and LLM subagents through a durable, observable, steerable Postgres-backed queue so work survives restarts and results provably reach the user. ## Core Features & Use Cases - Unified job orchestration: Submit deterministic shell jobs (gbrain jobs submit shell) and LLM subagent jobs (gbrain agent run) through one queue with structured progress, token accounting, and transcripts. - Steerable lifecycle: Pause, resume, cancel, replay, and send mid-flight steering messages to running agents via MCP-callable tools. - Durable execution doctrine: A capability ladder (Minion job + deadman, cron-checked progress file, foreground buffering) plus content-addressed stage checkpoints for expensive multi-stage pipelines. - Use Case: You need to run gbrain extract all, a 40-minute operation. Submit it as a Minion job with a one-hour timeout, arm a deadman check in the same action block, and get a recovery report even if the completion event is swallowed. ## Quick Start Ask the agent to submit your long-running command as a gbrain job and arm a deadman so you are notified even if the completion event is lost.

Frequently Asked Questions about minion-orchestrator

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run a long gbrain operation in the background?

Submit it as a Minion job with gbrain jobs submit shell and an appropriate --timeout-ms, then arm a deadman check in the same action block. The job survives restarts and the deadman verifies the result was actually reported to you.

How do I spawn and steer an LLM subagent?

Use gbrain agent run with your prompt and an optional --tools allow-list. While it runs, send_job_message injects steering directives that the agent reads on each iteration, and pause_job, resume_job, or cancel_job control its lifecycle.

Why is my shell job stuck in waiting status?

Shell jobs require GBRAIN_ALLOW_SHELL_JOBS=1 set on the worker environment; without it the shell handler never registers and submissions wait silently. Also confirm a worker is running via gbrain jobs stats, since PGLite deployments have no daemon mode.

Can I submit shell jobs through MCP tools?

No. Shell job submission is CLI-only because shell is in PROTECTED_JOB_NAMES; MCP submission throws a permission_denied OperationError. Agents can still observe shell jobs via get_job, list_jobs, and get_job_progress, and can cancel or replay them.

What happens if a job finishes but I never see the result?

The deadman pattern covers swallowed completion events: a one-shot scheduled check fires after the expected finish time, verifies whether the result was reported, and posts a recovery report tagged with the job ID if it was not.

When should I not use the Minions queue?

Skip it for single simple operations under about 30 seconds, which can run inline, and for single search queries that should use the search tool directly. The queue is for durable, observable work that must survive restarts or fan out in parallel.