InjectionNext Documentation

InjectionNext enables updating function implementations in an app without relaunching by leveraging Apple's linker code injection. The workflow consists of three parts:

1. Preparing the dynamic library: Recompiling source files into an object file and linking them into a dynamic library (using dlopen() for loading).
2. Loading and binding: Loading the library and redirecting call sites to the new implementations. This uses the fishhook library to rebind symbols by scanning the dynamic library's symbol table for mangled function names (Swift names typically start with $s).
3. Forcing redisplay: Triggering the UI to reflect changes. Since code changes don't automatically trigger UI updates, you must explicitly tell the UI to refresh.

Implementation is split between the InjectionNext.app (which manages the menu bar and controls the process) and the InjectionNext Swift package (which you add to your project to handle the socket connection, library loading, and binding).

To allow AI agents (like Cursor) to control InjectionNext, follow these steps to build the app, enable the control server, and install the MCP server component.

Prerequisites

• macOS with Xcode installed
• Node.js 18.14.1+
• InjectionNext.app built from this repository with ControlServer support.

1. Build InjectionNext

Clone the repository and build the app using xcodebuild. Note that this uses ad-hoc signing for local development.

# Clone and init submodules
git clone <repo-url>
cd InjectionNext
git submodule update --init --recursive

# Build the app
cd App
xcodebuild -project InjectionNext.xcodeproj \
  -scheme InjectionNext \
  -configuration Debug build \
  CODE_SIGN_IDENTITY="-" \
  CODE_SIGNING_REQUIRED=NO \
  CODE_SIGNING_ALLOWED=NO

The built app is located at: ~/Library/Developer/Xcode/DerivedData/InjectionNext-*/Build/Products/Debug/InjectionNext.app. You may optionally copy it to /Applications/.

2. Enable the ControlServer

The TCP control server is opt-in. You must enable it via defaults before launching the app:

# Enable
defaults write com.johnholdsworth.InjectionNext mcpServer -bool true

# Disable
defaults delete com.johnholdsworth.InjectionNext mcpServer

3. Install the MCP Server

Copy the mcp-server from the application's Resources directory to a writable location and install its dependencies:

# If installed in /Applications
cp -r /Applications/InjectionNext/Contents/Resources/mcp-server .

cd mcp-server
npm install

4. Configure Cursor

Add the server to your Cursor MCP configuration at ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "injection-next": {
      "command": "node",
      "args": ["/absolute/path/to/InjectionNext/mcp-server/index.js"]
    }
  }
}

Replace /absolute/path/to with your actual path.

5. Launch InjectionNext

Start the app before using MCP tools:

open /Applications/InjectionNext.app

# Build command example
cd App
xcodebuild -project InjectionNext.xcodeproj \
  -scheme InjectionNext \
  -configuration Debug build \
  CODE_SIGN_IDENTITY="-" \
  CODE_SIGNING_REQUIRED=NO \
  CODE_SIGNING_ALLOWED=NO

After a new dynamic library is loaded and functions are rebound, the UI will not automatically update. You must implement a mechanism to trigger a refresh. Depending on your framework, use one of the following patterns:

SwiftUI

Use the @ObserveInjection property wrapper (available in the HotSwiftUI and Inject packages) on an observed instance variable within your View struct. When an injection occurs, this variable changes, triggering a SwiftUI view update.

UIKit (UIViewController)

There are two primary ways to handle updates in legacy UIViewController subclasses:

1. The injected() method pattern: Implement an @objc func injected() method in your view controller. InjectionNext will perform a sweep of all known class instances; if an instance was part of the last injected library and possesses this method, InjectionNext will call it. You can use this method to call viewDidLoad() or a custom configureView() method.
2. The Hosting pattern: Use the Inject package to "host" the view controller, which automatically reinstantiates the view controller upon injection.

To enable code injection (updating function bodies without relaunching the app) in your Xcode project, follow these steps:

1. Install the App: Download a binary release, move InjectionNext.app to /Applications.
2. Launch Xcode via InjectionNext: Run InjectionNext.app and use the Launch Xcode menu item from the status bar to launch your Xcode instance.
3. Add Dependency: Add the InjectionNext repository as a Swift Package dependency to your project. This code is only included in DEBUG builds.
4. Configure Linker Flags: In your target's Build Settings, under Other Linker Flags, add the following (for the Debug configuration only):
   • -Xlinker
   • -interposable (Note: Add these on separate lines without double quotes).

Your changes will take effect when you save a source file for an app that has this package as a dependency and was launched via the InjectionNext app.

Other Linker Flags:
-Xlinker
-interposable