cannibal

name

cannibal

description

Patch and extend the installed macOS Codex desktop app by editing `/Applications/Codex.app`, including header buttons, side panels, message rendering, Electron bundle behavior, `app.asar` patching, `ElectronAsarIntegrity` updates, ad hoc re-signing, rollback backups, and relaunch/resume checkpoints. Use when Codex needs to inspect, modify, repair, re-sign, relaunch, or resume work on the installed app on macOS, especially after prompts that explicitly mention `$cannibal`, Codex modifying itself, top-right toolbar changes, side panels, chat UI changes, installed app patches, or restarting Codex without losing progress.

Cannibal

Overview

Use this skill to patch the installed macOS Codex app in a controlled, repeatable way. Treat the repo copy at skills/cannibal/ as the source of truth and sync it into ${CODEX_HOME:-$HOME/.codex}/skills/cannibal after edits so Codex can invoke $cannibal on this machine.

Read the relevant reference before acting:

• Read references/bundle-layout.md before touching the bundle.
• Read references/ui-patching.md for renderer and toolbar changes.
• Read references/restart-resume.md before any relaunch flow.

Always call out the current phase in commentary: discover, patch, sign, relaunch, resume, or verify.

Quick Start

1. Confirm macOS and default to /Applications/Codex.app unless the user explicitly points at a different bundle.
2. Derive the bundle paths:
   • Contents/Resources/app.asar
   • Contents/Info.plist
   • skill entitlements at scripts/codex_demo.entitlements.plist
3. Create a temp work dir in /tmp and a rollback dir under /tmp/cannibal-backups/.
4. Extract only the files needed for the requested change with:

node scripts/codex_asar_tool.js extract "$APP_ASAR" "$WORK_DIR" <file1> [file2 ...]

5. Generate a task-specific patch script or temp edited files in the work dir. Do not hand-edit the installed app bundle in place.
6. Rebuild app.asar, compute the ASAR header hash, install, re-sign, and verify.

Preflight

• Confirm the target bundle exists and stop immediately if it does not.
• Inspect the current bundle files before choosing patch markers. Do not assume symbol names or asset file names.
• Prefer marker-based replacements over brittle byte offsets.
• Keep backups and checkpoints separate:
  • rollbacks in /tmp/cannibal-backups/
  • checkpoints in /tmp/cannibal-checkpoints/
• Never intentionally kill the currently controlling Codex instance from inside that same session.

Mutation Workflow

1. Discover

• Inspect the installed bundle structure and extract only the current files you need.
• Confirm the real main/renderer asset names from the installed app before writing patch logic.
• If the request touches toolbar buttons, side panels, webviews, or message rendering, read references/ui-patching.md.

2. Patch

• Create a task-specific patch script in the temp work dir.
• Keep reusable helper logic in the task patch script:
  • replaceOnce
  • replaceSection
  • explicit marker validation
• Patch extracted files, not the installed app directly.
• Repack with:

node scripts/codex_asar_tool.js pack "$SOURCE_ASAR" "$WORK_DIR" "$OUT_ASAR"
node scripts/compute_asar_header_hash.js "$OUT_ASAR"

3. Sign

• Back up the current installed app.asar and Info.plist.
• Install the rebuilt app.asar, update ElectronAsarIntegrity, re-sign, and verify with:

zsh scripts/install_patched_codex.sh --app "$APP" --asar "$OUT_ASAR" --hash "$ASAR_HASH"

• Stop immediately if codesign --verify --deep --strict fails. Surface the exact error and rollback location.

4. Relaunch

• Before asking for relaunch, save a checkpoint with:

node scripts/checkpoint.js save --payload-json "$CHECKPOINT_JSON"

• Include:

  • task_summary
  • app_path
  • asar_path
  • plist_path
  • rollback_dir
  • work_dir
  • phase
  • artifacts
  • resume_prompt
  • status

• Ask the user to relaunch manually. Prefer one restart after batching related changes.

5. Resume

• On $cannibal resume or an equivalent prompt, load the latest unfinished checkpoint:

node scripts/checkpoint.js latest

• Restate the saved task summary, phase, rollback dir, and pending validation steps.
• After successful verification, mark the checkpoint complete:

node scripts/checkpoint.js complete

Response Rules

• Always say which phase you are in.
• Always surface the rollback directory after installation.
• Be explicit about whether relaunch is required or optional.
• Prefer concise status lines over long narration after the app patch is applied.
• If the skill itself changes, sync it into Codex home with:

zsh scripts/sync_to_codex_home.sh

Bundled Tools

• scripts/codex_asar_tool.js: extract and repack selected files inside app.asar
• scripts/compute_asar_header_hash.js: compute the SHA-256 hash used by ElectronAsarIntegrity
• scripts/install_patched_codex.sh: back up, install, re-sign, and verify the app bundle
• scripts/checkpoint.js: save, inspect, and complete relaunch checkpoints
• scripts/sync_to_codex_home.sh: sync the repo skill into ${CODEX_HOME:-$HOME/.codex}/skills/cannibal
• scripts/codex_demo.entitlements.plist: known-good entitlements for local ad hoc signing

Validation

• Validate the skill folder after edits:

python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" skills/cannibal

• Sync the validated skill into Codex home before relying on $cannibal.
• Dry-run helper scripts on backups or temp artifacts before patching the installed app.