fixmyui

The FixMyUI agent runs on your staging server. It listens for PM feedback jobs from fixmyui.com, spawns Claude Code to apply the changes, and reports progress back in real time.

Prerequisites

• Node.js 18+
• Claude Code CLI installed and authenticated (claude --version)
• Git configured on the server
• A FixMyUI account with an installation created at fixmyui.com/fixmyui

Install

npm install -g fixmyui

Quick start

Run these commands in the root of your project on the staging server:

# 1. Interactive setup — creates .fixmyui.json
fixmyui init

# 2. Test the connection to FixMyUI SaaS + Reverb
fixmyui test

# 3. Start the agent daemon
fixmyui start

To keep it running permanently, use pm2:

npm install -g pm2
pm2 start fixmyui --name fixmyui -- start --config /path/to/.fixmyui.json
pm2 save
pm2 startup

The -- start passes the start subcommand to fixmyui (everything after -- goes to the script, not PM2). The --config flag tells the agent exactly where to find the config file, avoiding cwd-related issues.

Configuration

Local config (.fixmyui.json)

fixmyui init creates a .fixmyui.json file containing only identity & connection fields. You can also use environment variables (which take priority):

| .fixmyui.json key | Env var | Default | Description | |---|---|---|---| | apiUrl | FIXMYUI_API_URL | https://fixmyui.com | FixMyUI SaaS URL | | agentSecret | FIXMYUI_AGENT_SECRET | — | Secret from the dashboard (required) | | installationId | FIXMYUI_INSTALLATION_ID | — | Set automatically by fixmyui init | | repoPath | — | cwd | Absolute path to the git repository root | | reverbAppKey | FIXMYUI_REVERB_APP_KEY | — | Reverb key (set by fixmyui init) | | claudePermissionMode | FIXMYUI_CLAUDE_PERMISSION_MODE | acceptEdits | Headless: auto-approve file edits (see Security). For screenshots (URL in prompt), use auto or bypassPermissions so network/WebFetch can run without a TTY (see Troubleshooting). |

Dashboard config (synced from SaaS)

These settings are managed on the FixMyUI dashboard and synced automatically at agent startup, before each job, and in real-time via WebSocket when you save. They are not stored in .fixmyui.json. Env vars can still override them:

| Setting | Env var override | Description | |---|---|---| | Branch strategy | FIXMYUI_BRANCH_STRATEGY | new-branch, same-branch, or local-branch | | Branch name | FIXMYUI_BRANCH_NAME | Fixed branch name (when strategy = same-branch) | | Branch prefix | FIXMYUI_BRANCH_PREFIX | Prefix for new branches | | Auto-push | FIXMYUI_AUTO_PUSH | Push branch after commit | | Post-commands | — | Shell commands to run after Claude finishes | | Preview URL | FIXMYUI_PREVIEW_URL_TEMPLATE | e.g. https://staging.myapp.com?branch={branch} | | Prompt rules | — | Instructions prepended to every Claude prompt | | Stop behavior | — | Action on user "Stop": git_stash (default, reversible), git_restore (discards), or none |

Stop / cancel jobs

Users can hit Stop in the FixMyUI widget or the dashboard at any time during a running job. The SaaS broadcasts a job-cancel event on the agent's private channel; the agent then:

1. Sends SIGTERM to the running Claude process.
2. Runs the configured stop_behavior in the repo:
   • git_stash — git stash push -u -m "fixmyui-job-{id}" (reversible with git stash pop)
   • git_restore — git restore --staged . && git restore . (discards uncommitted changes)
   • none — nothing
3. Reports the job as cancelled (POST /api/fixmyui/agent/jobs/{id}/fail with cancelled: true).

The default is git_stash so no work is ever lost.

Global CLI option: --config <path> (or -c) — explicit path to .fixmyui.json, works with all commands. Useful when the config file is not in the current directory (PM2, cron, systemd, Docker).

fixmyui init writes repoPath as an absolute path so the agent works regardless of the working directory.

Commands

fixmyui init                    # Interactive setup wizard
fixmyui start                   # Start the agent daemon (blocks until Ctrl+C)
fixmyui test                    # Check config, connectivity, and Claude availability
fixmyui status                  # Show current config (masks the secret)
fixmyui start -c /path/to/.fixmyui.json   # Use a specific config file

How it works

fixmyui start
  └─ connects to Reverb WebSocket at fixmyui.com
  └─ subscribes to private-fixmyui.agent.{installationId}

PM sends message on staging site
  └─ SaaS broadcasts "new-job" event to agent

Agent receives job
  └─ git checkout -b fixmyui/{job_id}
  └─ spawns: claude -p "<task>" --output-format stream-json
  └─ streams progress → SaaS → PM widget (real time)
  └─ git add -A && git commit -m "fixmyui: <pm_message>"
  └─ git push origin fixmyui/{job_id}
  └─ reports complete with branch + preview URL

Security

• The agentSecret (fmui_sk_xxx) is stored only on your server. The SaaS stores only its sha256 hash.
• The WebSocket channel is private — authenticated per session with an HMAC signature.
• Add .fixmyui.json to your .gitignore (or use env vars) to avoid committing the secret.
• Claude permission mode: the agent runs with --permission-mode acceptEdits by default so Claude Code can write files without a human at the terminal. That does not always include network tools (e.g. WebFetch to load the PM’s screenshot URL). If Claude says it needs permission to download the image, switch to auto (auto-approves tools with safety checks) or bypassPermissions only on isolated build/staging machines. Use only on trusted hosts. For stricter control use default or plan (Claude may stall waiting for approval).

Troubleshooting

| Issue | Fix | |---|---| | claude: command not found | Install Claude Code and ensure it's in $PATH | | Unauthorized on connect | Check your agentSecret matches the one in the FixMyUI dashboard | | Jobs not received | Run fixmyui test to verify WebSocket connectivity | | Push fails | Ensure the server has push access to the repo (git push manually) | | "approve file edit permission" / edits not applied | Normal in default Claude mode without a TTY. The agent uses acceptEdits by default; set FIXMYUI_CLAUDE_PERMISSION_MODE=acceptEdits or add "claudePermissionMode": "acceptEdits" to .fixmyui.json | | Claude needs permission to download / fetch the screenshot (URL in prompt) | acceptEdits does not auto-approve all network tools. Set FIXMYUI_CLAUDE_PERMISSION_MODE=auto (recommended on staging) or bypassPermissions (sandbox/CI only). Or add Claude Code permissions in ~/.claude/settings.json or <repo>/.claude/settings.json to allow WebFetch for your R2/public domain (e.g. "WebFetch(pub-*.r2.dev:*)" or your CDN host). Restart the agent after changing env. | | Missing agentSecret with PM2 | PM2 may use a different working directory. Use --config: pm2 start fixmyui -- start --config /var/www/.fixmyui.json. Don't forget -- start (double dash) to pass args to fixmyui. |