Skip to content
Back to search

Flare

The graph based agentic IDE

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/algonorhythm--flare/badge.svg)](/listings/algonorhythm--flare)

HTML

<a href="/listings/algonorhythm--flare"><img src="/api/listings/algonorhythm--flare/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Built releases are on the [releases page](https://github.com/AlgoNoRhythm/Flare/releases):

| Platform | Download | Notes | | --- | --- | --- | | Windows | `Flare-<version>-Windows-x64.exe` | NSIS installer, per-user, choose your own directory. A `.zip` is there too if you would rather not install anything. | | macOS, Apple silicon | `Flare-<version>-macOS-arm64-beta.dmg` | **Beta** — see below. | | macOS, Intel | `Flare-<version>-macOS-x64-beta.dmg` | **Beta** — see below. | | Linux | `Flare-<version>-Linux-x86_64.AppImage` | `chmod +x` and run. A `.deb` and a `.tar.gz` are published too. |

The macOS packages still say **beta** in their filename, but for a narrower reason than they used to.

They have now run on a Mac. The full suite — 544 unit tests and 78 end-to-end tests, Electron and browser — passes on macOS 14, and the packaged `.app` is booted out of its own DMG and checked for a working terminal before a release goes out, the same bar Windows and Linux are held to. What is *not* covered is Apple silicon specifically: the hardware behind this project is Intel, so the `arm64` package is built and signed but has never been launched. That is what the beta label is now for.

They are also **ad-hoc signed and un-notarised**. Notarising needs a paid Apple Developer account, so Gatekeeper will still refuse the first launch — the signature is there to satisfy the loader, not Gatekeeper. Open it once with right-click → Open, or clear the quarantine flag:

xattr -dr com.apple.quarantine /Applications/Flare.app

To build one yourself:

npm run dist      # installer for the platform you are on, into release/
npm run dist:dir  # unpacked, for a quick look

Run it **on the platform you are building for**. Flare's terminal is a native module that ships as a prebuilt binary per platform and architecture, and npm installs only the one for the machine doing the installing — so a Linux package built on Windows contains the Windows binary and opens no terminal at all. That is what the release workflow's one-runner-per-platform matrix is for (`.github/workflows/release.yml`); tag a version and it builds all four:

npm version 0.2.0 && git push --follow-tags

It uploads to a **draft** release, so nothing is public until the artifacts are all there and someone has looked at them. The title bar is platform-aware: custom controls on Windows/Linux, native inset traffic lights on macOS.

Windows CI signing uses SignPath: manual dry runs use `test-signing`, while release builds require `release-signing`. The Foundation test setup and required GitHub secret are documented in [Windows signing](docs/windows-signing.md). Production signing remains pending SignPath's setup review and certificate issuance.

On Windows, WSL2 is enough to test the Linux build properly: WSLg supplies a display, so the desktop suite runs against real Electron and the AppImage actually boots. Work inside the WSL filesystem rather than `/mnt/c` — `npm ci` against the Windows tree from Linux replaces `node_modules` with Linux binaries and breaks the Windows checkout.

cp -r /mnt/c/path/to/Flare ~/flare && cd ~/flare && npm ci
npx playwright install chromium
npm test && npx playwright test            # 633 unit + 80 e2e, on Linux
npx electron-builder --linux --publish never

Development mode (hot reload for the renderer):

npm run dev

Flare opens to a start screen listing your recent projects — arrow keys and Enter, or `Ctrl+O` to pick a new folder. The last project you had open is the first row, so restoring it is one keystroke rather than an assumption. `FLARE_PROJECT=<path>` skips the start screen and opens that project directly.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 689 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <img src="build/icon.png" alt="" width="88" align="left" />
  2. # Flare
  3. **A graph-first IDE for agentic coding — desktop app, or served to a browser
  4. from the machine the agent runs on.**
  5. The main surface is a live graph of your codebase — every file is a node,
  6. imports are edges — with a full terminal underneath where you run `claude`,
  7. `codex` or `opencode`. As the agent edits files, the graph updates in real
  8. time; every change burst is snapshotted into a local shadow history you can
  9. diff against and revert to, per file or as a whole tree.
  10. <br clear="left" />
  11. ![Flare in a minute: opening a folder in the graph, the blast radius of a shared file, four lenses, a task drawn round two files with a box-select, an agent picking that task up over MCP and doing it while the map updates, and the alert Flare raises when it also rewrites a file the rest of the app imports](docs/flare-demo.gif)
  12. *You run the agent in Flare's terminal, and Flare watches: it maps the repo
  13. from the source, attributes every write to whoever made it, and pulls you in
  14. when something important changes. The agent takes work from the board and
  15. asks its questions there, so the two of you are looking at the same project
  16. rather than at a chat log.*
  17. ## What you get
  18. ![Flare open on its own source with the Activity lens on: shared/insights.ts is hovered and every file that imports it is lit as an amber ray, while the top bar counts the risky changes and the files waiting for review](docs/flare-graph.png)
  19. *Flare open on its own source — 99 nodes, 326 edges. The Activity lens shades
  20. each file by how recently it changed, and hovering `shared/graph.ts` lights
  21. every file that imports it in amber: the blast radius of one file, without
  22. reconstructing it from a grep. Bottom right, an alert Flare raised on its own
  23. about `src/App.tsx` — nothing covers it, and with two agents live it says
  24. `mixed` rather than guessing which of them wrote it.*
  25. ### Three views of the same graph
  26. Switchable from the toolbar or the command palette. Each honours the active
  27. lens, the selection, collapsed directories and the search filter.
  28. - **Canvas** (default) — dependency cards on a pannable board, ordered
  29. left-to-right by dependency depth (SCC-condensed, crossing-reduced, wrapped
  30. into bands so a long chain never becomes an unreadable strip): foundations
  31. left, entry points right. Cards carry the filename, a lens-coloured rail and
  32. badges (complexity, coverage %, untested, TODOs, cycles). Hovering traces
  33. imports in blue and importers in amber; shift+click traces the path between
  34. two files; cards can be dragged and their positions persist. Zooming out
  35. swaps the cards to a plate skin (semantic zoom) so the shape of the repo
  36. still reads.
  37. - **Wheel** — every node sits on one ring ordered by directory, dependencies
  38. cross the middle as bundled chords, and cluster bands are labelled around the
  39. outside. Drag to spin, alt+wheel to rotate, scroll to zoom, shift+drag to
  40. pan, ctrl+drag to box-select. Click a node to *pin* its dependency
  41. directions; hover a cluster band to isolate that directory; click a band to
  42. collapse or expand it.
  43. - **Districts** — a squarified treemap where area is lines of code and shade
  44. is the active lens. The fastest read on "how big is this repo and where
  45. does the mass sit"; selecting a file outlines everything it touches.
  46. ![The Wheel view: every file on one ring, dependencies crossing the middle as chords](docs/flare-wheel.png)
  47. *The Wheel answers the one question the canvas cannot: what talks to what
  48. across the whole repo at once. A file whose chords fan across the entire disc
  49. is load-bearing whether or not anyone documented it that way. Node dots take
  50. the active lens, cluster bands are coloured by directory.*
  51. ### Features
  52. - **Folders that open one level at a time** — a folder card holding more files
  53. than fits on a screen unfolds into its *sub-folders*, not into four hundred
  54. cards. A `src/` that is 90% of the repo therefore has a middle state: it opens
  55. into `src/app`, `src/features`, `src/libs`… with the dependencies between them
  56. drawn, and each of those opens again. Folding it back remembers how far you
  57. had drilled.
  58. - **Lenses** — recolour the same layout by Clusters, Activity, Hotspots
  59. (churn × complexity), Risk, Tests, Coverage, Instability, Reuse, Unread or
  60. Cycles. Whichever is active, a strip under the toolbar explains how to read
  61. the colours and shows the matching scale.
  62. - **Everything is discoverable** — a VS Code-style File / View / Graph / Go /
  63. Help menu bar, a `?` cheat sheet listing every click, drag and shortcut for
  64. the current view, and a tooltip on every control saying what it does rather
  65. than what it is called. What acts on the *view* — pointer mode bottom-left;
  66. centre, fit, zoom and the cheat sheet bottom-right — sits on the canvas
  67. corners rather than in a toolbar strip above it.
  68. - **Control panel** — the collaboration, in three sections. **Tasks** is a
  69. kanban of work written to be *handed to an agent*: a card's primary action is
  70. **Copy for agent**, which emits the brief plus the files it names plus what
  71. the graph knows about them ("29 files downstream, 0% covered, in an import
  72. cycle"), so the agent starts from the map instead of spending half its
  73. context rediscovering it. File a card straight from a graph selection with
  74. right-click → *New task with these files*. Lanes are yours — add, rename,
  75. reorder or remove them; removing one rehomes its tasks rather than dropping
  76. them.
  77. **Design decisions** is for the architectural calls an agent makes without
  78. being asked — a module boundary, a dependency taken on, a data shape that
  79. will spread, a refactor across several files. It records them with
  80. `decision_record` *before* the code that assumes them and they land as
  81. **proposed**, for you to agree or decline with a reason; an agent cannot
  82. agree with its own proposal. Whether it then keeps building on one or leaves
  83. the work that rests on it is your call, set in the routine.
  84. **Questions** is what it needs from you, parked rather than blocking. Each
  85. question names the tasks it holds up, so the rest of the board stays
  86. workable; the agent picks up something else and halts only when everything
  87. left is waiting on an answer. Answer it in the panel and the agent reads it
  88. back over MCP.
  89. All three are queryable over MCP, so an agent can run its own loop:
  90. `tasks_list` (optionally by lane) to pick up work, `task_get` for the exact
  91. brief a human would have pasted, `task_update` to log progress and move the
  92. card to review, `task_create` to file follow-up work it finds but shouldn't
  93. do now, `decision_record`, `question_ask`, and `working_agreement` when it is
  94. unsure whether to keep going. Everything shows up in the panel live.
  95. - **A routine, so it doesn't stop at the first question** — the ⚙︎ Routine
  96. wizard sets what the assistant does when it runs out of work: check the board
  97. again rather than stopping, record design decisions you have not agreed to —
  98. and either keep building on them or park the work that rests on them — and
  99. park questions instead of halting on them, plus any house rules you type. It
  100. renders the working agreement the agent actually reads — generated from the
  101. switches, so turning one off removes its rule, and **editable**, because the
  102. switches cover what every project wants and nothing of what yours wants said
  103. in its own words. It stores it with the project, where `working_agreement`
  104. returns it along with the state of the board: how many cards are waiting to
  105. be picked up, how many are already in progress, how many are blocked, what is
  106. waiting on you, and which card to take next.
  107. That last part is written for more than one agent at a time. A card is only
  108. offered if it is still sitting in the first lane — moving it to in-progress
  109. is how an agent claims it, and no agent is ever pointed at a card another one
  110. has started.
  111. The last switch is the one that doesn't depend on the agent remembering any
  112. of the others: **check the board when it tries to stop**. Flare answers your
  113. assistant's stop hook with the state of the board, so a session that tries to
  114. end while a card is still workable is handed that card instead, by name. It
  115. adds a `Stop` hook to `.claude/settings.local.json` — local to your machine,
  116. not committed — and takes it out again when you switch it off. Only ever
  117. once per stop, so a session can always end, and never a card someone else has
  118. already started.
  119. Several agents on one board is the case all of this is built for: the panel
  120. and every agent write through one place, and a write made against a board
  121. that has moved on since is rebased rather than believed — so a click in the
  122. panel cannot delete the card an agent filed a second earlier.
  123. - **Channel — a room the agents talk in** — several agents on one repo do not
  124. collide because they are careless; they collide because nothing tells them
  125. what the others are already inside. Each one sees a clean tree, opens the
  126. file its task points at, and finds out about the other when you read a diff
  127. where two changes have been folded together with no seam.
  128. Flare cannot lock the file. It watches a filesystem rather than sitting in
  129. front of one, so a lock could only be a request an agent is free to ignore —
  130. and one that silently fails open is worse than none, because everyone
  131. downstream believes it held. What it can do is give them somewhere to talk,
  132. and then draw what was said on the map. The **Channel** tab is that room:
  133. ```
  134. Claude 2 taking shared/graph.ts, shared/resolver.ts
  135. moving the workspace lookup out of the resolver
  136. Codex 1 asking @Claude 2 — is shared/graph.ts free? I need the edge
  137. builder for the cycle fix
  138. Claude 2 done shared/resolver.ts — all yours
  139. ```
  140. Three habits, and the tool descriptions ask for all three: **say what you are
  141. taking before you start** (`chat_post` with `kind: "taking"` and the paths —
  142. files or whole folders), **read the room when you finish something**
  143. (`chat_read`, which hands back only what you missed), and **ask by name**
  144. when you want a file someone has spoken for. You are in the room on the same
  145. terms: type into it from the panel and the agents read it back over MCP.
  146. Nothing is refused. Two agents *may* both say they are taking the same file —
  147. and when they do it is drawn as contention rather than resolved behind their
  148. backs, at the top of the tab and as a two-tone mark on the graph, because the
  149. two of them settling it is the only thing that actually settles it. An agent
  150. that writes a file another agent had spoken for is not blocked either; the
  151. crossing lands in the review with both names on it. Everything an agent says
  152. lapses on its own, so a session that is killed mid-edit does not hold a
  153. folder for the rest of the afternoon.
  154. It reads as a chat, because it is one: bubbles, consecutive lines from one
  155. speaker grouped under one name, your own posts on the right, and each agent
  156. carrying a geometric mark — ● ◆ ▲ — assigned with its colour and never apart
  157. from it, so the ▲ agent is the same amber one on the card, in the review and
  158. in the room. The tool descriptions ask the agents to write prose a colleague
  159. could read rather than status codes, and the prose is what the bubble leads
  160. with.
  161. Every line about files also **opens**. Everything said here is a claim, and
  162. Flare is the only participant that watched what followed — so a turn expands
  163. into what actually happened to the files it named: which the speaker went on
  164. to write and when, which it never touched, and *who else wrote one of them
  165. afterwards*. That last line cannot be got any other way, and the message it
  166. crossed is where you are already looking when you want it.
  167. The tab is also where you find out whether any of it is working. A busy feed
  168. is not evidence of coordination, so the header carries the number that is:
  169. **how many of the files the agents wrote this session had been announced here
  170. first**, with a button that selects the ones that were not. Beside it, who is
  171. in the room, what each said it is taking, and which of them has never once
  172. called `chat_read` — an agent that posts and never listens looks exactly like
  173. coordination right up until two of them collide. The transcript filters by
  174. agent, by kind and by text, and every path in it is a click to the graph.
  175. - **Claude 1, Claude 2, Codex 1** — the identity everything above rests on. A
  176. process list cannot tell two `claude` sessions apart (both are equally
  177. "running" in every sample) and neither can the board (it attributes by path,
  178. so an agent editing a file on someone else's card is recorded as them). The
  179. MCP session can: it is minted on `initialize`, echoed back on every request,
  180. and impossible for another client to answer to. Flare names each one from the
  181. tool it says it is plus the next free number, and that name then follows it
  182. everywhere — the ring on a node, the author of a change burst, the parties in
  183. a crossing, the row in the roster. Numbers are never reused inside a session,
  184. because a "Claude 1" that becomes a different agent halfway through would
  185. merge two of them in every sentence that mentions it.
  186. In the review, that shows up as a chip per agent above the change list —
  187. name, files written, how many of its changes nothing has checked — and
  188. clicking one narrows the list to that agent's work. One agent leaving all of
  189. its changes unverified is a fact about that agent, and it is invisible when
  190. its bursts are interleaved with two others' down a scrolling list.
  191. - **Review cockpit** — the tab that answers the questions a file-by-file diff
  192. can't. Changes are grouped into *bursts* (one batch of writes by one author),
  193. and each burst shows:
  194. - **what actually checked it.** The IDE sees both the file writes and the
  195. commands run in its terminals, so it can say *"the tests ran, then two more
  196. files were edited and nothing re-ran"* — the states are verified / failed /
  197. **checked, then edited again** / never checked, always quoting the output
  198. line the verdict came from.
  199. - **who did it.** Not "an agent" — *Claude 2*, in its own colour, with what
  200. it was doing beside the name. With three of them on one repo that is the
  201. difference between a list of changes and a list you can act on.
  202. - **what it was trying to do.** Agents call the `record_intent` MCP tool
  203. before editing — or say it in the channel, which counts as the same thing;
  204. otherwise the burst says so plainly, because reviewing an agent's diff
  205. makes you the first human to see that code with nothing explaining why it
  206. exists.
  207. - **what the session was about.** Everything else in the panel is derived
  208. from what Flare watched; this is the one thing it has to be told, because
  209. the answer does not exist in any single burst. It exists as a story, and
  210. the only participant who knows the story is the agent that lived it — so
  211. it is asked for, over MCP, before the session ends. `session_summary`
  212. takes a headline and *chapters*: a line of prose per piece of work and the
  213. files each one covers, and they sit at the top of the review, over the
  214. diff they are about.
  215. Not on trust, though. Flare watched the writes, so it binds every chapter
  216. to the bursts underneath it and reports the three ways a story and a
  217. session disagree: a chapter naming files that **never changed** (work
  218. described that did not happen — the one kind of wrong you cannot catch
  219. from a diff, because there is no diff to catch it in), files that changed
  220. and **no chapter accounts for**, and chapters covering work **nothing has
  221. verified**. That audit goes back to the agent in the tool's reply as well
  222. as onto the screen, so the usual outcome is that it fixes its own summary
  223. before anyone reads it:
  224. ```
  225. Your chapters account for 2 of the 3 files you changed.
  226. "Left the workspace cache alone" names shared/cache.ts, which never
  227. changed — say what you actually did to it, or drop it.
  228. Not mentioned anywhere: src/components/ReviewPanel.tsx.
  229. ```
  230. - **which files deserve attention.** Every file is tiered *read carefully /
  231. read / skim* from blast radius, coverage, cycles and complexity, with the
  232. reason spelled out ("9 files break if this is wrong", "no test covers it"),
  233. so a 30-file change doesn't get 30 equal glances. The tier is a heading
  234. over its group rather than a badge on every row, and on a big change the
  235. skim group starts folded.
  236. - **agent smells.** Rules for the shortcuts agent changes take and human ones
  237. don't: a test edited in the same burst as the code it covers, assertions
  238. deleted, `.skip`/`.only` added, lint or type suppressions introduced,
  239. coverage thresholds lowered, complexity spikes, files left with no
  240. importers, abstractions extracted for a single caller.
  241. - **one-click undo.** Every burst has a snapshot: revert a file, revert the
  242. burst, or jump **back to the last state whose checks passed**.
  243. - **walkthrough** — step the graph through a burst's files worst-risk first,
  244. approving as you go.
  245. - **Risky changes come and find you** — the review tab is a tab, so a load-
  246. bearing file rewritten while you were reading the graph goes unnoticed until
  247. you go and look. Those changes queue behind a chip in the top bar instead,
  248. beside the review count: a number you can see from across the room, and the
  249. cards one click under it, newest first, staying put until answered.
  250. **Review** opens the change on its row in the review panel, **Dismiss** stops
  251. that card, **Dismiss all** clears the queue. Dismissing an alert is not
  252. approving the change — the file stays flagged, unread and exactly as the
  253. agent left it.
  254. It is a chip rather than a floating panel because there is no corner for one.
  255. The bottom-right is the terminal, where a card hides the output of the very
  256. agent whose change it is reporting on; the top-right is where every tab keeps
  257. its own controls, so a panel there sits on `+ Lane`, on `Re-layout`, on the
  258. channel's composer, and swallows the clicks meant for them. A queue that is
  259. usually non-empty during an agent session cannot be a panel. The transient
  260. toasts keep that corner — they have no controls at all, so the whole stack is
  261. click-through and can never eat the next thing you press. The bar is the
  262. *careful* tier plus something absolute (real dependents, a cycle, real
  263. complexity, no test at all), so a repo where nothing is load-bearing stays
  264. quiet rather than popping a card for its least boring file.
  265. - **Comprehension debt, measured** — the *Unread* lens paints every file that
  266. changed this session and no human has opened since; approving does not clear
  267. it, opening the file does. Insights shows the repo-level percentage.
  268. - **Every command classified** — the command log labels each observed command
  269. read / writes / verify / network / **destructive**, filterable, with the
  270. pass/fail verdict next to verification runs. Destructive commands
  271. (`rm -rf`, `git reset --hard`, `push --force`, `npm publish`, …) raise an
  272. alert and trigger a snapshot.
  273. - **Coverage ingestion** — drop an `lcov.info` (vitest/jest `--coverage`, nyc,
  274. pytest-cov…) in `coverage/` or the project root and it's picked up live: a
  275. Coverage lens appears, per-file percentages land in the details panel and
  276. hover cards, and real coverage replaces the test-linkage heuristic inside
  277. the review-risk score.
  278. - **Drill-downs** — collapse any directory into an aggregate meta-node (click
  279. its legend chip or double-click the node); expand any file into its
  280. functions/classes with symbol-level edges. Shift-click two nodes to highlight
  281. the import path between them.
  282. - **Cross-agent tracking** — the process tree of every terminal is watched for
  283. claude / codex / opencode / aider / …; changes made while an agent runs are
  284. attributed to it (coloured node rings, trails on the graph, "changed by" in
  285. details), and every shell command run in the terminals lands in the
  286. **Commands log** (▤ button in the terminal bar, persisted per project). That
  287. is the *terminal* half of it — the MCP half, which is what tells two claudes
  288. apart and puts a mark on the files each of them is inside, is the room above.
  289. - **Command palette** — Ctrl+K: fuzzy-jump to any file, `>` for commands,
  290. recent projects. Ctrl+B sidebar, Ctrl+W close tab, Ctrl+0 fit graph,
  291. Ctrl+=/− zoom, Esc collapses focus/drill-down. Full list under
  292. `> keyboard shortcuts`.
  293. - **Insights** — a unified metrics + issues view: per-file risk/hotspot/
  294. refactor composites, blast radius, churn (git + session), coverage, TODOs,
  295. co-change coupling; severity-ranked rules (regression-risk, god-file,
  296. agent-thrash, coverage-gap, cycles, dead code…) with a critical-alert badge
  297. and toasts.
  298. - **Reuse** — how cleanly each file would come out if you lifted it into a
  299. package, 0–100, plus one number for the whole repo. It counts the four
  300. things that actually stop you: talking to the host (`fs`, sockets, a
  301. database), being bound to a framework, dragging a large share of the repo
  302. along, and sitting in an import cycle. Being widely imported is *not* a
  303. penalty — a util forty files depend on is the most reusable thing you have,
  304. which is the opposite of how risk reads the same number. Unlike the other
  305. composites it is an absolute scale rather than a ranking within the repo: if
  306. everything imports `fs`, the least-bad file has not become reusable. The
  307. `mixed-concerns` rule points at the files where logic is trapped behind the
  308. plumbing and worth separating.
  309. - **MCP server for your agents** — one shared, localhost-only endpoint for
  310. the whole machine, however many Flare windows are open. Each instance
  311. runs a private ephemeral server and registers in a per-pid file registry;
  312. whichever instance holds the well-known port (default 7345,
  313. `FLARE_MCP_PORT`) acts as the gateway and routes `…/mcp/<slug>` — the same
  314. stable per-project slug the browser server uses — to the owning instance,
  315. proxying when needed and taking over the port when the holder exits. Bare
  316. `/mcp` works with a single session; with several it points the agent at
  317. `list_projects`. **Connect agent**, in the terminal bar, opens a dialog with
  318. the two steps — and they are genuinely two. Registering the server is a
  319. config change you make once per machine, and it is different for each of the
  320. three: a command for Claude Code, a command for Codex, JSON in a file of its
  321. own for opencode.
  322. ```sh
  323. claude mcp add --transport http flare http://127.0.0.1:7345/mcp/<slug>
  324. ```
  325. The second step is the one that is easy to skip and shouldn't be: **the line
  326. you open the agent with**. Attaching the tools does not make an agent read
  327. them, and everything this project expects — taking a card before starting it,
  328. saying in the channel which files it is about to edit, writing the session
  329. down before it stops — comes back from one call. So the dialog hands you a
  330. message to paste, with the endpoint in it, that says to make that call first:
  331. ```
  332. This project is open in Flare, which is on MCP at http://127.0.0.1:7345/mcp/<slug>.
  333. Start by calling `working_agreement` — it says how this project wants you to
  334. work, what is on the board, and who else is in here. Then take the card it
  335. points you at.
  336. ```
  337. It is deliberately short. A paragraph restating the protocol would be a
  338. second copy of it, going stale the moment you change the ⚙︎ Routine — and the
  339. agent is about to be handed the current version by the tool itself.
  340. Tools: `graph_overview`, `file_info`, `dependents`, `dependencies`,
  341. `find_path`, `issues`, `top_files`, `search`, `impact_of` (what breaks +
  342. which tests to run before changing files), `recent_activity`,
  343. `verification_status` (did my changes actually get checked?),
  344. `record_intent` (state the goal before editing, so the human reviewing the
  345. diff isn't reconstructing it), the board tools — `tasks_list`, `task_get`,
  346. `task_update`, `task_create` — the collaboration tools: `decision_record`,
  347. `decisions_list`, `question_ask`, `questions_list`, and `working_agreement`
  348. for what to do next — and the tools for working alongside other agents:
  349. `chat_post`, `chat_read` and `agents_list`. The agent asks the IDE about the
  350. codebase instead of re-deriving it.
  351. - **Workspace restore** — tabs, lens, active view, panel sizes, collapse
  352. state, node positions and window bounds all persist per project.
  353. - **Live change tracking** — a debounced watcher re-parses changed files and
  354. patches the graph in place. Changed-but-unreviewed nodes are marked in
  355. warning-orange with a heat decay, so an agent's progress is visible as it
  356. works.
  357. - **Review queue** — every file changed since your last checkpoint is flagged.
  358. Nothing is gated: an agent writes straight to disk, so reviewing is deciding
  359. what to keep. Dismiss clears the marker and changes nothing; revert puts the
  360. files back. Review next walks them worst-risk first, and each node shows its
  361. blast radius (transitive dependents), import counts and symbols.
  362. - **Shadow history ("git of local changes")** — a hidden git repo (separate
  363. `GIT_DIR`, your worktree) auto-commits every change burst. Timeline panel lists
  364. snapshots; diff any file against any snapshot, revert one file or restore the
  365. whole tree. Your real repo is never touched.
  366. - **Git integration** — branch + per-file status in the tree and graph, diff vs
  367. HEAD in a Monaco diff editor.
  368. - **IDE basics** — file tree, Monaco editor (VS Code's editor) with Ctrl+S save
  369. and external-change reload, multiple terminals (xterm.js + node-pty) running
  370. real shells.
  371. - **Light and dark** — *View ▸ Theme*, following your desktop unless you pin
  372. one. A theme is a single block of tokens in src/styles.css: the neutral
  373. ramp runs surface→ink rather than dark→light, so the ~460 places the
  374. stylesheet names a step do not change when a theme is added. The three
  375. things that draw outside CSS — the graph, the editor and the terminal —
  376. read those same tokens rather than carrying palettes of their own, and
  377. tests/palette.test.ts holds the line: colours only inside a palette, none
  378. in the roles, and every theme declaring the same tokens so a half-written
  379. one fails loudly instead of rendering with holes in it.
  380. ## Testing
  381. ```sh
  382. npm test # 633 vitest unit tests (parser, resolver, graph, scanner, git, shadow, store, reuse, roster, channel)
  383. npm run e2e # 80 Playwright tests: 56 driving the real Electron app, 24 driving a browser
  384. npm run verify # build + unit + e2e
  385. ```
  386. ## Architecture
  387. **One implementation, two transports.** `electron/core.ts` is all of Flare's
  388. behaviour with no window and no Electron: a map of channels to handlers, and an
  389. `onEvent` callback. The desktop main process and the browser server are
  390. adapters that only translate — neither names a channel, so a feature added to
  391. the core reaches both without a second edit. `tests/singleSource.test.ts`
  392. enforces that, and it is why serving Flare to a browser did not fork the
  393. codebase.
  394. - `shared/` — pure engine: import parser (comment/string-safe lexer + regex),
  395. module resolver, incremental graph builder with patch diffing, project scanner.
  396. No Electron dependencies; fully unit-tested.
  397. - `electron/core.ts` — the backend: project session (scan → graph → watcher →
  398. events), git service, shadow-history service, PTY service, agent monitor, MCP
  399. server, persisted per-project store (node positions, review state). Plain
  400. Node. The desktop-only bits — folder picker, OS clipboard, window buttons —
  401. are injected as an optional `CoreHost`.
  402. - `electron/main.ts` + `preload.ts` — the desktop adapter: a window, its
  403. remembered bounds, the macOS menu, and a generic `contextBridge` bridge.
  404. - `server/` — the browser adapter: serves the built `dist/` and carries the
  405. same calls and events over one websocket, riding on the ports the MCP server
  406. already owns so one instance needs exactly one port. A supervisor holds the
  407. port and serves the start screen; each project it is asked for becomes a
  408. session process of its own at `/<slug>/`. Everything it serves, websocket
  409. included, is behind the token in `server/auth.ts`.
  410. - `src/api.ts` — the typed client both transports share; the only line that
  411. differs between desktop and browser is which transport it is handed.
  412. - `src/` — React renderer: the three graph views (`CanvasView`, `WheelView`,
  413. `DistrictsView`) over a shared render model and lens palette, Monaco
  414. editor/diff, xterm terminals, file tree, details panel, timeline, review
  415. banner.
  416. Node ↔ renderer flow: chokidar batch → re-parse → graph diff → `evt:graphPatch`
  417. → graph patch + heat, plus debounced git status refresh and shadow snapshot.
  418. ## Run it
  419. Requires Node 20 or newer.
  420. ```sh
  421. npm install
  422. npm run build # bundle main process (esbuild) + renderer (vite)
  423. npm start # launch the desktop app
  424. ```
  425. ## Install it (Windows / macOS / Linux)
  426. Built releases are on the [releases page](https://github.com/AlgoNoRhythm/Flare/releases):
  427. | Platform | Download | Notes |
  428. | --- | --- | --- |
  429. | Windows | `Flare-<version>-Windows-x64.exe` | NSIS installer, per-user, choose your own directory. A `.zip` is there too if you would rather not install anything. |
  430. | macOS, Apple silicon | `Flare-<version>-macOS-arm64-beta.dmg` | **Beta** — see below. |
  431. | macOS, Intel | `Flare-<version>-macOS-x64-beta.dmg` | **Beta** — see below. |
  432. | Linux | `Flare-<version>-Linux-x86_64.AppImage` | `chmod +x` and run. A `.deb` and a `.tar.gz` are published too. |
  433. The macOS packages still say **beta** in their filename, but for a narrower
  434. reason than they used to.
  435. They have now run on a Mac. The full suite — 544 unit tests and 78 end-to-end
  436. tests, Electron and browser — passes on macOS 14, and the packaged `.app` is
  437. booted out of its own DMG and checked for a working terminal before a release
  438. goes out, the same bar Windows and Linux are held to. What is *not* covered is
  439. Apple silicon specifically: the hardware behind this project is Intel, so the
  440. `arm64` package is built and signed but has never been launched. That is what
  441. the beta label is now for.
  442. They are also **ad-hoc signed and un-notarised**. Notarising needs a paid Apple
  443. Developer account, so Gatekeeper will still refuse the first launch — the
  444. signature is there to satisfy the loader, not Gatekeeper. Open it once with
  445. right-click → Open, or clear the quarantine flag:
  446. ```sh
  447. xattr -dr com.apple.quarantine /Applications/Flare.app
  448. ```
  449. To build one yourself:
  450. ```sh
  451. npm run dist # installer for the platform you are on, into release/
  452. npm run dist:dir # unpacked, for a quick look
  453. ```
  454. Run it **on the platform you are building for**. Flare's terminal is a native
  455. module that ships as a prebuilt binary per platform and architecture, and npm
  456. installs only the one for the machine doing the installing — so a Linux package
  457. built on Windows contains the Windows binary and opens no terminal at all. That
  458. is what the release workflow's one-runner-per-platform matrix is for
  459. (`.github/workflows/release.yml`); tag a version and it builds all four:
  460. ```sh
  461. npm version 0.2.0 && git push --follow-tags
  462. ```
  463. It uploads to a **draft** release, so nothing is public until the artifacts are
  464. all there and someone has looked at them. The title bar is platform-aware:
  465. custom controls on Windows/Linux, native inset traffic lights on macOS.
  466. Windows CI signing uses SignPath: manual dry runs use `test-signing`, while
  467. release builds require `release-signing`. The Foundation test setup and required
  468. GitHub secret are documented in [Windows signing](docs/windows-signing.md).
  469. Production signing remains pending SignPath's setup review and certificate issuance.
  470. On Windows, WSL2 is enough to test the Linux build properly: WSLg supplies a
  471. display, so the desktop suite runs against real Electron and the AppImage
  472. actually boots. Work inside the WSL filesystem rather than `/mnt/c` — `npm ci`
  473. against the Windows tree from Linux replaces `node_modules` with Linux
  474. binaries and breaks the Windows checkout.
  475. ```sh
  476. cp -r /mnt/c/path/to/Flare ~/flare && cd ~/flare && npm ci
  477. npx playwright install chromium
  478. npm test && npx playwright test # 633 unit + 80 e2e, on Linux
  479. npx electron-builder --linux --publish never
  480. ```
  481. Development mode (hot reload for the renderer):
  482. ```sh
  483. npm run dev
  484. ```
  485. Flare opens to a start screen listing your recent projects — arrow keys and
  486. Enter, or `Ctrl+O` to pick a new folder. The last project you had open is the
  487. first row, so restoring it is one keystroke rather than an assumption.
  488. `FLARE_PROJECT=<path>` skips the start screen and opens that project directly.
  489. ## Run it in a browser (any remote machine)
  490. Flare's review cockpit works by watching the process tree under its own
  491. terminals, so the backend has to run on the machine the agent runs on. When
  492. that is not your laptop — a VM, a dev container, a build box, a cloud
  493. workstation, anything you reach over SSH or a forwarded port — serve it
  494. instead of installing it:
  495. ```sh
  496. npm install
  497. npm run serve # or `npm run serve -- /path/to/project`
  498. ```
  499. ```
  500. Flare — http://127.0.0.1:7345/?token=oq_F45fBJGdMTK4NJdm6y53n7-lHezBd
  501. the token is asked for once per browser — ~/.flare/web-token
  502. open it to pick a project — each one gets its own url
  503. ```
  504. **The port is the start screen.** Open it and you get Flare's own start
  505. screen — the same one the desktop app opens to, laid out the same way: the
  506. projects you have opened before, and a folder browser that walks the
  507. filesystem on that machine (the desktop keeps the system dialog as well, on
  508. Ctrl+O). Pick one and it starts a session for it and takes you to its URL:
  509. ```
  510. http://127.0.0.1:7345/api/
  511. ```
  512. From there it is the same IDE: the graph, the editor, the review cockpit, and a
  513. real terminal on the remote machine.
  514. **The terminal does not wait for the round trip.** A shell on another machine
  515. echoes what you type one network hop later, and at 80ms that is a terminal
  516. that feels underwater. Every key still goes out the moment it is pressed — Tab
  517. completion, history search and whatever agent is running in there all need the
  518. raw stream — but the character is drawn locally first and the shell's echo is
  519. treated as confirmation, the way mosh does it: only at a visible cursor on the
  520. main screen, undone before any output is applied so nothing can double, and
  521. switched off by itself for anything that does not echo (a password prompt, a
  522. full-screen program). It measures the echo delay as it goes and does nothing
  523. while the delay is short, so the desktop window behaves exactly as before.
  524. Underneath, keystrokes travel as one-way frames nobody acknowledges, terminal
  525. output is batched per event-loop turn instead of per pty read, and the socket a
  526. session's tab is proxied over runs with Nagle's algorithm off.
  527. **One port, many projects.** The url is the folder name — `/api/`, not
  528. `/api-3f21b8/`. It is assigned once and remembered, so it stays the same across
  529. restarts and reboots; two projects sharing a folder name get qualified by their
  530. parent (`/side-api/`) rather than by a hash. Each project runs as its own
  531. process with its own terminals and its own agents, so several can stay open in
  532. several tabs without touching each other. Whichever process holds the port
  533. routes to the others; when it exits another takes over and every URL keeps
  534. working. Agents connect over that same port at `/mcp/<slug>`, so a restricted
  535. machine only ever has to expose one.
  536. **Getting to the port.** Flare listens on `127.0.0.1` by default and tells you
  537. so — a loopback URL is useless from the laptop you are actually sitting at, so
  538. it prints the machine's real addresses too and says what to do about them:
  539. ```
  540. Flare — http://127.0.0.1:7345/?token=oq_F45fBJGdMTK4NJdm6y53n7-lHezBd
  541. reachable from this machine only. From your laptop, either
  542. ssh -L 7345:127.0.0.1:7345 you@workbench
  543. or restart with --host 0.0.0.0 for http://10.128.0.7:7345/?token=…
  544. ```
  545. A tunnel or your cloud IDE's port forwarding exposes nothing and works
  546. anywhere. Flare's asset and websocket URLs are page-relative, so it also runs
  547. unmodified behind a path prefix — `jupyter-server-proxy`'s `/proxy/7345/`, a
  548. VS Code tunnel, an nginx `location` block — with no configuration.
  549. **The token.** Behind this port are your files, your history and a live shell,
  550. so the browser side asks for a token — the one in the URL above. It is
  551. generated on first run and kept in `~/.flare/web-token`, so the printed URL
  552. keeps working across restarts; `--token <value>` or `$FLARE_TOKEN` sets your
  553. own. Opening a URL that carries it stores a cookie, so it is asked for once per
  554. browser and never appears in an address bar again; a URL without one gets a box
  555. to paste it into. Scripts can send it as `Authorization: Bearer` or
  556. `X-Flare-Token`. `--no-token` (or `$FLARE_NO_TOKEN=1`) turns the whole thing
  557. off, for a tunnel you trust or a proxy that already authenticates.
  558. Agents are outside it: `/mcp/<slug>` stays open, because a token there would
  559. break every `claude mcp add` line already written into a config file. It is
  560. loopback-only unless you widen the host.
  561. **`--host 0.0.0.0` (or `$FLARE_HOST`) listens on every interface** and prints
  562. the URLs that will answer, hostname first. Do this only on a network you trust:
  563. the token is the only thing in front of a filesystem and a shell, and the MCP
  564. endpoint moves with it. The per-instance private ports stay on loopback either
  565. way; only the shared one moves.
  566. **The URL of the machine, whatever shape it takes.** Every hosted environment
  567. addresses a forwarded port differently, and none of those addresses appear in
  568. the VM's own interfaces — so Flare derives the shape from the environment
  569. rather than assuming one:
  570. | where it runs | the URL it prints |
  571. |---|---|
  572. | your PC, a bare VM | its hostname and real addresses |
  573. | GitHub Codespaces | `https://<codespace>-7345.app.github.dev/` |
  574. | Gitpod | `https://7345-<workspace>.gitpod.io/` |
  575. | JupyterHub, `jupyter-server-proxy` | `https://<hub>/user/<you>/proxy/7345/` |
  576. Project slugs are appended to whichever it found, so the printed URL is the
  577. one you can actually paste:
  578. ```
  579. Flare — https://hub.example.com/user/malte/proxy/7345/
  580. api → https://hub.example.com/user/malte/proxy/7345/api/
  581. ```
  582. Anything else behind a proxy Flare cannot see takes `--public-url` (or
  583. `$FLARE_PUBLIC_URL`, which sessions inherit). A bare host gets the port
  584. appended; a value that already carries a port, a path prefix, or `https` is
  585. used exactly as given.
  586. State lives in `~/.flare` (`$FLARE_USERDATA` to move it), the token included;
  587. `--port` or `$FLARE_PORT` changes the shared port.
  588. The terminal's PTY module is the only native dependency; everything else is
  589. pure JS, so on an unfamiliar machine that is the one thing worth checking:
  590. ```sh
  591. node -e "require('@lydell/node-pty')" # silence means the terminal will work
  592. ```
  593. This is not a second app: it is the same `dist/` bundle and the same backend as
  594. the desktop build, reached over a websocket instead of Electron IPC — see
  595. [Architecture](#architecture).
  596. ## License
  597. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.