Get started

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

Requirements
ForYou need
The bridgeThe 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 fixesA coding-agent CLI on your PATH, signed in. Claude Code and Codex are checked for a subscription login by default; see Agents.
Reviewing and committingA Git repository. Without Git, reports still run, but Pointfix can’t list, diff, commit or revert the agent’s changes.
iOSXcode 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).
AndroidJDK 17 or 21, Android SDK 35, apps targeting API 26 or later, and adb on your PATH.
WebAny local development server.
Mac appmacOS 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

SDK packages
PlatformPackage
iOSSwift package https://github.com/pointfix-dev/pointfix-ios, product PointfixKit. See iOS simulator.
AndroidMaven Central: dev.pointfix:pointfix-android for Debug and dev.pointfix:pointfix-android-noop for Release. See Android.
Webnpm: @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.json or .git.
  • Detects platforms up to three folders deep: iOS (.xcodeproj, .xcworkspace or Package.swift), Android (gradlew or settings.gradle(.kts)) and web (package.json at the root).
  • Lists the supported agents on your PATH, then asks for the agent and port in an interactive terminal. --yes skips the questions.
  • Writes pointfix.config.json with project, port, defaultAgent, autoDispatch and allowedOrigins. Existing settings are kept. For web projects it adds http://localhost:5173 when your scripts use Vite, or http://localhost:3000 for 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.

  1. 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.
  2. The app starts the bridge for that project and shows the dashboard. Quitting the app stops the bridge.
  3. 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.