Using Flockdeck

Knowing who needs you

Running one agent is easy. Running six is not: they finish at different times and they block on permission prompts, and the one that is waiting is rarely the one you are looking at.

The dots

Every pane header carries a status dot.

Each state has its own shape as well as its colour, so you can tell them apart without seeing colour, except that waiting and blocked share the triangle. A blocked pane counts as waiting everywhere waiting agents are counted (below).

A pane whose turn is over but that has background work still running, a command or subagent it started, is still Idle and its header says how many are "in background". Its dot is the working dot all the same, and its tooltip says it is working in the background. Such an agent is counted as working everywhere working agents are counted (below), though its own status stays idle.

Hover the "in background" count to see what the work is, up to eight pieces: whether it is a shell command, a subagent, a monitor or something else, the description or command Claude Code gave for it, shortened, and how long ago Flockdeck first saw it. Text that looks like a secret (a token, a password given as a value) is hidden, with the same redaction the transcript recorder uses. A file path is shown as typed, though, even one to a secret file. The same text reaches the relay and phone views. A piece first seen only in the list Claude Code sends when a turn ends says "seen since", because it was already running by then. Where Claude Code gave nothing but an id, the list says "details unavailable (count only)" rather than guessing. Flockdeck keeps the list in memory only and never saves it.

While an agent is idle with background work counted, Flockdeck checks that work against the conversation Claude Code has stored for the pane: 45 seconds after it goes idle, then less often while nothing changes. The first check reads the last 8 MB of the conversation, and later checks read only what has been added since. A piece is dropped only on evidence of its end, written after Flockdeck first saw the piece and after the last sign it was running: Claude Code's notice that the task completed or was stopped, a subagent's hand-back, a successful stop of the task, a subagent's own transcript ending on its hand-back, or a monitor running past the timeout it was started with, when Claude Code stops it. An older end in the history is about an earlier task and is ignored. For a short while afterwards the tooltip lists what ended and what showed it, under "Lately ended".

A subagent whose transcript is still being written, or a command whose output file is still growing, counts as running. A piece with no sign of running for 30 minutes (no start, no end-of-turn list naming it, nothing being written) stays counted but is marked unverified, and the badge says so (◔ 1 in background, unverified). An idle agent whose background work is all unverified no longer counts as working, so its dot and its tab go back to idle. It still isn't treated as finished. There is no way to clear the count by hand.

While a tool is running the pane header names it, so Read, Bash or Edit tells you what the agent is doing, not only that it is busy.

Where else it shows

• The tab holding a waiting agent is marked ▲. A tab with an agent working, or idle between turns with background work still running (not counting work that is all unverified), has a pulsing filled dot instead; the ▲ takes its place when an agent there is waiting.
• The window title reports the count, ▲ 2 waiting while any agent is waiting, otherwise ● 3 working, so a waiting agent is visible in the taskbar with the window behind something else.
• The top bar counts the agents waiting and working across every open project, the same counts the window title draws from; an idle agent whose background work is still running counts as working, here and in the window title and the tab icon. Click the count for the same list Ctrl+Shift+A opens.
• The rail down the left of the window has a tile for each open project, and the tile says what that project's agents are doing, most urgent first: an amber badge where an agent is waiting on you, a pulsing cyan one where agents are working (one with background work still running counts) and none is waiting, and nothing where every pane is idle, exited, failed or not yet heard from, or there are no panes. So one that starts waiting in a project you are not looking at is seen from the one you are. Widen the rail and the count is written beside the name: ▲ 2 for two waiting, ● 3 for three working. The tile's tooltip and screen-reader name say it in words. A window reached through the relay shows the same.
• A desktop notification is raised when an agent blocks while the window is not in front, unless Desktop notifications is off in Settings › General. It is not raised when you are already looking at the window: the tab marker is enough, and a toast would be noise.
• Claude Code's own idle nudge (sent about a minute after a pane has simply gone quiet, waiting for a new prompt) never raises any of the above, for any pane: it says nothing more than that the pane is still there. A permission prompt or a real question always still reaches you, including for a helper another agent started for itself (see Agents and models).
• Ctrl+Shift+A lists every pane in every open project with its status, and jumps to any of them.
• Close finished panes clears out every agent pane that has gone idle and every pane that has exited cleanly, in every open project, in one go, like closing finished browser tabs. It asks nothing first, on purpose: a pane still waiting on you or still working is never touched, an idle shell is left alone, and one whose process failed (it never started, exited with an error, or was killed) is left alone too, since a failure is worth a look before it disappears. A pane locked with the padlock icon in its header, shut once locked, or Lock pane in the command palette is left open too, with a count of how many were skipped; a locked pane cannot be closed any other way either until you unlock it, though it can still be restarted. An idle agent that still has background work going (a command it started with run_in_background, or a background subagent) is not finished either, since closing it would kill that work. Its header says ◔ 1 in background while it has any, and so does its row in Ctrl+Shift+A. Flockdeck learns the work has ended when Claude Code tells the agent so, says at the end of a turn what is still running, or has recorded the end in the stored conversation (see above). Work that is counted but unverified still keeps the pane open. A Claude Code too old to say either keeps it counted until the agent stops it, the conversation is cleared, or the pane is closed by hand (or with flockdeck close -force).
• A background subagent calling tools after its agent's turn has ended leaves the pane idle, with that count and the working dot, rather than flickering between states for each call. A question or permission prompt it puts to you still turns it amber.

Where it comes from

For an agent that can report its own lifecycle, this is not screen scraping. Claude Code is launched with a generated --settings file registering its lifecycle hooks (UserPromptSubmit, PreToolUse, Notification, Stop and the rest), and an API agent, which is Flockdeck's own chat client, reports the same events itself. For Claude Code each event re-invokes this same binary in a hidden mode; the chat client sends its own. Either way the report reaches the application over the loopback interface.

Status therefore reflects what the agent is doing, not what its output happens to look like. Those settings are additive: your own settings, hooks and permissions still apply.

Auto-approve read-only

A pane can pass a plain read-only command (git status, cat, grep) without stopping at Claude Code's permission prompt. It is off unless you turn it on, with the ✓ in the pane's header or in Settings. Anything that changes a file, or that it is not sure of, still asks. Auto-approve read-only has the policy and the settings.

One answer is not reported by any event: a permission prompt answered from the keyboard. Enter turns the pane cyan, since allowing the tool starts it running. Refusing it puts Claude Code back at its prompt without a word, so a pane that is then heard from by nothing, neither an event nor anything it draws, for ten seconds goes back to grey.

An agent that cannot report

Not every coding agent has a lifecycle to report, and Flockdeck runs those too. For their panes the status is read from the terminal instead: the bell an agent rings when it wants you, a quiet timer for when it has stopped producing output, and, where its entry in agents.json gives it patterns, the lines it prints: the shape of a permission question, the shape of a prompt waiting to be typed at. Only the last few hundred bytes are looked at, with the escape sequences stripped, so a question two screens back does not keep a finished pane amber.

That is a guess where the other is a fact, and it is worth knowing which you are looking at: Agents and models says which agents report and which are read. Where both exist, a reported event always wins.

Letting Jev break the tie

The one thing the terminal cannot tell is a pane that has gone quiet: finished, or stopped on a question. Flockdeck can ask TypeSafe's Jev model, a small model that answers a fixed multiple-choice question rather than writing anything. This sends terminal output to a third party, TypeSafe, which nothing else in Flockdeck does with what your panes print, so it is off by default and needs both of these:

1. Settings › Status detection › Let TypeSafe's Jev help read pane status turned on. It can only be turned on from the machine itself, not from a window reached through the relay; turning it off works from a window reached through the relay too.
2. A TypeSafe API key: either the one you paste into Settings › API keys › TypeSafe API key (kept on this machine with your other keys, never shown back, only ever sent to api.typesafe.ai, and only set from the machine itself), or TYPESAFE_API_KEY in the environment Flockdeck starts in. The one in Settings is used first. Saving a key does not turn anything on.

With either missing, nothing is ever sent, and no error is shown.

What is sent, when a pane of an agent that reports nothing has been quiet for a few seconds and its status is still a guess: the last 30 lines of its output, at most 2,000 bytes, with the escape sequences taken out and secrets redacted. It goes in one request holding that text and the two questions asked of it. The scrollback and the pane's name and folder are not sent.

Before it is sent, the text goes through the redaction the transcript recorder uses, with additions for a terminal. The redaction takes out API keys of the common providers (Anthropic, OpenAI-style, GitHub, GitLab, AWS, Google, Slack, Stripe, Hugging Face, DigitalOcean, Twilio, npm), JWTs, bearer and basic credentials, passwords in URLs, private key blocks, and values assigned to a name such as TOKEN, SECRET or PASSWORD. The additions are these: any word that is a path to a secret file (.env, id_rsa, ~/.aws/credentials) is replaced, and so are three or more lines in a row of base64 (the body of a key whose first line has scrolled away). A key that the terminal wrapped onto the next line is joined first when the line before it is a full-width line, so it is caught in the common case. If nothing is left but redacted text, nothing is sent.

Redaction works by pattern and does not catch every secret: a password or key with no recognisable shape, on a line that does not name it as one, is sent as it is on screen, and so is everything else in those lines (code, file names, prose). If a pane may show something you cannot send to a third party, leave this off. Shell panes, and agents that report their own status, are never sent.

What it can change: a quiet pane called idle becomes waiting, or blocked, only when Jev answers with high confidence. It never turns waiting or blocked into anything else, and if it errors, is slow, is rate limited, or is unsure, the pane shows what it would have shown without it. Asks are limited to one per pane every 15 seconds, twelve per pane an hour and ten a minute in all, and the same output is not asked about twice in a row. After an error or a rate limit nothing is asked for a minute, and after a refused key or request for 15 minutes.