Support

Getting help

Questions and bug reports go to GitHub issues. Include:

• your flockr version (flockr --version)
• your operating system and terminal
• the agent involved, if any (for example Claude Code or Codex)

flockr status --json and the relevant part of the log files help too. flockr --help prints where the logs are.

Installing and updating

flockr does not update itself. To update, rerun the install method you used the first time. See Install and Updating.

Common problems

An agent's status looks wrong

Ask flockr why it shows that state:

flockr agent explain <pane> --json

It shows the detected agent, the state, and the rule that matched. Check that the agent's integration is installed with flockr integration status. See Agent states.

A command fails after updating

The running server can be older than the new client. Run flockr status. If it says a restart is needed, run flockr server live-handoff. It switches the running server to the new binary and keeps every pane and agent running. Use flockr server stop only if the handoff fails, since it stops every running agent. See Troubleshooting.

A machine can't join the flock or shows disconnected 1.2.0

Run flockr flock status on both machines. The hub needs listen in its [flock] section set to an address the member can reach, such as a NetBird or WireGuard address. Changes to [flock] need a server restart. See Set up a flock.

The web app doesn't load 1.2.0

Both [web] and [mobile] must be enabled, and the listen address must be reachable from your browser. Every key in those sections needs a server restart. See Web app.

A config change doesn't apply

Reload with flockr server reload-config or prefix+shift+r. Keys in [mobile], [flock] (except approve_messages), and [web] need a server restart instead.

iPhone app 1.2.0

What you need

• A flockr server, version 1.2.0 or newer, running on your own computer.
• The [mobile] section enabled in ~/.config/flockr/config.toml. See Pair your phone.

Try it without a server

The app has a built-in demo. On the empty home screen, tap Try the demo, or in Settings use Add demo machines. It adds two made-up machines marked Demo, and nothing goes over the network. Remove them in Settings.

Pair your phone

1. On your computer, run flockr mobile pair.
2. In the app, scan the QR code it shows.

Answer from an alert 1.2.0

Long-press a blocked agent's alert to see Yes, Yes, don't ask again, No, and Open. The answer buttons need Face ID or your passcode. flockr opens, checks that the prompt hasn't changed, and answers. If anything changed, it opens the agent instead so you can answer in the terminal.

The app can't connect

Your phone must be able to reach the server's [mobile] listen address. Put both on the same Wi-Fi, or connect them through a VPN such as WireGuard or NetBird.

The pairing code expired

Run flockr mobile pair again and scan the new code.

No alerts arrive

Allow notifications for flockr in iOS Settings.

Report a bug

Open an issue at github.com/flockr-sh/flockr. Include your flockr version (flockr --version) and your iOS version.