openrig-operator

Name: openrig-operator
Author: mvschwarz

56stars9forks

How to install openrig-operator?

mvschwarz/openrig/openrig-operator

$npx -y skills add mvschwarz/openrig --skill openrig-operator

Installs into the current project.

Summary

Use when debugging host-side OpenRig runtime issues: daemon reachability, Codex permission or writable-root failures, command approval friction, rate limits/account switches, helper cleanup, or topology health confusion. NOT for ordinary CLI operation (use openrig-user) or for ch

Files · 1

View on GitHub

SKILL.md

1	# OpenRig Operator
2
3	## Overview
4
5	This skill covers host/runtime/operator triage around OpenRig itself.
6	Use it when the problem may be the daemon, the shell/runtime surface, or stale helper processes rather than the product workflow you are trying to run.
7
8	> CANONICAL SURFACE NOTE (2026-05-11) — for durable queue routing while doing
9	> operator triage, use `rig queue` (daemon-backed SQLite). `rigx queue` is
10	> recovery-only fallback; qitems written there are invisible to daemon-backed
11	> reads and should not be used for new substantive work.
12
13	## When to Use
14
15	Use this skill when you see:
16	- `rig whoami --json` returning partial identity
17	- `rig ps --nodes --json` failing while some other `rig` commands still work
18	- `Sent to ...` plus `Verified: no`
19	- repeated unified-exec-process warnings
20	- suspicion that stale helper processes are accumulating
21	- Codex seats hit `Operation not permitted`, command approval friction, or stale writable roots
22	- Codex seats report usage-limit/rate-limit or need a ChatGPT account switch
23
24	Do not use this skill for normal product workflow routing, queue handling, or ordinary peer communication. Use `openrig-user` for that.
25
26	Do not use this skill to decide how to change OpenRig behavior. Changes
27	to the OpenRig product (CLI, daemon, UI, specs) happen in the openrig
28	product repo — operate that as a normal software project, not via
29	this troubleshooting skill.
30
31	## First Checks
32
33	Start with the minimum truthful operator read:
34
35	```bash
36	rig whoami --json
37	rig daemon status
38	rig ps --nodes --json
39	```
40
41	Interpret them together, not in isolation:
42	- partial `whoami` can mean identity is inferable while daemon-backed surfaces are degraded
43	- `daemon status` tells you whether the host daemon is up, not whether every seat can reach it cleanly
44	- `ps --nodes --json` is the best machine-readable topology check when it works
45
46	## Verification Drift Vs Send Failure
47
48	For `rig send`:
49	- `Sent to ...` + `Verified: yes` = strong positive delivery evidence
50	- `Sent to ...` + `Verified: no` = ambiguous delivery, not automatic failure
51	- no `Sent to ...` line or a hard error = send failure
52
53	When verification is ambiguous, check:
54	- direct reply
55	- `rig capture <session>`
56	- transcript evidence
57	- queue/outbox state if the message asked for a durable handoff
58
59	Do not blindly retry until you have checked one of those.
60
61	## Unified Exec Warning
62
63	If you see:
64
65	- `Warning: The maximum number of unified exec processes you can keep open is 60 ...`
66
67	treat it first as a host/tooling-layer warning, not as automatic proof that the OpenRig topology is unhealthy.
68
69	This warning can coexist with a healthy live topology.
70
71	## Safe Process Triage
72
73	Inspect the process surface first:
74
75	```bash
76	ps -axo pid,ppid,command \| rg 'tmux send-keys\|rig queue create\|tmux attach\|codex\|claude'
77	```
78
79	Think in layers:
80	- host/tooling layer: stale one-shot wrappers, session bookkeeping, helper shells
81	- topology layer: live `tmux attach` seats, live `codex` / `claude` runtimes, daemon health
82
83	Do not diagnose topology failure from tooling-layer warnings alone.
84
85	## Safe Cleanup Boundary
86
87	Usually safe to reap when clearly orphaned / one-shot:
88	- `tmux send-keys ...`
89	- short-lived shell wrappers created only to enqueue or send one message
90
91	Do not mass-kill:
92	- `tmux attach ...`
93	- `codex ...`
94	- `claude ...`
95	- other long-lived daemon/runtime processes
96
97	The point is to remove garbage, not workers.
98
99	## Terminal Node Escalation
100
101	Use a terminal node when evidence shows a seat-level sandbox/profile cannot perform required host work, but another approved operator surface can. This is an explicit operator lane, not a silent permission bypass.
102
103	Good fits:
104	- Codex/Claude seat cannot access Tart, SSH, tmux, queue directories, or host files needed for a proof
105	- a VM/test-proof or current-host-operator task needs real host capability
106	- another seat or terminal/sysadmin node has approved access and can return command evidence
107
108	Do not use this lane to bypass repo safety, dirty-worktree boundaries, review gates, or destructive-action approval. If the command would stop live rigs, delete data, reset git state, or mutate VM state beyond the acc

People who liked this also viewed

6 picks

Type

openrig-operator

56stars9forks

View on GitHub

How to install openrig-operator?

mvschwarz/openrig/openrig-operator

$npx -y skills add mvschwarz/openrig --skill openrig-operator

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# OpenRig Operator
2
3	## Overview
4
5	This skill covers host/runtime/operator triage around OpenRig itself.
6	Use it when the problem may be the daemon, the shell/runtime surface, or stale helper processes rather than the product workflow you are trying to run.
7
8	> CANONICAL SURFACE NOTE (2026-05-11) — for durable queue routing while doing
9	> operator triage, use `rig queue` (daemon-backed SQLite). `rigx queue` is
10	> recovery-only fallback; qitems written there are invisible to daemon-backed
11	> reads and should not be used for new substantive work.
12
13	## When to Use
14
15	Use this skill when you see:
16	- `rig whoami --json` returning partial identity
17	- `rig ps --nodes --json` failing while some other `rig` commands still work
18	- `Sent to ...` plus `Verified: no`
19	- repeated unified-exec-process warnings
20	- suspicion that stale helper processes are accumulating
21	- Codex seats hit `Operation not permitted`, command approval friction, or stale writable roots
22	- Codex seats report usage-limit/rate-limit or need a ChatGPT account switch
23
24	Do not use this skill for normal product workflow routing, queue handling, or ordinary peer communication. Use `openrig-user` for that.
25
26	Do not use this skill to decide how to change OpenRig behavior. Changes
27	to the OpenRig product (CLI, daemon, UI, specs) happen in the openrig
28	product repo — operate that as a normal software project, not via
29	this troubleshooting skill.
30
31	## First Checks
32
33	Start with the minimum truthful operator read:
34
35	```bash
36	rig whoami --json
37	rig daemon status
38	rig ps --nodes --json
39	```
40
41	Interpret them together, not in isolation:
42	- partial `whoami` can mean identity is inferable while daemon-backed surfaces are degraded
43	- `daemon status` tells you whether the host daemon is up, not whether every seat can reach it cleanly
44	- `ps --nodes --json` is the best machine-readable topology check when it works
45
46	## Verification Drift Vs Send Failure
47
48	For `rig send`:
49	- `Sent to ...` + `Verified: yes` = strong positive delivery evidence
50	- `Sent to ...` + `Verified: no` = ambiguous delivery, not automatic failure
51	- no `Sent to ...` line or a hard error = send failure
52
53	When verification is ambiguous, check:
54	- direct reply
55	- `rig capture <session>`
56	- transcript evidence
57	- queue/outbox state if the message asked for a durable handoff
58
59	Do not blindly retry until you have checked one of those.
60
61	## Unified Exec Warning
62
63	If you see:
64
65	- `Warning: The maximum number of unified exec processes you can keep open is 60 ...`
66
67	treat it first as a host/tooling-layer warning, not as automatic proof that the OpenRig topology is unhealthy.
68
69	This warning can coexist with a healthy live topology.
70
71	## Safe Process Triage
72
73	Inspect the process surface first:
74
75	```bash
76	ps -axo pid,ppid,command \| rg 'tmux send-keys\|rig queue create\|tmux attach\|codex\|claude'
77	```
78
79	Think in layers:
80	- host/tooling layer: stale one-shot wrappers, session bookkeeping, helper shells
81	- topology layer: live `tmux attach` seats, live `codex` / `claude` runtimes, daemon health
82
83	Do not diagnose topology failure from tooling-layer warnings alone.
84
85	## Safe Cleanup Boundary
86
87	Usually safe to reap when clearly orphaned / one-shot:
88	- `tmux send-keys ...`
89	- short-lived shell wrappers created only to enqueue or send one message
90
91	Do not mass-kill:
92	- `tmux attach ...`
93	- `codex ...`
94	- `claude ...`
95	- other long-lived daemon/runtime processes
96
97	The point is to remove garbage, not workers.
98
99	## Terminal Node Escalation
100
101	Use a terminal node when evidence shows a seat-level sandbox/profile cannot perform required host work, but another approved operator surface can. This is an explicit operator lane, not a silent permission bypass.
102
103	Good fits:
104	- Codex/Claude seat cannot access Tart, SSH, tmux, queue directories, or host files needed for a proof
105	- a VM/test-proof or current-host-operator task needs real host capability
106	- another seat or terminal/sysadmin node has approved access and can return command evidence
107
108	Do not use this lane to bypass repo safety, dirty-worktree boundaries, review gates, or destructive-action approval. If the command would stop live rigs, delete data, reset git state, or mutate VM state beyond the acc

People who liked this also viewed

6 picks

Type