Install and set up

Install the Mac app and the pointfix command, add an SDK to your app, set Pointfix up in your app’s repository, and start the bridge.

Requirements

Install

The Mac app

Download Pointfix.app from pointfix.dev/download and move it to your Applications folder. It is a signed app with the dashboard window and the Simulator panel. See The Mac app below.

The pointfix command

The command line and the bridge install with Homebrew, which also installs Node.js:

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 installed bridge includes the dashboard, the web reporter script it serves, and the Swift API reference.

The SDKs

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

pointfix start

The bridge prints its URL and project, and keeps running in that terminal; press Ctrl + C to stop it. Open the dashboard at http://127.0.0.1:4747, or run pointfix open from another terminal. 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. Start the bridge in your repository first.
2. Open Pointfix.app. It shows Connect to Pointfix with a port field (4747 by default). It connects automatically as soon as a bridge answers on that port, checking every 2 seconds, or press Connect.
3. Use Settings… (⌘ ,) to open Preferences. The toolbar has Simulator Panel, Settings and Disconnect.

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.