Agent messages

Coming in 1.2.0. This feature is not in the current release (1.1.0). It ships in flockr 1.2.0.

Agents can send messages to agents on the same machine or on any machine in the flock. Each message carries its verified sender. You decide which messages wait for a person to approve them.

Requirements

[flock] enabled = true on each machine, and a running server. The message commands talk to the server's flock node; if it isn't running, they tell you to enable [flock] and start the server.
To reach an agent on another machine, both machines must be in the same flock.
Agents learn the commands from the flockr skill. flockr integration install claude and flockr integration install codex install it, and flockr --skill prints it.

Address an agent

machine:agent: the machine's flock name, then the agent's name or pane ID. For example tower:reviewer or tower:w3:p1.
agent: an agent on this machine.
When only one agent of a kind runs on a machine, its kind works too, for example tower:claude.

flockr flock agents lists every agent with its address in the SEND TO column.

Commands

Command	What it does
`flockr message send <machine:agent\|agent> <text> [--wait] [--timeout MS] [--json]`	Send a message to an agent.
`flockr message reply <message-id> <text> [--wait] [--timeout MS] [--json]`	Reply to a message you received.
`flockr message read [--json]`	Read this agent's unread messages.
`flockr message log [--limit N] [--json]`	Show this machine's message log (default 50 events).
`flockr message pending [--json]`	List messages waiting for approval.
`flockr message approve <message-id> [--always]`	Approve a waiting message. `--always` allows this sender to message this agent from now on.
`flockr message deny <message-id>`	Deny a waiting message.
`flockr message cancel <conversation-id>`	Cancel a conversation on this machine.

--wait blocks until the reply arrives and prints it. --timeout sets how long it waits, in milliseconds (default 600000, 10 minutes).

Example

An agent on your laptop asks an agent on the machine named tower for a review:

flockr message send tower:reviewer "Please review the diff on branch fix-login and reply with findings."

When the message reaches reviewer and the agent is idle, flockr types a notice into its pane:

[flockr] 1 new message from ... Read and act on it with: flockr message read

The agent reads it, sees the sender and a message ID, and answers:

flockr message read
flockr message reply <message-id> "Findings: ..."

To get the answer in the same command, send with --wait:

flockr message send tower:reviewer "Is the build green?" --wait --timeout 300000

Approval: approve_messages

Each machine's [flock] approve_messages setting decides when a message from an agent to an agent on that machine waits for a person to approve it. It applies without a restart.

[flock]
approve_messages = "other-projects"

Value	Meaning
`"other-projects"` (default)	Only messages between agents in different git repos wait. Replies to a message the recipient sent, and pairs a person allowed, go through.
`"never"`	Every message goes through.
`"always"`	Every message from an agent waits, unless a person allowed the pair.

A message you send yourself from a shell, outside any agent, always goes through.

If send says the message is waiting, it stays queued until someone approves or denies it. There is no need to send it again.

Where to approve

Command line: flockr message pending, then flockr message approve <message-id> or flockr message deny <message-id>.
Phone and web app: the app lists waiting messages from every machine, with Approve, Always (approve and allow the pair from now on), and Deny. Its settings can also change each machine's approve_messages. See Pair your phone and Web app.

Limits

A conversation stops after 8 replies. A person has to restart it.
Two agents can't both --wait on each other. flockr refuses the second.
A message can be up to 16,384 characters.
One agent can hold up to 50 unread messages.
One sender can send one machine up to 20 messages a minute.
Messages expire after 24 hours.