brainstorm

Local visual brainstorming companion: a tiny HTTP + WebSocket server that serves the newest .html file from a session content/ directory, wraps HTML fragments in a themed frame, and appends click events (elements with data-choice) to state/events.

Use it from any repo by passing --project-dir so screens persist under <project>/.superpowers/brainstorm/<session>/.

Install

From a clone:

cd /path/to/brainstorm
npm link   # optional: makes `brainstorm` available globally

From npm (after you publish):

npm install -g brainstorm

Start a session

brainstorm --project-dir /path/to/your/repo

Or:

bash /path/to/brainstorm/scripts/start-server.sh --project-dir /path/to/your/repo

The command prints one line of JSON, for example:

{"type":"server-started","port":52341,"host":"127.0.0.1","url_host":"localhost","url":"http://localhost:52341","screen_dir":".../content","state_dir":".../state"}

Open url in your browser. Write new .html files into screen_dir (never reuse filenames); the page auto-reloads when a new newest file appears.

Read state_dir/events for JSONL click lines (cleared when a new screen file is added).

state_dir/server-info contains the same startup JSON.

Stop

bash /path/to/brainstorm/scripts/stop-server.sh /path/to/session

session is the parent of content/ and state/ (the path printed as the parent of screen_dir in practice — e.g. .../brainstorm/12345-1706000000).

Options

Flag	Meaning
--project-dir <path>	Store under <path>/.superpowers/brainstorm/<id>/
--host <bind>	Default 127.0.0.1; use 0.0.0.0 only if you understand exposure
--url-host <host>	Hostname in printed URL (e.g. localhost)
--foreground	Run in foreground (needed in some CI / Windows Git Bash setups)

Remote MCP / Fly.io

This tool binds locally. It does not replace a public URL for browsers when your agent runs only on a remote server. Run brainstorm on the machine where you open the browser, or host screens behind HTTPS on your app.

Credits

Server, frame template, and client helper are derived from obra/superpowers (brainstorming visual companion), adapted into a standalone package.

License

MIT — see LICENSE.