Jumping between agents

With many agents running, you want to get to the one that needs you without hunting for it. flockr gives you three ways: the attention key, number keys, and notifications.

prefix+a: the next agent that needs you

prefix+a (focus_next_attention) focuses the next agent that is blocked or finished unseen, oldest alert first. Press it again to move on through the queue.

By default, landing on a done agent clears its done badge. To step through agents without clearing the ones you pass, set a delay:

[ui]
seen_delay_ms = 1500

Now a done agent clears only after its pane has been on screen for 1.5 seconds. prefix+u marks the focused pane's finished agent as done again, so it comes back into the queue. See Agent states.

Number keys

Agents and spaces are numbered in the sidebar.

These work without the prefix (except switch_tab). For spaces 10 and up, list more keys after 9:

[keys]
switch_workspace = "ctrl+alt+1..9,0,y,u,i,p"

If alt+1..9 does nothing

Terminals with tabs, such as Ghostty, GNOME Terminal, and Konsole, take alt+1..9 first. Unbind it in the terminal, or pick other keys in flockr:

[keys]
focus_agent = "ctrl+alt+1..9"

alt+... bindings can also depend on your terminal and tmux setup.

Other ways to move between agents

• previous_agent and next_agent focus the previous or next agent shown in the agents list. They have no default keys.
• In navigate mode (prefix+w), navigate_agent_up, navigate_agent_down, and navigate_focus_agent focus agents and stay in navigate mode. They are unset by default; for example navigate_agent_up = "k" or navigate_focus_agent = "1..9". If you give digits to agents, set navigate_switch_workspace = "shift+1..9" to keep spaces on other keys.
• Click an agent in the sidebar.
• From a script: flockr agent focus <name-or-pane-id>.

Notifications

flockr can tell you when an agent in the background finishes or gets blocked.

Pop-ups

ui.toast.delivery picks how pop-ups are delivered:

[ui.toast]
delivery = "flockr"
delay_seconds = 1

[ui.toast.flockr]
position = "bottom-right"

Press prefix+o (open_notification_target) to focus the agent from the notification on screen. On Linux, clicking a flockr system notification switches to the agent's pane, and on Hyprland it also brings the terminal window to the front.

Sounds

With ui.sound.enabled = true (the default), flockr plays a sound when agents change state in background spaces. You can use your own mp3 files:

[ui.sound]
enabled = true
path = "sounds/notification.mp3"   # all sounds
done_path = "sounds/done.mp3"      # finished only
request_path = "sounds/request.mp3" # needs attention only

Relative paths resolve from the config file's directory. [ui.sound.agents] turns sound on or off per agent; droid is muted by default.

On your phone

The flockr phone app can get push alerts when an agent is blocked or done. See Push alerts.

From scripts

Show your own notification through flockr:

flockr notification show "Build finished" --body "All tests passed" --sound done

--position takes top-left, top-right, bottom-left, or bottom-right. --sound takes none, done, or request.