Reference

Configuration

Pointfix has two layers of settings: pointfix.config.json, which you edit and can commit, and Preferences, which the dashboard saves in .pointfix/settings.json.

pointfix.config.json

pointfix init writes this file at your project root. A fuller example:

{
  "project": ".",
  "port": 4747,
  "defaultAgent": "claude",
  "autoDispatch": true,
  "allowedOrigins": ["http://localhost:5173"],
  "agentTimeoutMs": 1800000,
  "workflow": {
    "check": { "command": "npm", "args": ["test"] },
    "relaunch": { "command": "./scripts/run-debug-app.sh", "args": [] }
  },
  "custom": { "command": "your-agent", "args": ["--prompt", "{prompt}"] }
}

pointfix.config.json fields
Field	Type and default	Meaning
`project`	Path, default `"."`	The repository the agent works in. Relative paths are resolved from the config file’s folder. The folder must exist.
`port`	Integer 1024–65535, default `4747`	The bridge’s port. SDKs must use the same port.
`defaultAgent`	Agent ID, default `"codex"`	The initial agent. Choosing one in Preferences replaces it. IDs are listed in Agents.
`autoDispatch`	Boolean, default `true`	The initial Auto mode setting: run new reports immediately.
`allowedOrigins`	Array of origins, default `[]`	Exact `http` or `https` origins of dev servers that may use the web reporter, such as `"http://localhost:3000"`. No paths or trailing slashes.
`workflow.check`	`{ command, args }`, optional	Runs after the agent succeeds (status `checking`). If it fails, the report fails and relaunch is skipped.
`workflow.relaunch`	`{ command, args }`, optional	Replaces the built-in relaunch for every platform while Auto-relaunch is on (status `rebuilding`).
`custom`	`{ command, args }`, optional	The custom agent, with `{prompt}`, `{screenshot}` and `{model}` placeholders.
`useApiKeys`	Boolean, default `false`	Allow Claude Code and Codex to use API keys instead of requiring a subscription login. See Subscriptions and API keys.
`remote`	Boolean, default `false`	Let simulators and devices on other Macs send reports. See Remote access.
`agentTimeoutMs`	Positive integer, default `1800000` (30 minutes)	Time limit for each step: the agent, the check and each relaunch command.

Commands are an executable plus an array of string arguments. They run from project without a shell, so pipes, && and variables don’t work; put multi-command builds in an executable script in your repository. Use commands that exist in your repository; Pointfix assumes no build or test command.

The bridge reads the file when it starts. Restart it after editing. Invalid values stop it with a message naming the field.

How the file is found

POINTFIX_CONFIG, if set (relative to the current folder). The file must exist.
Otherwise pointfix.config.json in the project root: the nearest folder, from the current folder upward, that contains pointfix.config.json or .git. If there is neither, the nearest folder with Package.swift, settings.gradle(.kts) or package.json, else the current folder.
Without a file, the defaults above apply.

pointfix config prints the file it used and the resolved values.

Preferences (.pointfix/settings.json)

Preferences are edited in the dashboard (Preferences, or ⌘ , in the Mac app), and some in the Simulator panel. They are saved per project in .pointfix/settings.json and, once saved, take precedence over the matching config values. The Mac app and browser share them.

Preferences fields
Field	Preference	Default
`autoDispatch`	Auto mode	`autoDispatch` from the config, else on
`autoRelaunch`	Auto-relaunch	On, unless `"autoRelaunch": false` is set in `pointfix.config.json`
`autoCommit`	Auto-commit	Off
`leanAgent`	Lean runs (Claude Code)	On
`agent`	Agent	`defaultAgent`
`models`	Model, per agent	Empty (CLI default)
`ios.project`, `ios.scheme`	Relaunch targets: Xcode project or workspace (inside the project) and scheme	Empty
`android.dir`, `android.task`, `android.applicationId`	Relaunch targets: Gradle folder, install task, application ID	`""`, `":app:installDebug"`, `""`

The Appearance setting (System, Light, Dark) is stored in the browser, not in this file. If you edit settings.json by hand and it doesn’t validate, the bridge falls back to the defaults.

Environment variables

Environment variables
Variable	Effect
`POINTFIX_CONFIG`	Path to the configuration file to use.
`POINTFIX_PROJECT`	Overrides `project` (relative to the current folder).
`POINTFIX_PORT`	Overrides `port`. `pointfix start --port=` sets it for that run.
`POINTFIX_AXE`	Path to the optional AXe executable for iOS accessibility lookup. Without it, `axe` is looked up on `PATH`.

Remote access

To report from a simulator or Android device attached to another Mac, set "remote": true and restart the bridge. It then listens on all network interfaces instead of only 127.0.0.1, and pointfix start and the dashboard’s Connections → From another Mac list the URLs to use: this Mac’s .local name, then its IPv4 addresses.

// iOS, on the other Mac
ContentView().pointfixHost(url: URL(string: "http://studio.local:4747")!)

// Android, on the other Mac (prefer the IP address)
Pointfix.install(this, screen = "Home", url = "http://192.168.1.20:4747")

Other Macs can only send reports and follow their progress. The dashboard, Preferences, commits and reverts stay on this Mac, including the Commit fix and I’ll commit buttons in an app’s progress pill: review and commit on the bridge’s Mac.

No authentication

Anyone who can reach the port can send reports, and reports start agent runs when Auto mode is on. Turn remote access on only on networks you trust.

With remote access off, the bridge listens on 127.0.0.1 only, so other machines can’t reach it.