claudeers.
// Claude Plugins

flow

Ambient terminal scenes that move with your coding agent's work, for Claude Code and pi

// Claude Plugins[ cli ][ api ][ desktop ][ mobile ][ claude ]#claude#claude-code#claude-plugin#developer-tools#pi-extension#plugins◷ MIT$open-sourceupdated about 1 month ago
Actively maintained
94/100
last commit about 1 month ago
last release none
releases 0
open issues 1
// star history

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up flow (claude-plugin project) into my current project.
Found on https://claudeers.com/flow
Repo: https://github.com/robdmac/flow
Homepage/docs: —
Detected install method: claude-plugin → /plugin install flow@robdmac/flow
Category: plugins. Platforms: cli, api, desktop, mobile.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
active; community-verified: false. Confirm the source before running anything.
// or install directly (claude-plugin)
/plugin marketplace add robdmac/flow
/plugin install flow@robdmac/flow
// or clone
git clone https://github.com/robdmac/flow

// compatibility

Platformscli, api, desktop, mobile
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageTypeScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

flow

Flow's fire above the prompt: pilot lights at idle, climbing with each of Claude's tool calls, an inferno with three subagents, then back down when Claude is done

Ambient scenes in your terminal that move with the work your coding agent is doing: a fire, fizzing bubbles, the surf, a ski run, two rockets, a hot-air balloon, a steam engine, a train through the countryside, and a colony ship behind its shield. They run above the prompt of Claude Code (in the terminal or the Claude desktop app) or pi, or in a tall pane beside Claude Code's transcript.

Each scene is drawn in 24-bit color from Unicode block, quadrant and braille characters, so several pixels share each terminal cell. In the Claude desktop app, which has no character grid to draw into, the same frames are drawn as images.

https://github.com/user-attachments/assets/66673edf-7a52-43c3-b52b-3a804068bc5e

Install

Claude Code, from inside a session:

/plugin marketplace add robdmac/flow
/plugin install flow-scenes@robdmac
/reload-plugins

Installed it before as flow@robdmac? The plugin is now flow-scenes (another plugin had the name flow). Run /plugin uninstall flow@robdmac, then install as above. The command is still /flow. Settings you'd saved in /config don't carry over: set them again, or set them with /flow and /flow save.

Claude desktop, in the Code tab: click + next to the prompt box, then Plugins → Add plugin, add the marketplace robdmac/flow and install Flow (flow-scenes). Manage it later from + → Plugins → Manage plugins. The desktop app and Claude Code share their plugins, so if you've installed Flow in the terminal it's already there. It runs in local sessions, not cloud ones.

pi, from your shell:

pi install git:github.com/robdmac/flow

Mods are an early-access Claude Code feature, and their API may change between releases (see Compatibility below).

Not loading?

If /flow doesn't exist after installing, run claude --debug and look for a line about hooks modules:

  • "the rollout flag (tengu_plugin_hooks_modules) is off": mods from installed plugins are still being rolled out account by account, and yours doesn't have them yet. Update Claude Code (claude update), then turn them on yourself for one launch:

    CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude
    

    (claude -r instead of claude resumes your last session.) To keep it on, add it to ~/.claude/settings.json:

    "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" }
    

    or export it in your shell profile.

  • "saved off by an earlier session": the flag was cached as off and hasn't refreshed yet. Start a new session, or use the setting above.

  • "not available on Bedrock/Vertex/third-party providers" or "with a custom ANTHROPIC_BASE_URL": mods only run against the Anthropic API, so Flow can't load there.

  • "until workspace trust is accepted": accept the trust prompt for the folder you started Claude in.

The scenes

Every scene has a level from 0 (off) to 10 (as busy as it gets).

SceneAt 1At 10
firea low glow of embersa roaring fire throwing sparks
warpstars drifting pasthyperspace streaks
avalona colony ship among still stars, its habitat turning, now and then a rock burning up on its shield; every few minutes it passes a sun or flies through a nebulastars streaking past, a rock flaring on the shield every few seconds
balloona hot-air balloon on the grassup through the clouds to the edge of space
enginea steampunk engine standing stillcogs, belts and pistons at full speed
falcon, starshipthe rocket on its padclimbing through the sky (2–7), separating at about 7, the upper stage in orbit (8–10); as it stages the screen splits, one side following the booster back down (falcon's lands on its legs, starship's is caught by the tower's arms), the other staying with the upper stage; brought home, falcon's Dragon capsule comes down under parachutes to a splashdown and the view slides back to the pad, and starship's Ship splashes down at sea and is carried back for the arms to lift on
surfa glassy sea at dawnbig barrelling waves
skian easy runa steep mogul run at speed
bubblesa couple of lazy strings of bubblesa rolling, fizzing boil
trainwaiting at a red signal or a platform, its diesel idling (when the work starts the signal clears, the horn sounds and it pulls away; when it winds down the train pulls up again)flat out past fields, villages, woods, rivers and stations, the poles and the line beside it a blur

/flow pick shows them all at once, each one live, to choose from with the arrow keys and Enter (in pi, a list).

Some scenes also answer to other names: inferno and flame (fire), stars (warp), colony and interstellar (avalon), mechanism (engine), rocket (falcon), spaceship (starship), ocean and sea (surf), snow (ski), rail and railway (train).

Balloon, falcon, starship, surf, ski and train also have a night version: stars, a moon, moonlit snow or water, and the train's windows lit up. By night, bubbles turns into a stout: pale tan bubbles rising through black. By default day and night follow your local clock (night is 19:00 to 7:00). /flow day or /flow night pins one.

What moves it (auto mode)

Your agent is…The scene
idlea low glow (or nothing, if you choose)
in a turnrises to a level set by effort: low 2, default 3, high 4, xhigh 5, max 6
working a whileone level more for every 30 s the turn has run (not counting time it waits on you: a permission prompt, a question, a plan to approve)
streaming an answerkeeps going (limited per second, so plain chat sits mid-range)
editing filespushes higher, scaled by the lines written
running commandssparks; a slow command keeps it ticking over
reading or searching, or using any other tool (an MCP server's too)a small spark each
running subagentsbusier with each one (with diminishing returns), and each one gets a companion of its own (see below); the rest add company: more stars, more lit windows, more streams of bubbles, more lights on the launch tower
hitting a failed command, or compactingsmoke for a moment: smoky flame tips, sooty steam, a grey sky, a wipeout, a rocket's plume sputtering grey, black smoke pouring from the train's diesel
near a full context (≥85%)blue: a blue-white flame, a storm, dusk on the slopes, a blue gas flame, rain driving past the train
waiting on you: a permission to grant, its question, a plan to approvesettles to a calm 2 and holds, the whole scene turned a warm sepia that breathes slowly, about every 4 s: the fire banks to a bed of glowing coals, the stars stop, the colony ship comes to rest, the balloon hovers with its pilot light glowing, the engine runs down and lets off steam, a rocket holds its stage with amber lights up the tower, the surfer sits up waiting for a wave, the skier stops, the bubbles slow, the train draws up at a red signal or a platform, its headlight and the signal glowing with each breath. With sound on, a soft chime as the wait begins

A plain answer sits around 5, edit-and-test loops reach about 8, and 10 takes several subagents editing in parallel, or a long turn: it climbs a level every 30 s it keeps going.

Waiting on you shows only while a dialog is actually up for you: a permission ask that auto mode's classifier settles by itself, or that a hook answers, isn't one. It ends when you answer (once the call is over, or as soon as a long command shows it's running). Like the tints, it shows in auto mode only, and only in the session that waits.

Subagents, one by one

In fire, surf, ski, balloon, falcon, starship, engine, train and avalon, each running subagent has a companion of its own, in its own colors or its own place, so you can tell at a glance which are busy, which have gone quiet or are waiting on you, and when each finishes:

SceneArrivesWorkingQuiet (nothing for 20 s)Waiting on you (a permission dialog, its question)Done
firethe main fire narrows to make room and a small fire of its own kindles beside it, sparks catching (on alternate sides, a dark gap between each)burns bright and lively, taller the busier the scenedies down to low, glowing embersits embers pulse a bright glow, quicker than the waiting fire's breathburns out with a last puff of smoke and the gap closes, the main fire widening back (failed: snuffed out at once, in grey smoke)
surfpaddles in from the edgepaddles hard, or rides a following wave; on a big swell, rides the big wave with the surfersits up on its board, bobbingsits up waving an armpaddles off out of sight
skiskis in from behindcarves S-turns, throwing spraypulls over to the side, standing on its poleswaves a pole overheadtucks and skis off ahead (failed: drops back)
balloona small balloon in stripes of its own rises into view from belowflies high, bobbing on blasts of its burnerburner out, sinks lowits envelope blinksclimbs away off the top (failed: sinks away below)
falcon, starshipa mini rocket (the same rocket, smaller) on a little launch site of its own beside the big oneflies the mission with the big one, a beat behind: lifts off, stages (its booster coming home beside the big one's: falcon's on its legs, starship's into its own tower's arms), keeps formation into orbit and comes home with it (Dragon under its own chutes; the Ship belly-first, carried home and stacked)coasts, dropped back, a light blinking on its nose; on the ground it doesn't launchan amber beacon flashesfades as it pulls away ahead (failed: tumbles away in smoke)
engineits lamps on the bed plate warm upa light runs along its lampsits lamps glow lowits lamps flash togetherits lamps fade out (failed: fading red)
traina short train of its own draws up alongside from out of sightkeeps pace on the next track, gaining and losing a little, headlamp litdrops back a little, headlamp outits cab flashes amberfalls back out of sight
avalona probe launches from a bay on the ship's hull (the hatch glowing in its color) and flies up beside itholds station by the ship on its own flickering drivedrive off, falls back along the ship, a running light blinkingan amber beacon flashesturns about and burns away aft, off toward home (failed: drive dead, tumbles away dark)

A scene has room for a few (the fire 4 to 6 small fires across the band, 1 or 2 in the spine, surf 5, ski 4, balloon 4, the rockets 3 mini rockets (one of them behind the big launch site in the spine; 1 in a spine narrower than 19 columns), the engine 6 lamp groups, the train up to 4 trains, avalon 4 probes; fewer in the narrow spine or a narrow band: only as many as it shows whole); more wait for a place to come free. Warp and bubbles keep the plain company above: they're a stream of stars, a glass of anonymous bubbles, with nothing that stays put long enough to be someone. In the Claude desktop app, put the pointer over a companion to see its subagent's task, what it's doing and for how long.

The command

/flow changes things at once, in the session you run it in. Each session keeps its own scene and settings, so two sessions side by side can show different scenes, and resuming one (claude --resume, claude --continue, or opening it again in the Claude desktop app) brings its settings back. A /clear keeps the scene you had.

A new session starts on your defaults: the rows in /config (Scene mode, Scene, Scene while idle, Manual level, Scene layout, Day or night, Sound, Sound volume). /flow save makes the current session's settings your default, and /flow reset puts a session back on it. Changing a row in /config changes the default and the session you're in. A session already running keeps what it shows when the default changes elsewhere (another session's /flow save, say), and /flow on its own says when the session differs from your default, and how. /flow save saves exactly what the session shows.

CommandEffect
/flowshow the scene, mode, level and time of day
/flow <scene>pick a scene by name or alias (/flow surf, /flow sea)
/flow pickevery scene at once, live, side by side in a pane: the arrows (or Tab) move, Enter (or the scene's number) picks it for this session, as /flow <scene> does, Esc closes; on desktop, click one
/flow nextthe next scene
/flow day / nightpin the time of day
/flow clockday or night by your local clock (the default)
/flow <scene> nighta scene and a time of day at once
/flow automove with the agent's work (the default)
/flow 1–10 / offhold a fixed level, or switch it off
/flow idle glow / darkin auto mode while idle: a low glow (the default), or nothing (the band gives its rows back)
/flow soundtoggle a soundscape for the scene, swelling with the work (macOS; off by default); /flow sound on / off to set it
/flow sound 1–10the soundscape's volume, turning it on (7 is the default; each step below it 3 dB quieter); /flow sound 0 turns it off. /flow volume 1–10 does the same
/flow band / spinea 5-row band above the prompt (the default; also horizontal, bar or flat), or a tall pane docked beside the transcript (also portrait, vertical or side)
/flow savemake this session's settings your default, the one new sessions start with (it writes them to /config)
/flow resetput this session back on your default
/flow helplist all of this

Sound

/flow sound (or Sound in /config) turns on a soundscape for each scene, and turns it off again, each one tuned against real recordings so it sounds like the thing itself: a campfire's sparse, bright crackle over the soft lick of its flames (and a bonfire's roar at the top), a beach's wash and its waves breaking now and then on a calm day, often on a rough one, a steam engine's chuffs in time with its crank, water bubbling and boiling, wind gusting round a balloon and its burner roaring, skis carving through snow, a train's diesel idling at the signal, and the roar of its wheels and the wind rising as it runs (matched to recordings made in a carriage and beside the line), a rocket's roar and crackle matched to NASA's launch recordings. The colony ship and the warp drive are science fiction, so theirs are designed: the hull's hum, the shield fizzing, and a low, muffled boom through the hull as each rock blows up on it; the drive's hum climbing with speed.

The background is long takes that blend one into the next at random moments, so nothing comes round on a beat, and a fresh one crossfades in whenever the level or the scene changes (a rocket on the pad, climbing, in orbit, coming home). On top of it you hear what happens on screen, as it happens: bubbles bursting, rocks blowing up on the shield, sparks, a wave breaking, each ski turn, the hammer, the train's horn as it pulls away and before each level crossing, and the rockets' ignition, staging, the booster's sonic boom, the catch, parachutes and splashdown. Every scene follows the same loudness from level 1 (quiet) to 10.

/flow sound 1 to 10 turns it on at that volume in the session you run it in (Sound volume in /config is the volume new sessions start with, and /flow save makes this session's it). 7, the default, is the loudness the scenes were tuned to; each step below it is 3 dB quieter, so 1 is 18 dB down. Above 7 there's little room left: the loudest sounds already play near full scale, and any louder they'd distort. So 8, 9 and 10 lift the quieter sounds by up to 2, 4 and 6 dB, the louder ones by less and the loudest not at all, and a busier moment still sounds busier than a calm one. /flow sound 0 turns it off, and /flow sound turns it back on at the volume it had.

When Claude starts waiting on you (a permission, its question, a plan to approve), a soft chime: two struck tubes rising a fourth, about as loud as a scene at 6. Once a wait, and not for one right behind another (within 20 s): you're there already. It's part of the soundscape, so it follows the session's sound setting: /flow sound turns it on and off with the rest. For an alert without the ambience, there's Claude Code's own notification setting in /config.

It plays only while the scene is on screen, and stops with the session. Claude Code plays the clips with afplay, so it's macOS only; elsewhere the setting does nothing. It's set per session like everything else, so you can have it on in one session and not another, or quieter in one; several sessions with it on each play their own.

Turning it off

Run /flow off, or /flow idle dark to stay in auto mode but show nothing while idle. Either applies to the session you run it in; follow it with /flow save to make it the default for new sessions too. You can also disable the plugin. Flow draws in the terminal and in the Claude desktop app; not in VS Code or on mobile.

pi

The same scenes run as a pi extension (pi/index.ts): a widget above pi's editor, drawn as 24-bit ANSI lines. It shares the scenes, the activity model and the /flow command with the Claude Code version. pi has no side panes, so there is no spine there, and no built-in subagents (so no companions). pi's events drive it:

pi eventThe scene
agent_start / agent_enda turn lifts it (a level more for every 30 s it runs), then it settles to idle
turn_startrises to the floor for ctx.thinkingLevel (minimal/low 2 … max 6)
message_update deltasstreamed text and thinking keep it going
tool_callwrite/edit push it by lines written, bash sparks, reads and other tools flicker
tool_result with isErrora failed command shows as smoke
session_compactso does a compaction
ctx.getContextUsage()a nearly-full context shows as blue

pi tells an extension nothing of a wait on you, so there the scenes never show one. Nor has it a player, so the scenes are silent there: /flow sound says so.

As in Claude Code, each session keeps its own settings, kept in the session itself (an entry the model never sees), so resuming or forking it brings them back. ~/.pi/agent/flow.json holds the defaults new sessions start with; /flow save writes it. To try it without installing: pi --extension ./pi/index.ts.

What Flow does on your machine

Network: none. Flow sends nothing anywhere and contacts no hosts. Everything it draws and plays is computed locally from the plugin's own files.

Your settings: Flow writes its own /config rows (the flow-scenes plugin's options: scene, mode, sound and the rest) only:

  • when you run /flow save, which writes the settings your session shows as the defaults for new sessions;
  • at session start, to fix a row still holding a scene's old name (a renamed scene becomes its new name; a scene that's gone becomes the default).

It writes no other settings, no files and no environment variables. (CLAUDE_CODE_ENABLE_FUNCTION_HOOKS, under Not loading?, is a variable you set yourself, if you need it.)

What it keeps: in Claude Code's per-plugin store, each session's own /flow settings (the 100 most recently used sessions, none unused for 60 days) and which one-time tips you've seen. In the session's own plugin state, the balloon's altitude and whether someone has been at the session. In pi, a session's settings go in the session as an entry the model never sees, and /flow save writes ~/.pi/agent/flow.json.

Sound: off unless you turn it on. Claude Code plays the plugin's own clips (sounds/) through afplay, only after someone has typed or run a turn in the session.

What its hooks see, and what they decide: nothing. Every hook passes the event on unchanged (the one Flow answers is its own /flow command); Flow never blocks, allows, rewrites or answers a tool call, a permission, a prompt or a setting. It only watches, to set how busy the scene looks:

HookWhat Flow readsWhy
tool.callthe tool's name, the number of lines an edit or write adds (not their text), whether a Bash command failedhow busy the scene is; a failed command shows as smoke
classic.PermissionRequestthat a permission dialog is about to show (its tool's name, which subagent)the scene settles and breathes while Claude waits on you
turn.start, turn.complete, turn.stepwhen a turn or a subagent's run starts and ends; how much text is streamed (its length only)the level, and each subagent's companion
session.compact, session.measurethat a compaction happened; how full the context issmoke; blue when it's nearly full
config.seta change to one of Flow's own /config rowsapplies it to the session at once
prompt.editthat a key was pressed in the prompt (not what)someone is there, so sound may play
command.run/flow and its argumentsthe command
session.start, session.end, ui.*the session's id; the panes it drawsits settings; the band, the spine and /flow pick

It also lists the session's running subagents ($.agent.list(): their state, task and type) to give each one a companion and a hover card.

Cost

Flow repaints about 14 times a second while busy and 8 times when calm. It skips unchanged frames and doesn't repaint at all while off screen. In the desktop app it redraws at most 10 times a second. The heaviest scene takes under 2 ms per frame.

Compatibility

Built against Claude Code 2.1.289 and pi 1.0.0. Mods (function-hook plugins) are early access: the API may change between Claude Code releases, so a newer release can break flow until it's updated.

Development

claude --plugin-dir .   # load it, with hot reload (loading writes its types to .claude-plugin/types/)
claude plugin validate .
claude plugin test .
npm install && npm run typecheck

CI (ci.yml) runs these and npm run check on every pull request and push to main.

Add your own scene

npm install
npm run new-scene -- aurora --blurb "curtains of light that ripple faster with the work" --night
npm run preview -- aurora    # see it here at levels 1, 5 and 10, as a band and a spine, with each tint and waiting
claude --plugin-dir .        # then /flow aurora
npm run check                # colour pairs and timing, before you open a pull request

new-scene writes hooks/aurora.ts: a scene that already moves with the level, shows the tints, breathes while Claude waits on you and (with --night) has a night. Edit its paint(): it gets a grid of pixels (2 × 2 a terminal cell) and the dials (the level, eased; the frame count; night; the tint; how far into a wait on you; whether it's the tall spine). AGENTS.md has the rules a scene keeps to.

Every hook file carries a // REVISION: marker. On startup the mod writes the loaded revision, the local time and the UTC offset to the debug log (claude --debug).

License

MIT

// faq

What is flow?

Ambient terminal scenes that move with your coding agent's work, for Claude Code and pi. It is open-source on GitHub.

Is flow free to use?

flow is open-source under the MIT license, so it is free to use.

What category does flow belong to?

flow is listed under plugins in the Claudeers registry of Claude-compatible tools.

21 views
★ 14 stars
unclaimed
updated about 1 month ago

// embed badge

flow on Claudeers
[![Claudeers](https://claudeers.com/api/badge/flow.svg)](https://claudeers.com/flow)

// retro hit counter

flow hit counter
[![Hits](https://claudeers.com/api/counter/flow.svg)](https://claudeers.com/flow)

// reviews

// guestbook

0/500

// related in Claude Plugins

🔓

A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.

// pluginsmultica-ai/★ 230,631[ claude ]
🔓

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explainin…

// pluginsanthropics/⟨Python⟩★ 156,472[ claude ]
🔓

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

// pluginsHKUDS/⟨Python⟩★ 58,467◷ Apache-2.0[ claude ]
🔓

financial-services — a Claude ecosystem project on GitHub.

// pluginsanthropics/⟨Python⟩★ 41,409◷ Apache-2.0[ claude ]
→ see how flow connects across the ecosystem