CarterIDE guide: build, install and edit tweaks on your iPhone

CarterIDE is a code editor, terminal and build system that runs on your jailbroken iPhone. You can create a tweak, build it, install it and respring (restart the Home Screen) without a computer, and, if you want, ask an AI model to help edit your project.

Before you start

• Jailbreak: Dopamine (rootless) on iOS 15 or later. Creating, building, installing and respringing is tested end to end on iOS 17.1. On iOS 15 and 16 the app and Doctor work, but the build-and-install loop has had less testing.
• Build tools: CarterIDE builds with Theos. You don't need to install anything first: the app's Doctor screen checks each tool and installs what's missing.
• Coding Agent (optional): needs an API key for an OpenAI-compatible service, such as OpenAI, or Ollama or LM Studio on your own computer. The provider bills you separately. Everything else works without a key.
• Settings pane: Settings → CarterIDE needs PreferenceLoader, but all real options are inside the app.
• Price: $0.99 one-time, or included with Tweak Pass. See buying.html.

Note: The Coding Agent is a beta. It works best for small, specific changes, and its results depend heavily on the model you pick. Tweaks written in Swift are untested when built on the phone; use Objective-C or Logos (.x / .xm) for now.

Set it up

1. Add the CarterWare source and install CarterIDE (see install.html). Its icon appears on the Home Screen; no respring needed.
2. Open CarterIDE, read the three intro cards and tap Get started.
3. If Toolchain Doctor opens, tap Start carterd on the carterd helper row. This helper installs packages and resprings for you.
4. Tap Install missing (…) to install any red tools. If the Theos row is red, tap its Show Fix: the Terminal opens with the install command typed. Enter your sudo password, wait for it to finish, then tap Refresh.
5. When Required for Build shows 9/9 green, close Doctor.
6. On Add your API key, paste a key (see "Add an OpenAI API key"), or tap Use Offline Recipes instead or Skip for now.
7. Test it: in Files, tap Recipes, pick SpringBoard respring banner and tap Create. Then open Build and tap Build · Install · Respring.

You know it worked when the Home Screen restarts and, about three seconds later, an alert titled with your project name says "Tweak loaded on SpringBoard." Uninstall the test tweak in Sileo or Zebra under your project name.

Using the app

On iPhone there are five tabs: Code, Build, Files, Agent and Tools. The top bar has a searchable command list, a terminal button, a button that opens the Console, and a dot that's green when the install helper is online.

Code

Your open files as tabs, with syntax colors. Modified marks unsaved changes; tap Save to write them. The Deploy strip at the bottom expands to Build, Install, Respring, Logs and Build · Install · Respring.

Build

Build · Install · Respring runs all three steps and stops at the first failure, so a broken build is never installed. Build, Install and Respring run one step each. Cards below show the built package, error and warning counts, and any Pending diffs from the Agent.

Files

Workspaces lists your projects and Files the current project's files. + starts a new project. Folders you add to Documents/CarterIDE yourself, for example with git clone, appear under Other folders in Documents/CarterIDE.

Agent

The Coding Agent chat has three modes:

• Ask answers questions and never changes files.
• Edit (default) proposes changes as diffs. Nothing is written until you tap Accept.
• Agent edits files, runs commands and builds on its own, then lists every change so you can Keep or Revert it.

The red stop button cancels a run. In Agent mode, anything beyond read-only commands (like ls, grep, git status or a plain make) asks Run this command? with Run, Allow All This Run and Deny. The book icon opens Offline Recipes, which need no key.

Tools

• Doctor checks every tool needed to build and install. Red rows get Fix (apt), Show Fix or Start carterd.
• Source Control shows Git changes with Stage, Unstage, Commit and Initialize Repository.
• Inspect lists running Processes (tap Logs for a process's last two minutes of logs), installed Tweaks and Apps, and recent crash logs under Debug.
• Packaging edits your package's ID, name, version and dependencies; tap Save control.
• Search searches the whole project. Settings is covered under "Settings explained".

Console

Five tabs: Terminal, Problems (build errors; tap one to jump to it), Output (the live build log), Diffs and Logs (logs pulled after an install). On iPad, the app uses a sidebar and bottom panel instead of tabs.

Common tasks

Make a new tweak project

1. In Files, tap +.
2. Type a Project name, choose Theos Tweak (or SwiftUI App, Command Line or Web) and tap Create.
3. The project is saved in its own folder in Documents/CarterIDE, and its main file opens.
4. Before sharing it, open Tools → Packaging, change Package to your own ID (new projects start with a placeholder) and tap Save control.

Build, install and respring a tweak

1. Check that the dot in the top bar is green. If not, open Tools → Doctor and tap Start carterd.
2. Open Build and tap Build · Install · Respring.
3. If the build fails, it stops there and lists errors in Problems. Tap one to jump to it, or tap AI Fix for a proposed change.

Every built package is also copied to Documents/CarterIDE/build/, where Filza can find it.

Add an OpenAI API key

1. Open Tools → Settings → Coding Agent.
2. Keep Base URL as https://api.openai.com/v1, paste your key into API Key, and enter a Model your account can use (default gpt-4.1).
3. Tap Test API Key. "Key OK" means it works; otherwise the message says what's wrong.

Use a model running on your computer

1. Make the server accept network connections: start Ollama with OLLAMA_HOST=0.0.0.0, or turn on local network serving in LM Studio.
2. In Tools → Settings → Coding Agent, set Base URL to your computer's network address, port and /v1, for example http://192.168.1.20:11434/v1 for Ollama. Don't use 127.0.0.1 or localhost; on the phone those mean the phone.
3. Type anything into API Key (it can't be empty) and the model's exact name into Model.
4. Tap Test API Key. If it can't connect, check the port and that both devices share Wi-Fi.

Ask the Agent to change your tweak

1. Open the project, then the Agent tab, and choose Edit.
2. Ask for one small change, such as "Change the log message in Tweak.xm to say Hello."
3. Accept or Reject each diff, then build.

Each message starts a fresh run: the model doesn't see your earlier messages, only your new request and the project files it reads. Put everything it needs in one message.

Undo changes the Agent made

1. In Edit mode, tap Reject; nothing was written yet.
2. In Agent mode, tap Revert on each change in Review, or Revert all.
3. If you stopped an Agent-mode run part way, files it already wrote stay changed and aren't listed. CarterIDE saves a snapshot before each Agent-mode run, but this version has no button to restore it. Commit in Tools → Source Control before big requests so you can run git restore . in the terminal to go back.

Settings explained

The Settings → CarterIDE pane only links into the app; every option lives in CarterIDE under Tools → Settings.

In the app: Tools → Settings

Phone UI: Force phone UI (even on iPad); Show Doctor on launch when broken opens Doctor at launch if a build tool is missing; Auto-attach logs after install pulls your tweak's last two minutes of logs into Console → Logs after each install (it takes about ten seconds).

Coding Agent: Base URL, API Key and Model, plus Test API Key. Max agent steps (1–30, default 16) caps how many rounds one request can take. Default mode sets Ask, Edit or Agent. Stream agent tokens shows replies as they're written. Ask before Agent runs shell commands shows the Run / Deny card; turned off, Agent mode can run any command as the mobile user without asking.

Editor: Font size, Show hidden files, Auto-save before build (off means builds use what's saved on disk), Word wrap and Minimap.

IPA Install Backend: how app (.ipa) packages install; leave it on automatic. Default log process is whose logs are pulled when your project doesn't name one.

Helper (carterd): shows Online or Offline, with Recheck connection. The helper only answers the CarterIDE app itself.

Remote Build Targets: optionally add a Mac or Linux machine over SSH, used only when the phone's own tools are missing.

Export release bundle copies built packages to a dated folder in Documents/CarterIDE-Releases. Settings save when you tap Save Settings or close the screen.

Troubleshooting

"carterd offline" and Install or Respring won't run

Open Tools → Doctor, tap Start carterd, then Refresh. If it stays red, respring and try again, or reinstall CarterIDE, which sets the helper up fresh.

Doctor still shows Theos as missing

Let the install finish in the terminal without errors, then tap Refresh. If you installed Theos somewhere unusual, reinstall it using Show Theos install steps.

The build fails immediately

Make sure every row under Required for Build in Doctor is green, then read the first error in Console → Output.

A tweak I built sends the phone into Safe Mode

Your tweak is crashing the Home Screen. Exit Safe Mode, uninstall it, fix the code and rebuild. If it's in Swift, try Objective-C or Logos.

Test API Key fails

"Invalid API key" means the key is wrong or revoked. "Model not found" means your account can't use that Model. "Endpoint not found" usually means the Base URL should end in /v1.

"Model reply was not valid JSON" or "step limit reached"

The first means the model's answer couldn't be read; try a stronger model. The second means the request needed more rounds than Max agent steps; split the task or raise the limit.

Questions

Where is my API key stored?

In the iOS Keychain on your iPhone, marked for this device only, so it isn't copied to other devices. It survives relaunches and updates. On the rare setup without Keychain access, it's kept in CarterIDE's settings file, readable only by your user account. To delete it, clear API Key in Tools → Settings and tap Save Settings.

What does CarterIDE send to the AI provider?

Only what the Agent needs, only to the Base URL you entered, and only when you send a message or tap Test API Key. A request contains your message, the Agent's instructions (with your project's folder path and type), and what the Agent looked at during that run: file contents, file lists, search results, Git diffs, command output and build logs. Doctor's network check makes one request to OpenAI's address with no key or code.

Do I need an API key to use CarterIDE?

No. The editor, terminal, Doctor, building, installing, Git, Inspect and Offline Recipes all work without one. Only the Agent tab and AI Fix need a key.

Can the Coding Agent damage my phone?

It's kept to your project: it can't edit files outside the project folder, has no install or respring step of its own, and in Agent mode asks before running anything beyond read-only commands, unless you turn that off. Commands run as mobile, not root. Agent mode does write files directly, so commit before big requests.

Where are my projects stored?

In Documents/CarterIDE, one folder per project. Built packages are also copied to Documents/CarterIDE/build/.