How the Cancellation Skill Works Across Execution Modes in oh-my-codex

The cancellation skill in oh-my-codex terminates active OMX workflows by detecting session states, following a strict dependency order, and atomically updating mode status to prevent stale processes or orphaned workers.

The cancellation skill serves as the canonical mechanism for stopping any active Omni-mode eXecution (OMX) workflow in the Yeachan-Heo/oh-my-codex repository. Whether terminating a long-running autopilot session, a persistent Ralph loop, or a coordinated Swarm deployment, the skill ensures clean shutdowns across all execution modes by manipulating state files in .omx/state/sessions/.

Detecting Active Sessions via State Tools

Before termination begins, the cancellation skill enumerates active workflows using state tools such as state_list_active and state_get_status. These utilities scan the .omx/state/sessions/ directory to identify which modes currently have active: true flags in their JSON state files.

The detection phase builds a comprehensive map of running sessions, enabling the skill to determine which modes require cancellation without interfering with inactive or completed workflows.

The Dependency-Ordered Termination Sequence

The skill follows a strict cancellation hierarchy defined in src/cli/index.ts (lines 2527-2600) to prevent resource leaks and dependency conflicts. Modes terminate in this precise sequence:

1. Autopilot – Must stop first as it may own linked Ralph, UltraQA, or Ecomode instances
2. Ralph – Persists a loop; linked Ultrawork/Ecomode must clear together
3. Ultrawork – Parallel workers safely halted after parent Ralph termination
4. Ecomode – Token-efficient mode, independent but linked to Ralph
5. UltraQA – QA cycle that may depend on Autopilot/Ralph resources
6. Swarm – Shared SQLite marker independent of session scopes
7. Ultrapilot – Parallel autopilot workers
8. Pipeline – Sequential chain of agents
9. Team – tmux-based multi-agent session requiring special shutdown
10. Plan Consensus – Stand-alone planning session

This ordering ensures that parent modes release resources and child workers receive termination signals before orphaning processes.

Atomic State Updates in src/modes/base.ts

Each mode cancellation invokes cancelMode() from src/modes/base.ts (lines 78-90). This function performs atomic state updates by rewriting the mode's JSON configuration:

{
  "active": false,
  "current_phase": "cancelled",
  "completed_at": "<ISO-timestamp>",
  "last_turn_at": "<ISO-timestamp>"
}

The atomic write prevents race conditions during concurrent shutdowns, ensuring that state files never reflect partial or inconsistent cancellation statuses.

Handling Linked Modes and Team Shutdowns

Ralph modes require special handling due to linked execution contexts. When cancelModes() detects an active Ralph session with linked_ultrawork or linked_mode === 'ultrawork' (handled in src/cli/index.ts, lines 83-92), it automatically cascades the cancellation to the linked Ultrawork or Ecomode instance immediately after terminating Ralph.

Team mode implements a two-pass shutdown protocol described in skills/cancel/SKILL.md (lines 62-74). The skill detects .omx/state/team/*/config.json, writes shutdown inbox messages to each worker, sends tmux keystrokes, force-kills any remaining panes, and finally removes the tmux session and state directory.

CLI Usage and Force Options

Users invoke cancellation through the CLI entry point:

# Cancel current active mode(s)

$ omx cancel
Cancelled: ralph
Cancelled: ultrawork

Target specific sessions without affecting others:

$ omx cancel --session 1234abcd
Cancelled: ecomode

Purge legacy artifacts and force-clear all state:

$ omx cancel --force
All session state and legacy files removed.

When --force or --all flags are present, the skill calls the low-level state_clear routine to remove legacy files such as ralph-state.json and ultrawork-state.json from the .omx/state/ directory.

Programmatic API for Developers

Developers can import cancellation functions directly from the base module for custom implementations:

import { cancelMode, cancelAllModes } from "./src/modes/base.js";

// Cancel a specific mode (e.g., Ultrawork) in the current workspace
await cancelMode("ultrawork");

// Cancel everything that is still active
const cancelled = await cancelAllModes(); // returns ['autopilot', 'ralph', ...]
console.log("Cancelled modes:", cancelled);

Summary

• The cancellation skill detects active sessions by scanning .omx/state/sessions/ via state tools before terminating any workflows.
• Termination follows a strict dependency order defined in src/cli/index.ts, ensuring Autopilot stops before Ralph, and Ralph before linked Ultrawork instances.
• cancelMode() in src/modes/base.ts performs atomic state updates, setting active: false and current_phase: "cancelled" with ISO timestamps.
• Ralph-linked modes and Team tmux sessions receive specialized shutdown handling to prevent orphaned processes.
• CLI users can target specific sessions with --session or purge legacy files using --force and --all flags.

Frequently Asked Questions

What is the cancellation skill in oh-my-codex?

The cancellation skill is the canonical mechanism for terminating active OMX (Omni-mode eXecution) workflows across all execution modes in the oh-my-codex repository. It ensures clean shutdowns by updating state files atomically and following dependency hierarchies to prevent resource leaks and orphaned workers.

How does the cancellation skill handle linked execution modes?

When cancelling a Ralph mode that has linked_ultrawork enabled, the skill automatically terminates the associated Ultrawork or Ecomode session immediately after Ralph shuts down. This cascading cancellation, implemented in src/cli/index.ts, prevents orphaned parallel workers from continuing execution independently.

What happens when I use the --force flag with omx cancel?

The --force or --all flag triggers state_clear to purge legacy state files such as ralph-state.json and ultrawork-state.json in addition to cancelling active modes. This removes all residual artifacts from the .omx/state/ directory, performing a complete cleanup of the workspace.

Can I cancel a specific session without affecting other active modes?

Yes, the cancellation skill accepts a session ID parameter through the CLI. Running omx cancel --session <id> targets only that specific session's state files, leaving other active modes unaffected and continuing their execution normally.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}