Agent Flow Claude Code mod: a live Claude Code subagent tree in a side pane

Agent Flow is a community mod by Charles Tao (Charlie0113-T). It shows what your subagents are doing while Claude delegates work. Type /flow and a pane opens beside the transcript with a live tree: the main loop at the root, and every subagent and in-process teammate nested under the agent that spawned it.

Each row is one agent. It shows a status glyph (● running, ✓ completed, ✗ failed, ◐ waiting for approval), the agent type, name and description, and the elapsed time. You also see what the agent is doing right now (a tool call and how long it has run, or a wait for your approval), its call count, and its tokens once it has finished. A [+] on a row expands its details: model, a prompt excerpt, recent tool calls and tokens. The header sums it up, for example Agent flow · 2 agents · 1 running · 0 waiting.

The tree flags what needs your attention. Agents waiting for approval are drawn magenta and bold. A tool call running longer than 30 seconds is marked slow, and a running agent with no event for two minutes is marked quiet. While the pane is closed and an agent is waiting, a status line under the prompt says 1 agent waiting for approval. Loops the engine never lists, such as a Workflow tool's agents or the engine's own forks, appear under a collapsed "unlisted loops" group, so they never vanish silently.

The install block above adds the author's marketplace and installs the plugin from it. Then type /flow and ask Claude to use the Agent tool.

The tree is built from engine events and corrected against $.agent.list() every two seconds while anything runs. Here is the spawn hook from hooks/register.ts. It lets the spawn happen first, then adds the node and may auto-open the pane:

on('agent.spawn', async ($, e, next) => {
  const result = await next(e)
  const engine = host

  if (engine === null) {
    return result
  }

  try {
    const now = await engine.now()

    apply(current =>
      Model.onSpawn(current, {
        agentId: result.agentId,
        parentAgentId: e.parentAgentId,
        subagentType: e.subagentType,
        description: e.description,
        // ...model, name, background, fork, prompt
      }, now),
    )
    await maybeAutoOpen(engine)
  } catch (error) {
    noteFailure('agent.spawn', error, await quietly(() => engine.now(), 0))
  }

  return result
})

tool.call marks the agent busy in a tool, then counts the call and its duration once next(e) returns. turn.complete records a subagent's end status, duration and tokens. The classic PermissionRequest and permission_prompt notification events mark an agent as waiting for approval. A reconcile timer and a one-second redraw timer run only while at least one agent is running, and state changes are batched into one redraw every 100 ms. /clear and /resume reset the tree. All the logic lives in small pure functions under hooks/model/, which the 68 unit tests cover.

There are no /config options. The thresholds are constants in hooks/limits/. They cover the auto-open widths (144 and 110 columns), the reconcile interval (2 s), the slow-tool limit (30 s), the quiet limit (2 min), the 200-node cap and the five rows shown inline. Change them in a local checkout and load it with --plugin-dir. When the pane sits inline above the prompt on a narrow terminal, it shows only the rows that need attention.

We read every file the plugin can execute before running it: hooks/register.ts and every module under hooks/. The plugin is purely an observer:

• It never runs commands and reads or writes no files, so there is no $.process or $.fs call. It makes no network requests and has no telemetry.
• It reads agent state from engine events and $.agent.list(). It keeps up to 120 characters of each spawn prompt in memory to show in the expanded details.
• The only thing it stores is one $.store key, agent-flow.open, which remembers whether you keep the pane open.
• Intercepts tool calls appears because it hooks tool.call, agent.spawn and the permission events. Each hook only records timing and status, then passes the event on unchanged. It never denies a spawn, a tool call or a permission. Its own errors are caught and noted in the pane's event line.
• Changes the UI covers the pane, the status line under the prompt and the /flow command.

The repository also has a scripts/smoke.sh for developers. It drives a real session with paid API calls, but it is not part of the installed plugin. To turn the mod off, run /plugin disable agent-flow.

The plugin loaded on Claude Code 2.1.291 on macOS. claude plugin validate passed without warnings, and claude plugin test ran 68 tests with 68 passing. Hooks modules load only where function hooks are enabled. If /flow does not behave as expected:

• "could not register /flow" in the plugin log means another /flow command is already listed; the mod then stands down.
• A pane above the prompt instead of beside it means the terminal is narrow. The pane shows only rows that need attention, with a hint to widen to 110 columns.
• No pane at all (claude -p, the VS Code extension): /flow prints the tree as text, and /flow text always does.
• An empty tree reads "no subagents yet; ask Claude to use the Agent tool".

To check that it works after installing, open the pane with /flow, then ask Claude to use the Agent tool to send one Explore subagent to list the files in src. The new node appears under main with its current tool and turns into a ✓ when it finishes.