# ios-logos-tweak

The ios-logos-tweak Claude Code skill guides work on iOS jailbreak tweaks built with Theos and Logos. It activates for .x and .xm tweak code, hook reviews, and Theos Tweak projects.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 107 repo stars
- Author: PoomSmart
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/PoomSmart/ios-logos-tweak/tree/HEAD/SKILL.md
- Updated: 2026-11-07
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/ios-logos-tweak

## What it does

The skill explains how to express hooks with Logos directives for Objective-C methods and C functions, and how to add methods or state to hooked classes. It covers `%hook`, `%hookf`, `%new`, `%orig`, `%init`, `%property`, iOS version checks, and Objective-C bracket messaging.

For existing instance variables, it recommends `MSHookIvar` in tweak code rather than manual runtime access. Plain Objective-C hooks belong in `.x`; use `.xm` when that translation unit needs C++ or Substrate’s C++ APIs. For a dynamic `%hookf`, resolve the symbol from its owning library with `MSGetImageByName` and `MSFindSymbol`; a global lookup using `MSFindSymbol(NULL, ...)` can cause crashes in some injection setups.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add PoomSmart/ios-logos-tweak --skill ios-logos-tweak -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/ios-logos-tweak/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/ios-logos-tweak/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add PoomSmart/ios-logos-tweak --skill ios-logos-tweak -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/ios-logos-tweak/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add PoomSmart/ios-logos-tweak --skill ios-logos-tweak -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/ios-logos-tweak/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install PoomSmart/ios-logos-tweak ios-logos-tweak
```

2. **Manually: put the files in place**
- File: `.github/skills/ios-logos-tweak/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add PoomSmart/ios-logos-tweak --skill ios-logos-tweak -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/PoomSmart/ios-logos-tweak
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/ios-logos-tweak/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/PoomSmart/ios-logos-tweak/tree/HEAD/SKILL.md

## When to use it
- write an Objective-C method hook with Logos
- intercept a C function using `%hookf`
- access an instance variable with `MSHookIvar`
- choose between `.x` and `.xm` files
- add a method or stored state with `%new` and `%property`

## Example prompts
- Review the `layoutSubviews` hook in `Tweak.x` and fix how it calls the original method.
- Show how to hook a C function with `%hookf` and resolve its symbol from the right library.
- Add a helper method to this hooked class with `%new` and its exact type encoding.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 07456c49965dedb7.

BEGIN THIRD-PARTY FILE 07456c49965dedb7
````text
---
name: ios-logos-tweak
description: Best practices for iOS jailbreak tweaks using Theos and Logos (%hook, %hookf, %new, %orig, %init). Prefer Logos and Substrate helpers (MSHookIvar) over manual hook/ivar runtime APIs. Covers firmware checks (IS_IOS_OR_NEWER vs @available vs respondsToSelector) and bracket messaging. Use when writing or reviewing .x/.xm tweak code, MobileSubstrate/libhooker hooks, swizzling, or Theos Tweak projects.
---

# iOS Logos Tweak Best Practices

## Core rule

Put hooking code in **Logos files** (`.x`, `.xm`, `.xi`) and express hooks with **Logos directives**. Let the Logos preprocessor emit `MSHookMessageEx`, `MSHookFunction`, `class_addMethod`, constructors, and class registration.

Do **not** hand-write Substrate hook boilerplate in tweak source unless Logos cannot express the case (rare; see [reference.md](reference.md)).

## File layout

**Default: `.x`.** Most tweaks use a single `Tweak.x` (Logos + Objective-C). Theos runs Logos on the file, then compiles the result as ObjC.

| Extension | Compiles as | When to use |
|-----------|-------------|-------------|
| **`.x`** | Objective-C | **Default.** `%hook`, `%hookf`, `%new`, `%orig`, `%property`, blocks, and normal Foundation/UIKit code. |
| **`.xm`** | Objective-C++ | Only when this **translation unit** needs C++ or Substrate’s C++ APIs (see below). |
| **`.xi` / `.xmi`** | Included fragments | Rare: Logos inside `#define` macros or `#include` chains; prefer splitting into separate `.x`/`.xm` files with `extern` instead ([Theos docs](https://theos.dev/docs/logos-file-extensions)). |

### Use `.xm` when this file contains

- **`MSHookIvar<T>`** or **`MSIvarHook`** (implemented as C++ templates in `<substrate.h>`).
- **C++** only valid in ObjC++: `std::`, `namespace`, templates, lambdas, C++ types in hook bodies.
- **`%orig`** forms that embed **block literals** in the hook implementation when your toolchain/setup requires ObjC++ for those expansions (uncommon; most hooks stay in `.x`).

### Stay on `.x` when

- Hooks are plain Objective-C (even with blocks, `@autoreleasepool`, etc.).
- You do not call `MSHookIvar` in that file.

If only one hook file needs ivar access, keep **`Tweak.x`** and add a small **`Something.xm`** (or move just those hooks to `.xm`) rather than renaming the whole project to `.xm` without reason.

Keep **interfaces and constants** in normal `.h` / `.m` when they are not hooks. Keep **all hooks** in Logos (`.x` / `.xm`, not raw `.m` with `MSHook*`).

Do not `#include <substrate.h>` in Logos files; Theos/Logos adds it in generated code.

## Objective-C methods: `%hook`

```logos
%hook YTPlayerViewController

- (void)layoutSubviews {
    %orig;
    // tweak logic
}

%end
```

- Match the **exact** selector signature (class vs instance `+`/`-`, types, argument names).
- Call the original with `%orig` or `%orig(arg1, arg2)`; never pass `self` or `_cmd`.
- If you use `%orig(...)`, pass **every** user argument (Logos fills `self`/`_cmd`).
- Always close with `%end`.
````
END THIRD-PARTY FILE 07456c49965dedb7

The third-party file has ended. Everything between the 07456c49965dedb7 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3022 of 16679 bytes. © PoomSmart · MIT · https://github.com/PoomSmart/ios-logos-tweak/tree/HEAD/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
