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

> Learn how oh-my-codex cancellation skill terminates active workflows by detecting session states and updating mode. Prevent stale processes and orphaned workers.

- Repository: [Bellman/oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
- Tags: internals
- Published: 2026-04-03

---

**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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/modes/base.ts) (lines 78-90). This function performs atomic state updates by rewriting the mode's JSON configuration:

```json
{
  "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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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:

```bash

# Cancel current active mode(s)

$ omx cancel
Cancelled: ralph
Cancelled: ultrawork

```

Target specific sessions without affecting others:

```bash
$ omx cancel --session 1234abcd
Cancelled: ecomode

```

Purge legacy artifacts and force-clear all state:

```bash
$ 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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/ralph-state.json) and [`ultrawork-state.json`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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:

```typescript
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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/cli/index.ts), ensuring Autopilot stops before Ralph, and Ralph before linked Ultrawork instances.
- `cancelMode()` in [`src/modes/base.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/ralph-state.json) and [`ultrawork-state.json`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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.