Reference

Agents

Pointfix runs your agent’s command-line tool headless in the project folder. Choose the agent and model in Preferences; every report uses that agent, whichever app sent it.

Supported agents

Agents that aren’t on the bridge’s PATH are listed in Preferences but disabled. Every agent edits files directly and leaves committing to Pointfix. In the commands below, <prompt> is the generated prompt and […] parts are added only when they apply.

Agents and the commands Pointfix runs
Agent (ID)	Command	Sign in
Claude Code `claude`	`claude -p <prompt> --output-format stream-json --verbose --permission-mode acceptEdits [lean flags] [--model M]`	`claude auth login`, with a Claude subscription
Codex `codex`	`codex exec [-c forced_login_method="chatgpt"] [-m M] --sandbox workspace-write --json [--image <screenshot>] -- <prompt>`	`codex login`, with ChatGPT
Cursor Agent `cursor`	`cursor-agent -p --force --output-format stream-json [--model M] <prompt>`	`cursor-agent login`
Gemini CLI `gemini`	`gemini -p <prompt> --yolo [-m M]`	Run `gemini` and sign in with Google, or set `GEMINI_API_KEY`
GitHub Copilot CLI `copilot`	`copilot -p <prompt> --allow-all-tools [--model M]`	Run `copilot`, then `/login` once; needs a Copilot plan
OpenCode `opencode`	`opencode run [-m M] <prompt>`	`opencode auth login`
Factory Droid `droid`	`droid exec --auto medium [-m M] <prompt>`	Run `droid` and sign in
Qwen Code `qwen`	`qwen -p <prompt> --yolo [-m M]`	Run `qwen` and sign in, or use an API key
Amp `amp`	`amp -x <prompt> --dangerously-allow-all`	`amp login`
Goose `goose`	`goose run -t <prompt>`	`goose configure`
Aider `aider`	`aider --message <prompt> --yes-always --no-auto-commits --no-check-update [--model M]`	An API key in your environment or `.aider.conf.yml`
Custom `custom`	Your `custom.command` and `custom.args`; see Custom command	Up to your tool

The agent ID is what you use for defaultAgent and pointfix init --agent=.

How the screenshot reaches the agent

Codex receives the PNG with --image. Every other agent gets the screenshot’s file path in the prompt, with an instruction to read the image before changing layout.

What has been verified

Claude Code and Codex have been run end to end. Cursor Agent’s flags were checked against its installed CLI’s help. The other agents use each CLI’s documented headless mode and have not yet been tested with Pointfix. If one misbehaves, the Activity tab shows its output, and a custom command lets you adjust the flags.

Models

Set the model in Preferences. Empty uses the CLI’s default. Model names may contain letters, digits and . : - _ [ ], up to 80 characters.

Suggestions in Preferences: Claude Code sonnet, opus, haiku; Cursor Agent auto, sonnet-4, gpt-5; Gemini CLI gemini-2.5-pro, gemini-2.5-flash. Any name the CLI accepts works.
OpenCode models are written as provider/model.
Amp and Goose have no model setting; they use their own configuration.
The Activity tab records the model and token usage for Claude Code and Codex runs.

Subscriptions and API keys

By default, Claude Code and Codex run on your subscription, not per-token API billing:

Before each run, Pointfix runs claude auth status or codex login status. If the CLI isn’t signed in with a Claude subscription or with ChatGPT, the run fails before any model call, with the command to fix it. The check’s output is not logged.
Their environment has ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, OPENAI_API_KEY, CODEX_API_KEY and other CLAUDE_CODE_* variables removed (CLAUDE_CODE_OAUTH_TOKEN, a subscription token, is kept). This also keeps a nested claude from attaching to a Claude Code session that started the bridge.
Codex also gets -c forced_login_method="chatgpt".

Set "useApiKeys": true in pointfix.config.json to allow API billing: the check and the forced login are skipped and the environment is passed unchanged. Other agents always keep your full environment, since many of them authenticate with API keys.

Lean runs (Claude Code)

Lean runs is a Preferences switch shown for Claude Code, on by default. It adds:

--setting-sources project,local --strict-mcp-config --disable-slash-commands --tools Read,Edit,Write,Glob,Grep

Your personal Claude Code plugins, skills, hooks and MCP servers are skipped, which means far less context per turn and no hooks blocking edits. Repository settings and CLAUDE.md still apply, and subscription login is unaffected. Because only file tools are offered, Claude can’t run commands in a lean run; configure workflow.check if you want tests run after each fix, or turn Lean runs off.

Custom command

Run any CLI by adding custom to pointfix.config.json and choosing Custom in Preferences:

{ "custom": { "command": "your-agent", "args": ["--prompt", "{prompt}", "--image", "{screenshot}"] } }

Placeholders in custom.args
Placeholder	Replaced with
`{prompt}`	The full prompt.
`{screenshot}`	The screenshot’s absolute path, or an empty string when there is none.
`{model}`	The model setting. Preferences has no model field for Custom, so this is currently empty; put the model in `args` directly.

command is an executable and args an array of strings. Nothing goes through a shell. Choosing Custom without a custom entry is refused.

How runs execute

The agent runs in the project folder with the bridge’s PATH. Install and sign in to the agent in the same environment you start the bridge from.
Each run is a new process; nothing is injected into an existing chat window.
Each step is stopped after agentTimeoutMs (30 minutes by default). Stop run sends SIGTERM to the agent’s process group, then SIGKILL a second later.
The agents’ own permission settings still apply; for example, Codex expects a trusted repository and Claude Code’s project permissions can deny commands.