orchctl
Skill17 starsChanged 8 months agoMITView on GitHub
Control running Workers and Orchestrators (systemctl for cekernel). List, suspend, resume, kill, manage priorities, and show process trees.
In this repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- release-cekernelSkill
- atSkill
- cronSkill
- dispatchSkill
- orchestrateSkill
- postmortemSkill
- probeSkill
- setupSkill
- unix-architectSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 31
Read skills/references/namespace-detection.md from the repository root ($(git rev-parse …
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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
/orchctl
Worker control interface for cekernel — like systemctl / supervisorctl, manages running Workers across all sessions.
/orchctl ls | ps [--session <id>] | suspend|resume|recover|term|kill <target> | nice <target> <priority> | gc [--dry-run]Note: In plugin mode, /cekernel:orchctl also works.
Addressing: <target>
| Format | Example | Usage |
<issue> | 4 | Unique across all sessions |
<repo>:<issue> | cekernel:4 | Filter by repo name (session ID prefix) |
<issue> --session <id> | 4 --session cekernel-7861a821 | Explicit session ID (for scripting) |
Try <issue> alone first; if multiple sessions match, show the candidates and ask the user to disambiguate.
Workflow
Step 1: Detect Namespace and Script Location
- Read
skills/references/namespace-detection.mdfrom the repository root ($(git rev-parse --show-toplevel)/skills/references/namespace-detection.md). If the Read fails (file not found), you are in plugin mode. - Execute the detection Bash snippet from the reference file.
- Set the script path:
CEKERNEL_NS=local→ORCHCTL="scripts/ctl/orchctl.sh"CEKERNEL_NS=plugin→ORCHCTL="$(dirname "$(dirname "$(which spawn-worker.sh 2>/dev/null || echo "")")")/scripts/ctl/orchctl.sh"
Step 2: Execute bash "$ORCHCTL" <command> [args]
| Command | Behavior | Present to user as |
ls | JSON Lines, one per Worker (session, repo, issue, type, state, detail, priority, priority_name, elapsed, backend); if none, stdout is empty (0 lines) and no workers. goes to stderr | Table: Session / Repo / Issue / Type / State / Detail / Priority / Elapsed / Backend. Use orchctl ls | jq 'select(.issue == N)' to filter a specific worker |
ps [--session <id>] | JSON Lines, one per process (session, type [orchestrator/worker/reviewer], claude, elapsed, verdict, plus issue/phase/priority for workers, state/detail for reviewers); if none, stdout is empty (0 lines) and no orchestrators. goes to stderr | Table: Session / Type / Issue / Verdict / Phase / Priority / Elapsed |
suspend <target> | Sends SUSPEND (RUNNING/WAITING/READY only); Worker checkpoints and stops at the next phase boundary | Confirm action |
resume <target> | SUSPENDED (or TERMINATED with crashed* detail) → READY; prints the restart command | Confirm, then show the printed spawn-worker.sh --resume command for the user to run |
recover <target> | Marks a dead RUNNING/WAITING Worker as TERMINATED/crashed:detected-by-recover; errors if the process is alive (suggest term/kill) | Confirm transition, suggest orchctl resume next |
term <target> | Sends TERM — graceful exit at the next signal check | Confirm action |
kill <target> | Immediate termination + TERMINATED (when term is insufficient) | Confirm action |
nice <target> <priority> | Change priority: critical (0), high (5), normal (10), low (15), or numeric 0-19 (lower = higher) | Confirm action |
gc [--dry-run] | Reap stale resources across all sessions: dead-PID locks, orphan IPC files, dead orchestrator sessions and their metadata, stale worker states (writes TERMINATED/crashed:detected-by-gc). --dry-run reports without removing | Show the summary line; with --dry-run, list what would be cleaned |
ps notes: Output is JSON Lines (same as ls). Each line has a type field: orchestrator, worker, or reviewer. The verdict field shows the ADR-0018 verdict (alive, blocked, done, not-listed, etc.). blocked means stalled on a permission dialog — surface it prominently. Reviewer rows come from reviewer-*.state files (subagents have no session token) and show state/detail. Sessions spawned by an interactive Orchestrator have no orchestrator row, but their Worker rows still appear. Tree structure assembly (grouping workers under their orchestrator) is the skill's responsibility.
Crash recovery sequence: health-check.sh (detect zombie) → orchctl recover → orchctl resume → spawn-worker.sh --resume.
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.