Install and set up
Install the Mac app, add an SDK to your app, and open your project. The Mac app runs the bridge itself. The pointfix command is only needed for the Homebrew route and for running the bridge in a terminal.
Requirements
| For | You need |
|---|---|
| The bridge | The Mac app includes Node.js and the bridge: nothing else to install. Homebrew route only: macOS and Homebrew, which installs Node.js for you. |
| Running fixes | A coding-agent CLI on your PATH, signed in. Claude Code and Codex are checked for a subscription login by default; see Agents. |
| Reviewing and committing | A Git repository. Without Git, reports still run, but Pointfix can’t list, diff, commit or revert the agent’s changes. |
| iOS | Xcode 27 or newer (Swift 6.4). The SDK targets iOS 26 and later and captures in the simulator only. The AXe simulator inspector is optional (see element context). |
| Android | JDK 17 or 21, Android SDK 35, apps targeting API 26 or later, and adb on your PATH. |
| Web | Any local development server. |
| Mac app | macOS 15 or newer on a Mac with Apple silicon. |
Install
The Mac app (recommended)
Download Pointfix.dmg, open it, and drag Pointfix into Applications. Open the app and choose your project folder. No Homebrew and no Terminal are needed: the app includes Node.js and the bridge, and it starts the bridge for the project you open.
The app updates itself. Choose Pointfix → Check for Updates… to check now.
Homebrew (existing installs)
If you already installed Pointfix with Homebrew, it keeps working. The Homebrew route is the 0.2.x line: the pointfix command and the Mac app from the Homebrew tap. Homebrew installs Node.js for you.
brew install pointfix-dev/tap/pointfix
The Mac app is also available through Homebrew:
brew install --cask pointfix-dev/tap/pointfix
- Update:
brew upgrade pointfix - Remove:
brew uninstall pointfix
The Homebrew install includes the dashboard, the web reporter script it serves, and the Swift API reference. The Homebrew cask and the standalone download both install Pointfix.app in Applications, so keep only one of them installed.
The SDKs
| Platform | Package |
|---|---|
| iOS | Swift package https://github.com/pointfix-dev/pointfix-ios, product PointfixKit. See iOS simulator. |
| Android | Maven Central: dev.pointfix:pointfix-android for Debug and dev.pointfix:pointfix-android-noop for Release. See Android. |
| Web | npm: @pointfix/web, or a script tag served by the bridge. See Web. |
Set up a repository: pointfix init
Run init inside your app’s repository:
pointfix init
- Finds the project root: the nearest folder upward that has
pointfix.config.jsonor.git. - Detects platforms up to three folders deep: iOS (
.xcodeproj,.xcworkspaceorPackage.swift), Android (gradleworsettings.gradle(.kts)) and web (package.jsonat the root). - Lists the supported agents on your
PATH, then asks for the agent and port in an interactive terminal.--yesskips the questions. - Writes
pointfix.config.jsonwithproject,port,defaultAgent,autoDispatchandallowedOrigins. Existing settings are kept. For web projects it addshttp://localhost:5173when your scripts use Vite, orhttp://localhost:3000for Next.js, Create React App, Remix or Nuxt. - Adds
.pointfix/to.gitignore. - Prints the SDK snippet for each platform it found.
Flags are listed in Command line.
Check your setup: pointfix doctor
doctor checks Node, the configuration, Git, the port, the selected agent, Claude Code and Codex subscription sign-in, and xcodebuild or adb for the platforms it detects. It exits with status 1 when it finds a problem, and prints the command to fix sign-in (claude auth login or codex login).
Start the bridge: pointfix start
With the Mac app, you don’t need this step: the app starts the bridge for the project you open. Use pointfix start to run the bridge in a terminal instead.
pointfix start
The bridge prints its URL and project, and keeps running in that terminal; press Ctrl + C to stop it. Run pointfix open to open the Pointfix Mac app, or open the dashboard at http://127.0.0.1:4747. Use http://127.0.0.1 rather than http://localhost: only the 127.0.0.1 origin is allowed to change settings and act on reports.
Then choose the agent, model, Auto mode, Auto-relaunch and Auto-commit in Preferences. They are saved per project in .pointfix/settings.json.
One bridge runs per project. It keeps a lock file in the project’s .pointfix folder while it runs. See Troubleshooting if a lock is left behind.
The .pointfix folder
The bridge keeps its data in .pointfix/ in your project: reports, screenshots, agent output, your Preferences (settings.json) and build output for iOS auto-relaunch. It is local runtime data. Keep it out of Git; init adds it to .gitignore.
The Mac app
Pointfix.app shows the dashboard in a native window and adds the Simulator panel.
- Open Pointfix, then choose Open Project… and select your app’s repository. The first time, Pointfix sets it up (the same steps as
pointfix init). Recent projects are listed under Recent. - The app starts the bridge for that project and shows the dashboard. Quitting the app stops the bridge.
- Use Settings… (⌘ ,) to open Preferences. The toolbar has Simulator Panel, Settings and Disconnect.
If a bridge is already running for that project, for example one started with pointfix start, the app connects to it instead of starting a second one. The app updates itself with Sparkle; Check for Updates… is in the Pointfix menu.
The app only loads pages from 127.0.0.1 and localhost; HTTPS links open in your default browser. If another service answers on the port, it says so and asks you to check the port in pointfix.config.json.
Pointfix