collab-monitor
Skill0 starsChanged 19 days agoApache-2.0View on GitHub
Native Monitor for addressed collab mail on Claude/cmux seats, report DONE markers and installed-version watches. Codex/T3 seats: no polling turns; completion notifications wake you; a T3 lead keeps one lead name waiter. NOT for file-integrity auditing.
In this repository64 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- verify-lead-waitSkill
- verify-merge-receiptsSkill
- branded-docSkill
- explanatory-docSkill
- 1passwordSkill
- agada-benchSkill
- agent-browserSkill
- agent-routingSkill
- architectural-conformance-auditSkill
- audio-dashboardSkill
- brain-store-fallbackSkill
- claude-desktop-researchSkill
- cmux-agentsSkill
- cmuxSkill
- coachSkill
- coderabbitSkill
- codex-workflowsSkill
- content-demo-creationSkill
- convention-auditSkill
- cursor-workflowsSkill
- cyberSkill
- deploy-verifySkill
- drive-filingSkill
- eas-prebuild-checkSkill
- ecosystem-healthSkill
- eli5Skill
- false-green-gateSkill
- figma-loopSkill
- fleet-wrap-gateSkill
- fleet-wrapSkill
- frustration-captureSkill
- gemini-researchSkill
- git-guardianSkill
- github-researchSkill
- golem-installSkill
- grill-meSkill
- heredoc-guardSkill
- html-dashboardSkill
- human-confirm-gateSkill
- i-have-adhdSkill
- install-runbook-linterSkill
- large-planSkill
- m1-window-gateSkill
- model-pin-gateSkill
- never-fabricateSkill
- orcSkill
- plan-councilSkill
- pr-loopSkill
- qa-verdict-gateSkill
- qa-videoSkill
- repogolemSkill
- research-lifecycleSkill
- reviewer-order-gateSkill
- session-handoffSkill
- skill-creatorSkill
- stitch-designSkill
- t3-visualsSkill
- tmp-blockSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. About 0 are common, 10 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Use the native Monitor tool when the harness exposes it.
- Very specific: line 42
If something genuinely must sit and watch, dispatch one bounded codex.subagent.mechanical child per /agent-routing § Routing rules (SSOT).
- Very specific: line 54
Every worker brief says Report to <collab path>, not to the lead thread, then end your task.
- Distinctive: line 66
Don't dispatch from a waiter-woken T3 turn: a next step follows on the completion wake.
- Distinctive: line 73
Don't relay worker updates into chat.
- Very specific: line 77
Call Monitor({command, description, timeout_ms: 1800000}): a command, a short description naming the lane, and a 30-minute timeout.
- Very specific: line 83
Keep every timer wake inside the prompt-cache window (Claude ~60 min, Codex ~30 min): a Monitor timeout_ms, ScheduleWakeup delay or re-arm …
- Distinctive: line 92
Use the foreground routing filter as the native tool's command.
- Distinctive: line 109
Never point a test watch at a real lane's state root.
- Distinctive: line 158
If the report is missing or malformed, the watch stays open until its deadline.
- Distinctive: line 184
After a version match, run the required real-client smoke.
- Very specific: line 198
When a watch ends unexpectedly, repair it and re-arm before dispatch resumes.
- Very specific: line 199
When its task finishes, stop it.
- Distinctive: line 205
Only for a Codex seat running inside a cmux fleet with no T3 parent and no native Monitor.
- Distinctive: line 234
After handoff or lane closure:
- Very specific: line 253
Stop by listen name, never by a process-name pattern.
- Distinctive: line 278
Use live queries on every tick.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Collab Monitor
Use the native Monitor tool when the harness exposes it. Arm before dispatch, keep the returned watch identifier in the lane record, and stop it when its lane closes. Codex and T3 seats never poll collabs with turns; a T3 lead keeps one name waiter (next section), which also watches its lane collab (§ Lanes with a collab). A detached producer alone does not wake an agent.
Codex and T3 seats
The m1-launch-queue collab is now an admission ledger, not a request queue: agent-routing/references/cross-machine.md § 5.
"Codex seats must not poll collabs; T3 delegate completions already wake you." "No polling turns. No collab-monitor wakes in Codex" (Etan 2026-10-18, via orc collab)
Why: the weekly Codex quota drained in under 24 h, with the Codex "Collab Monitor" skill at 196 uses on Oct 18, and "Collab-monitor polling wakes cost another 201M across 729 turns." (Etan 2026-10-18, via orc collab)
- A Codex seat never arms collab-monitor, never runs
start/follow/run, and never polls a collab file with model turns, in a loop or on a schedule (a lead's one shell name waiter below is the only exception). - A T3 seat (any vendor) relies on its parent-owned wake signals:
delegate_taskcompletion notifications for child work andwatch_pull_requestfor PRs. Do not add a second watcher on top of them, apart from the lead name waiter below. - A T3 lead keeps exactly one name waiter armed at all times on the leads+orc
collab,
orchestrator/docs.local/collab/orc-inbox.md(lead rules §1, 2026-10-30), and on each lane collab it leads (§ Lanes with a collab): a background shell loop that exits on the first new@<handle>or@all-leadsline in the inbox, or the first new line addressed to its listen name in a lane collab. Register it witht3_background_waitand re-arm it on every wake. It costs no model turns until a line matches, so it is not a polling turn. Keep your own handle out of your own posts, or it wakes you. Workers and children never arm it. - If something genuinely must sit and watch, dispatch one bounded
codex.subagent.mechanicalchild per/agent-routing§ Routing rules (SSOT); resolve its model withnode scripts/model-roles.mjs codex.subagent.mechanical --use watcher. It reports once and exits; it never owns the parent's PR watch. - Native Monitor below is for Claude seats in a cmux fleet.
Lanes with a collab
"when there is a collab the message shouldn't travel through the chat, but have the monitor on the […] collab damn it" (Etan 2026-11-02, via orc)
- Every worker brief says
Report to <collab path>, not to the lead thread, then end your task.Workers append their status, DONE and BLOCKED lines to the collab, then end the task. - In T3, the task's end is the real wake. Workers send no separate thread message; they end normally (with the report pointer), and the completion notification wakes the lead, whose turn from it can dispatch the next step.
- The lead keeps ONE live monitor on the collab, for lines addressed to it. A Claude seat in a cmux fleet uses native Monitor (§ Collab tail with a lead filter), re-armed at expiry. A T3 lead (any vendor) extends the one name waiter above to the lane collab, so it adds no second waiter and no polling turns.
- In T3, that name waiter is for awareness only. A waiter wake can arrive as a
background-task turn, and T3 can refuse
delegate_taskfrom it (parent_not_active, reproduced twice on 2026-11-02; once it did dispatch). Don't dispatch from a waiter-woken T3 turn: a next step follows on the completion wake. Task-completion and PR-watch wakes can dispatch. In T3 the completion notification stays the liveness guard and the dispatch wake; the collab waiter carries the messages. - On a Claude cmux seat, the native Monitor is the completion watch too (§ Native Monitor first): act on an addressed BLOCKED/DONE line from its wake, including dispatching the next step.
- Don't relay worker updates into chat; chat is for Etan and orc's routing. No polling turns.
Native Monitor first
Call Monitor({command, description, timeout_ms: 1800000}): a command, a short
description naming the lane, and a 30-minute timeout. This Claude Code harness
caps the tool at 1800000 ms; other harness versions may differ, so check their
schema. Give it events that each require action; use one completion watch for
a batch of tests or CI jobs.
Keep every timer wake inside the prompt-cache window (Claude ~60 min, Codex
~30 min): a Monitor timeout_ms, ScheduleWakeup delay or re-arm interval is
≤50 min (3000000 ms) on a Claude seat and ≤25 min on a Codex seat. Never arm
3600 s: wakes past the window busted the cache 20 times in a week, costing
Claude 7.4M tokens (35 Monitor arms at 3600 s, cache audit 2026-10-19). Prefer
an event wake (a completion notification or watch_pull_request) over a timer.
Collab tail with a lead filter
Use the foreground routing filter as the native tool's command. Monitor owns the process and wakeups; the filter owns watermarks, hash dedup and author matching. This avoids spawning a detached producer before every native watch.
Monitor({
command: 'bash "$HOME/.claude/skills/collab-monitor/scripts/collab-monitor.sh" run --alias @<seat-id> @<lead-listen-name> /absolute/path/collab.md',
description: '<lane> addressed collab mail',
timeout_ms: 1800000,
})Replace the listen name, seat alias and file with the actual lane values. Use a
private, explicit state root via MONITOR_STATE_DIR when isolating a test watch.
Resolve the script from the skill location supplied by your harness; the example
uses this MacBook's installed ~/.claude/skills/collab-monitor symlink. Verify
the resolved script exists before arming; use its absolute path on other hosts.
Never point a test watch at a real lane's state root.
The bounded lead filter accepts word-bounded @<name> mentions, headers addressed
### author → name (also ->), and that lead's own <name>-w<N> / <name>-r<N>
DONE/BLOCKED lines. It excludes self-authored blocks, signature-only tags,
near-miss names and unrelated headings. Fenced and indented code cannot route
mail; an unclosed fence reports an incomplete poll and is retried. Add --alias
for each actual delivery name, not a broad prefix.
The first poll seeds existing history silently. Re-arming with the same state
root preserves dedup. New mail should produce NEW-FOR-@<name>; readiness alone
is not proof that the consumer received a message. Append collab posts with
cat >> or an append-only writer.
Repeated identical headings in one append-only file are separate occurrences.
The first retains its content hash; later ones carry episode=2, episode=3,
etc. Read that routed occurrence outside code in the alert's file for its report body
and pointer. Extending a body does not create another heading episode. Restart
preserves dedup; existing heading-only state silently seeds pre-watermark repeated
headings on its next successful growth poll. Identical copies at the same
occurrence in different watched files still share a dedup key. Use a unique final
completion heading per report episode so older installed monitors also catch it.
This repair does not attach a parent consumer or replay a missed report.
Report-file DONE markers
Set the report path and the exact marker in this command, then pass it as
Monitor's command with timeout_ms: 1800000. Check the exact final line,
not a DONE word in the report body. This watch completes once; read the report
and verify its requested artifact after it fires.
REPORT='/absolute/private/report.md'
DONE_MARKER='DONE_LANE'
deadline=$(( $(date +%s) + 1800 ))
while true; do
if [ -r "$REPORT" ] && [ "$(tail -n 1 "$REPORT")" = "$DONE_MARKER" ]; then
printf 'REPORT_DONE %s\n' "$REPORT"
exit 0
fi
if [ "$(date +%s)" -ge "$deadline" ]; then
printf 'REARM_REQUIRED report watch\n'
exit 0
fi
sleep 1 # Cheap local file-stat poll cadence; not an urgency signal.
doneA marker is a handoff signal, not proof of merge, publication or installation. If the report is missing or malformed, the watch stays open until its deadline.
Installed-version watches
Query the installed command, not the checkout, a merge receipt or a release tag.
Set the exact expected --version output and pass this body to native Monitor.
The command re-reads the installed binary on every tick, including replacements
at the same path.
TOOL='/absolute/path/installed-command'
EXPECTED_VERSION='expected exact version output'
deadline=$(( $(date +%s) + 1800 ))
while true; do
if current="$("$TOOL" --version 2>/dev/null)" && [ "$current" = "$EXPECTED_VERSION" ]; then
printf 'VERSION_MATCH %s\n' "$current"
exit 0
fi
if [ "$(date +%s)" -ge "$deadline" ]; then
printf 'REARM_REQUIRED installed-version watch\n'
exit 0
fi
sleep 1 # Cheap local file-stat poll cadence; not an urgency signal.
doneAfter a version match, run the required real-client smoke. A version string alone does not prove the installed service serves requests successfully.
Re-arm at 30 minutes
The 30-minute re-arm is the tool's hard expiry, not an optional reminder.
On expiry and after every compaction, re-check which lanes remain open and
re-arm their watches using current paths, identifiers and expected versions. Report/version examples emit REARM_REQUIRED after their 30-minute
budget. For a collab stream, cancel the prior native watch by its returned
identifier before replacing it; keep the same routing state to avoid history
replay. In this Claude Code harness, use TaskStop with the returned task id
to cancel early; check the current schema on other harness versions. Do not
leave duplicate streams attached.
When a watch ends unexpectedly, repair it and re-arm before dispatch resumes.
When its task finishes, stop it. Workers do not monitor their lead's reviewer.
Review routing: /agent-routing § Routing rules (SSOT). Follow an engine-issued
mailbox contract when one exists.
Legacy cmux-only adapter
Only for a Codex seat running inside a cmux fleet with no T3 parent and no native Monitor. Any T3 seat, or any Codex seat that can rely on completion notifications, stops at Codex and T3 seats. Record its listen name and PID, verify readiness, and attach its consumer to the orchestrator's monitored command session:
CM="$HOME/.claude/skills/collab-monitor/scripts/collab-monitor.sh"
# Or set CM to the absolute script path from your harness's skill catalog.
test -f "$CM" || { printf 'Missing collab-monitor script: %s\n' "$CM" >&2; exit 1; }
bash "$CM" start --alias @<seat-id> @<listen-name> /absolute/path/collab.md
bash "$CM" status @<listen-name>
bash "$CM" follow @<listen-name>run, follow, and the start producer exit cleanly when their owning agent
dies. Ownership is the nearest claude/codex ancestor, or the initial parent
when no agent ancestor exists; --owner-pid <pid> overrides it on all three
commands. start captures ownership before detaching and persists independently
of the invoking shell while that owner lives. Foreground run/follow also
exit on reparenting to PID 1; the packaged detached producer is exempt from that
parent check. Owner checks continue during sleep/tail waits (at most one second
apart), and normal cleanup reaps sleep/tail children and releases owned state.
follow replays the
current session log then streams new alerts, and exits when that named watch
stops. It is the attached consumer, not proof of a native Monitor tool on Codex.
For a caller-owned foreground process, use run; for a scheduled single poll,
use run --once. Both use the same bounded routing filter.
After handoff or lane closure:
bash "$CM" stop @<listen-name>status is read-only: it never acquires locks or prunes state. start prunes
inactive runtime records across its state root:
PID/instance/owner/ready records, stale run locks and abandoned event extracts.
Pruning retains logs, dedup hashes and size watermarks. A live producer or foreground
run keeps all its files, including when its token is inconsistent; active or
ownerless start locks younger than 30 seconds are preserved; older ownerless
locks are recoverable after interrupted publication. Pruning has signal cleanup.
Reused PIDs belonging to unrelated processes
are pruned without signaling them. start records the owner PID and status
prints owner_pid (unknown for older instances). Instance identity works across
checkout paths. run and follow exit and reap their children if the script or
any packaged helper disappears, including during long waits.
Stop by listen name, never by a process-name pattern. The implementation checks
PID and per-start identity before signaling. On STATE_CONFLICT, inspect the
preserved records; do not delete state or signal an unverified process.
Defaults: state ~/.local/state/collab-monitor/<listen-name>/, positive
POLL_SECONDS, readiness budget 30 seconds. START_TIMEOUT_SECONDS can extend
readiness to at most 86400 seconds; malformed intervals and names . / ..
are rejected. --include-self is for explicit audits only and labels those
records SELF-POST rather than inbound mail. Never share test state with a lane.
Limits and supervision
The filter detects byte-size shrink, retries transient missing/unreadable files, and reports incomplete polls. It does not detect same-size rewrites, messages outside the routing grammar, process death without a supervisor, or completion visible only in a worker registry. A crash between alert emission and persistence can duplicate the final alert: delivery is at-least-once.
You MUST NOT poll read_screen in a loop for a worker outcome. For headless Codex
workers use codex-workflows' watch: observe process completion, then read its
finished output once. A monitor observes an artifact, not whether a reviewer was
actually routed. Keep handoff ownership explicit in the lane's closure record.
Recurring payloads
Use live queries on every tick; never copy a stale PR state into the payload. Frame the tick with a timestamp, cycle and last verified action. Counters reset only on a verified side effect. Finish with dispatch, verify-and-decrement or escalate-park. Codex and T3 seats write no recurring collab-reading ticks (Codex and T3 seats). Scheduler-specific fallback guidance is in references/cron-payloads.md; it is not a prerequisite for native Monitor.
Evaluation
python3 skills/golem-powers/collab-monitor/evals/monitor-howto.py
python3 skills/golem-powers/collab-monitor/evals/episode-dedup.py
bash skills/golem-powers/collab-monitor/evals/run-evals.sh candidate
bash skills/golem-powers/collab-monitor/evals/live-two-file-smoke.sh
python3 skills/golem-powers/collab-monitor/evals/owner-exit.py
python3 skills/golem-powers/collab-monitor/evals/state-hygiene.pyThe how-to checks exercise synthetic report/version command transitions and
teaching contracts. The routing suite exercises the packaged filter and detached
fallback. Neither proves native Monitor execution on a harness where it is
unavailable. Agent-behavior scenarios are recorded separately in evals.json.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

