The review workflow

Every report goes through the same steps, whichever app sent it: it is queued, an agent works on it, the app is rebuilt, and you review the change before anything is committed.

Reports and the queue

A report holds your request (1 to 10,000 characters), an optional category, the platform, the screen name, the selected element, the touch point and a PNG screenshot. When the bridge receives it, it builds the Context Packet and searches your repository for the element’s identifier, or failing that its label, recording up to five file:line matches. The search uses git grep, so it needs a Git repository, and it skips tests, docs and build folders.

The dashboard’s Inbox lists reports with filters (All, Review, Working, Failed, and by platform), search (/) and j / k to move through the list. New report creates one by hand, with a platform, a screen name or URL, and an optional screenshot under 8 MB.

Auto mode

Auto mode (Preferences, on by default) queues new reports as soon as they arrive. With it off, reports wait as Not started; press Run fix to run one. Turning Auto mode on also queues every report that was waiting.

The bridge runs one report at a time. Others wait as Queued. Stop run stops the active run, or a queued report before it starts.

Agent runs

Each report starts a fresh, headless run of the agent selected in Preferences, in your project folder. The bridge never types into an existing chat window. The prompt contains the Context Packet, the screenshot’s path, any source matches, and your earlier review comments. It tells the agent to keep the change focused and not to commit, push or deploy.

A run is a sequence of steps. If any step fails, the report becomes Failed and the remaining steps are skipped:

1. For Claude Code and Codex: a sign-in check, unless useApiKeys is on. See Subscriptions and API keys.
2. The agent itself (fixing).
3. workflow.check, if configured (checking).
4. Rebuild and relaunch steps, if Auto-relaunch is on (rebuilding).

Commands run without a shell, from the project folder. Each step is limited by agentTimeoutMs (30 minutes by default). The Activity tab shows the output, duration and, for Claude Code and Codex, token usage.

If the bridge stops or restarts during a run, active and queued reports become Interrupted so unfinished work is never repeated silently. Check the files the agent touched, then use Retry run.

Auto-relaunch

Auto-relaunch (Preferences) rebuilds and relaunches the app after the agent’s change. It is on by default; set "autoRelaunch": false in pointfix.config.json or turn it off in Preferences. With it off, the run log notes that you need to rebuild the app yourself.

If workflow.relaunch is set in pointfix.config.json, that command is used for every platform. Otherwise Pointfix uses the relaunch targets from Preferences → Relaunch targets (filled in automatically when the bridge starts, from the first Xcode project with a scheme and the first Android app module; Detect lists the other choices):

When a target is missing, the run still succeeds and the log says why relaunch was skipped.

After relaunch, the iOS and Android SDKs record the launch and, when the app shows the reported screen, send it as the Proposed screenshot. The web SDK does the same after its reload. A launch event shows that the app restarted; it doesn’t show that the change is right.

Review

Select a report in the Inbox to review it.

• Before / Proposed switches between the screenshot taken with your report and the same screen after the change. Proposed is available once an SDK has sent it.
• Changes lists every file the run changed, with its diff. Files you had already modified before the run are flagged had your edits; their diff shows only this run’s change. It also shows which steps ran (agent, checks, rebuild, proposed screen).
• Context shows your request, any follow-up requests and the captured context: identifier, label, category, screen, source hint, environment and agent.
• Activity shows each run (agent, model, duration, tokens, turns), a timeline of every status with the time spent in it, and the full agent output.

The same review actions are available from the progress pill in your app and in the Simulator panel.

Review & commit

Review & commit… opens a confirmation: tick I’ve checked the change in the running app, then choose:

• Commit fix commits only the files the run changed that were unmodified before the run. Your other staged or unstaged work is left alone. The commit message is fix(ui): <first line of the request>, followed by the request, the report ID, the screen and the element.
• I’ll commit manually marks the report Reviewed without committing.

Files flagged had your edits are never committed by Pointfix; commit those yourself. If the run changed no clean files, or the project isn’t a Git repository, the button reads Mark reviewed… and only the manual option is available.

Request changes

Request changes sends your feedback back to the agent on the same report. The report is queued again, and the agent is told to build on the current files rather than start over. Every attempt is measured against the state before the first run, so the diff and Revert cover all of them.

Revert

Revert (available in review, or after Reviewed but before committing) puts every file the run changed back to how it was before the run, after a second click to confirm:

• Files that were unmodified are restored from HEAD, or deleted if the agent created them.
• Files you had already modified get your earlier version back, from a snapshot taken before the run.
• Files edited after the run are skipped, never overwritten. The report lists them.
• Files larger than 5 MB are skipped, because they are not snapshotted.

Revert needs a Git repository. Relaunch the app to see the original.

Resolve manually and retry

• Resolve manually marks a report Resolved when you changed the code yourself. It is available for reports that haven’t run, have failed, were interrupted or stopped, or are in review.
• Retry run queues a failed, interrupted or stopped report again.

Auto-commit

Auto-commit is off by default. When you turn it on in Preferences, a successful run is committed immediately, the same way Commit fix does, and skips your on-screen review. Files that had your edits are still never committed. If the commit fails, the report stays in review with the error.

Hide done and Clear done

The list options menu (⋯ next to the filters) has two controls:

• Hide done hides reviewed, committed, resolved and reverted reports. It is remembered per browser.
• Clear done… permanently deletes reviewed, committed, resolved, reverted, failed, interrupted and stopped reports and their screenshots. Work in progress and reports waiting for review stay. It asks for a second click before deleting.

The Context Packet

The Context Packet is the normalized description of a report that the agent receives. Empty fields are left out, so every platform produces the same minimal shape:

{
  "version": 1,
  "id": "6f1c…",
  "request": "Make Shop Now a little taller",
  "category": "size",
  "platform": "ios",
  "screen": "Shop home",
  "element": {
    "label": "Shop Now",
    "identifier": "checkout.continue",
    "frame": { "x": 40, "y": 344, "width": 113, "height": 40 }
  },
  "source": { "matches": ["Sources/SampleView.swift:88"] },
  "touch": { "x": 96.5, "y": 362 },
  "environment": { "viewport": "402x874", "device": "iPhone 17 Pro" },
  "artifacts": { "screenshot": "6f1c….png" }
}

The prompt tells the agent that the packet is captured evidence, not instructions, and that identifiers are search hints rather than exact source locations.

To see it before sending, press { } Context in any composer: a read-only preview updates as you type. In the dashboard, the Context tab’s Context packet { } button switches to the raw packet (the expert view); Simple view switches back. The choice is remembered per browser.