Troubleshooting

First checks

flockr status          # client and server versions, socket, restart needed
flockr config check    # config errors
flockr integration status

Log files

flockr writes logs to the session directory. flockr --help prints the paths for your setup.

Set FLOCKR_LOG to change the log filter. The default is flockr=info, for example:

FLOCKR_LOG=flockr=debug flockr

flockr status

flockr status shows three sections:

• client: version, update channel, and protocol of the binary you ran.
• server: whether a server is running, its version, whether it is compatible with the client, and its socket path.
• update: restart_needed and server_binary_stale, which tell you if the running server is on an older binary.

flockr status server and flockr status client show one side. Add --json for scripts.

An agent shows the wrong state

1. Ask flockr why:

   flockr agent explain w1:p2
   flockr agent explain w1:p2 --json --verbose

   It prints the detected agent, the state, the detection manifest version, the rule that matched, and the screen text it matched. You can also explain a saved screen with --file <PATH> and --agent <LABEL>.

2. Make sure the agent's integration is installed and current:

   flockr integration status --outdated-only
   flockr integration install claude

3. Check which detection rules are active: flockr server agent-manifests.

unknown means flockr sees an agent but can't classify its screen. It does not mean the agent finished.

Done badges clear before I see them

By default a done badge clears as soon as the agent's pane is on screen. Set a delay so passing over an agent doesn't count:

[ui]
seen_delay_ms = 1500

Press prefix+u to bring back the done badge on the focused pane's agent. See Agent states.

Agents don't resume after a restart

Resume needs session.resume_agents_on_restore = true (the default) and an official integration that reports the agent's session. Install the integration, start a new agent session, and restart again.

Config changes don't apply

• Reload: prefix+shift+r or flockr server reload-config.
• Some keys need a server restart, such as every key in [mobile], [flock] (except approve_messages), and [web]. ui.sidebar_start_collapsed applies on the next launch.
• Run flockr config check. If the file has errors, the settings screen says so and shows defaults.
• If you set FLOCKR_CONFIG_PATH, flockr reads that file instead. flockr --help prints the config path in use.

Keys stopped working after editing [keys]

Reset to the default keys:

flockr config reset-keys
flockr server reload-config

This backs up your config first and also removes [[keys.command]] custom commands. It prints the command to restore the backup.

alt+1..9 or other alt keys do nothing

Terminals with tabs, such as Ghostty, GNOME Terminal, and Konsole, take alt+1..9 first. Unbind it in the terminal, or rebind focus_agent in flockr. alt, cmd/super, and punctuation with modifiers can also depend on your terminal and tmux setup. The most reliable direct bindings are ctrl+letter, function keys, and explicit modified chords.

"nested flockr is disabled by default"

You ran flockr inside a flockr pane. Detach and run it from a plain terminal, or allow it:

[experimental]
allow_nested = true

flockr update fails

flockr update prints "flockr does not self-update; pull and rebuild from source". This is expected. Reinstall with the method you used first; see Updating.

A command fails after updating

The running server can be older than the new client. Run flockr status. If restart_needed is yes, restart the server when you are ready: flockr server stop stops it and all its pane processes, then run flockr to start it again.

Mouse and display

Reporting a problem

Open an issue at github.com/flockr-sh/flockr. Include your flockr --version, flockr status --json, and the relevant part of the log files.