FlowState 2.5.0

FlowState 2.5.0 publishes the free server as flowstatemcp on PyPI and nudges agents to log as they go.

Install

uvx flowstatemcp

Or: pipx run flowstatemcp. After pip install flowstatemcp, the flowstatemcp and flowstate commands both start the stdio server.

Added

• The free server is the PyPI package flowstatemcp. The import name stays flowstate. A GitHub release publishes the sdist and wheel with PyPI Trusted Publishing.
• The next brief reminds an agent that logged nothing. If the previous session on a project read FlowState and saved no record, the next start_here adds one line telling the agent to log decisions and changes as it works.
• Copy-paste rules and one-click install. README and AGENTS.md have a three-line rule for CLAUDE.md, AGENTS.md, Cursor, Windsurf, VS Code Copilot, Claude Projects, and ChatGPT, plus Add to Cursor and Add to VS Code links for uvx flowstatemcp.

Changed

• Agents are told when to write, not only what to write. log_work, and the todo, problem, and handoff tools, say to record a decision, change, fix, or lesson right after it happens, and again before the session ends. The FlowState skill is now version 2.6.

Updating

• From 2.4.4 or later: quit your AI apps and run flowstate update in your own terminal, then reopen them. Or switch to uvx flowstatemcp.
• From 2.4.3 or older: follow "Updating" in the README.

Full details: CHANGELOG

FlowState 2.4.9

FlowState 2.4.9 makes confirmations stick to the exact words you approved.

Changed

• A confirmation belongs to the exact words you approved. When something is confirmed, the confirmation is tied to that wording.
• Editing confirmed words sends it back for review. Changing the approved text clears the confirmation.
• Approvals for older wording are refused. You can't confirm a version that has since been edited.
• Routine status and priority changes keep their confirmation.

Who is affected

• Existing confirmations stay valid: migration 025 carries them over automatically.

Updating

• From 2.4.4 or later: quit your AI apps and run flowstate update in your own terminal, then reopen them.
• From 2.4.3 or older: follow "Updating" in the README.

Full details: CHANGELOG

FlowState 2.4.8

FlowState 2.4.8 is a small release on top of 2.4.7. It changes what FlowState tells your AI apps when they connect. The Python packages are the same as 2.4.7.

Changed

• AIs check FlowState's learnings when something breaks. The connect-time instructions and the FlowState Agent Skill (now version 2.5) tell the AI: when it hits an error, a failing test or a bug, or gets stuck, it should first search the project's learnings, problems and solutions and try what is already recorded. After it fixes something non-obvious, it should log a learning (with no secrets). AGENTS.md says the same.
• AIs mention the FlowState skill once. In apps that support Agent Skills (Claude Code, Codex, Cursor and others), if the flowstate skill is not loaded, the AI mentions once where to get it. Web-only apps (claude.ai, ChatGPT) never get this.
• The skill's author is now DialectForge instead of a personal name.

Tests

• The HTTP idle auto-close test no longer fails at random on slow CI runners.

Who is affected

• Everyone using FlowState with an AI app: after updating and reopening your apps, the AI is more likely to reuse fixes you already recorded and to record new ones.
• No change to your data, settings or commands.

Updating

• From 2.4.4 or later: quit your AI apps and run flowstate update in your own terminal, then reopen them. To pick up skill 2.5, reinstall the skill with python setup_flowstate.py --install-skill.
• From 2.4.3 or older: follow "Updating" in the README.

Full details: CHANGELOG

FlowState 2.4.7

Changed

• The pages FlowState shows in a browser use the new FlowStateMCP look; no behavior changes.
  The review page, the phone approve and review pages reached through FlowState Relay, the
  remote review sign-in and the remote access consent page now match flowstatemcp.com (light
  palette, larger tap targets, 16px fields on phones). Forms, links, routes and security headers
  are unchanged; a new test pins them to 2.4.6.

Tests

• test_display_name: the wait for the fourth relay name message is longer (it timed out on
  slow Windows CI runners).

FlowState 2.4.6

FlowState 2.4.6 is a small fix release on top of 2.4.5. Nothing changes in how FlowState works for you, and the Python packages are the same as 2.4.5.

Fixed

• Creating a method without a description no longer crashes. Creating a method with no name or description used to fail with KeyError: 'description'. It now returns a clear bad_request that says what is missing, and nothing is saved.
• Erasing a project now removes every row that refers to it. flowstate erase project:N used to leave rows for the erased project in the activity log, the run ledger (run_writes, run_views) and the project's own approval and review settings. Those rows are now found by column in every table and removed. Per-app settings, your own settings and sign-ins are not project data and stay.

Who is affected

• Anyone who erases a project with flowstate erase project:N: from 2.4.6 on, nothing from that project is left behind.
• Anyone whose AI app created a method without a description: it now gets a clear error instead of a crash.
• Everyone else: no visible change.

Tests

• New tests check both fixes. They fail on 2.4.5 and pass on 2.4.6. The full suite passes (1839 passed, 5 skipped).

Updating

• From 2.4.4 or 2.4.5 (Mac, Linux and Windows): quit your AI apps and run flowstate update in your own terminal.
• From 2.4.3 or older: follow "Updating" in the README; the 2.4.4 notes for your version still apply.

Full details: CHANGELOG

FlowState 2.4.5

FlowState 2.4.5 is a small fix release on top of 2.4.4. Nothing changes in how FlowState works for you, and the Python packages are the same as 2.4.4.

Fixed

• Windows: changing settings no longer crashes when two FlowState commands do it at once. While one command was finishing with the settings lock file, the next one could stop with "Permission denied" on config.json.lock. It now waits and tries again, and if the other command takes too long it says so ("Another FlowState command is changing ...").
• The computer name is recorded again on machines with a random-looking name. Some cloud and CI computers have a host name that looked like a token to FlowState's secret check, so the "machine" column of the settings and approvals log was left empty. Such a name is now recorded as a short label, computer- plus 8 characters, the same every time. A name that contains a real key format still records nothing.

Who is affected

• Windows users who run more than one FlowState command or app that changes settings at the same time.
• Anyone whose computer has a long random host name (mostly cloud and CI machines): the settings log now shows a machine for those changes.
• Everyone else: no visible change.

Tests and CI

• The full test suite now passes on Windows, macOS and Linux with Python 3.11, 3.12 and 3.13 (all 9 CI jobs).
• Three tests that could not pass on Windows now really run there, and CI lists the slowest tests and has a time limit.

Updating

• From 2.4.4 (Mac, Linux and Windows): quit your AI apps and run flowstate update in your own terminal. 2.4.5 uses the same Python packages as 2.4.4, so Windows can update in place too.
• From 2.4.3 or older: follow "Updating" in the README; the 2.4.4 notes for your version still apply.

Full details: CHANGELOG

FlowState 2.4.4

FlowState 2.4.4

Tap-to-decide review cards in the chat, a plain-word guide to what you can ask, and a long list of security and data-safety fixes.

What's new

Review cards in the chat. Session summaries, suggestions, imports, clean-up ideas, markdown edits and possible conflicts can now show up as small cards with buttons right in the chat. The AI calls show_review_card to show one item, or up to 5 waiting items of a project. Each card says what the item is, what saving it would do, and which app wrote it and when, with Approve and Reject. Disagreements keep their own card (show_conflict_card). We tested the cards in Claude Desktop and the Claude iPhone app. Every other app gets the same card as plain text, plus the review link.

Taps only count when you tap. The card buttons call tools the AI can't see or call (resolve_review_card, resolve_conflict_card). The first time an app that signs in over the network could show you a card, FlowState asks you once, on your review page and your phone review page: "Allow tap cards in <app>?".

New guide: What you can ask FlowState. Plain-word examples of what to ask your AI, from saving a decision to reviewing what a session saved.

Also new

• Session summaries show what the session saved, with Keep all, plus Keep / Remove for each record.
• Project history on the review page: every change in a project and which app made it.
• Unsettled decisions are marked in the brief. While a possible conflict is open, the newer decision stays tagged unsettled, so an AI doesn't just follow the older one.
• A name for this FlowState ("Main FlowState" until you change it), and both names (the app's claim and its real sign-in) wherever FlowState shows who wrote something.
• flowstate erase removes records for good, including quotes of them in review items and history.
• Undo is smarter around cards: if an undo closed possible conflicts, FlowState asks whether to reopen them.

Security and data-safety fixes

• Only you add or remove hard rules. A rule an app adds waits for your approval.
• Apps connected with a per-app key, a remote token or an OAuth sign-in can't delete.
• Approve / Reject popups go only to apps on this computer.
• Data-git can't send your data anywhere on its own, and it now shares the markdown exports, not the database.
• The nightly off-site copy is encrypted on this computer before it leaves.
• App config files and other private files are written readable only by you.
• Delete and clean-up approvals cover exactly the records you were shown.
• OAuth fixes: one exact issuer, no CORS on the OAuth endpoints, working token revocation, and a token audience check.
• mcp is now 1.30 or later. Earlier versions are affected by GHSA-w4fh-qvv9-3v23.

How to update

Read this first: 2.4.4 needs new Python packages (mcp>=1.30,<2), so it comes with a new .venv.

• Mac and Linux, on 2.4.0 or later: quit your AI apps, then run flowstate update in your own terminal, in the FlowState folder. Don't ask an AI to do it. The update stops if an app is still running FlowState, and puts the old version back if anything fails. Then reopen your AI apps.
• Windows, or anyone older than 2.4.0: update by hand. Quit your AI apps, then in the FlowState folder run:

  git fetch --tags
  git checkout v2.4.4
  python setup_flowstate.py
  

  Run setup with the same options you used the first time. Restart FlowState's HTTP and relay services if you run them, then reopen your AI apps.
• Don't run pip install --upgrade flowstate. FlowState isn't on PyPI, and that name belongs to an unrelated project.

After updating

• Data-git users: update every computer to 2.4.4 first, then run flowstate data-git migrate once on each. A computer still on 2.4.3 that pulls a migrated repository can lose its database.
• Remote access: update cloudflared to 2026.10.2 or later (cloudflared --version).
• Popups on a LAN app with its own key: run flowstate approvals popup add --sign-in "<key name>" once.

Signed release

The v2.4.4 tag is SSH-signed with the FlowState release key, and GitHub shows it as Verified. flowstate update only installs a tag signed by a key listed in your current copy (mcp-server/flowstate/release_signers), and flowstate update --dry-run shows signed by flowstate-release before it changes anything.

Thanks

Auth-scanned by Leroy H. Mason using mcp-authscan. His scan of a beta relay address found the token endpoint CORS header, the /revoke issue and the issuer's trailing slash, all fixed above. A scan is not an audit.

Full details: CHANGELOG.md

FlowState 2.4.3

FlowState 2.4.3

What's new

Disagreement cards. Sometimes two AIs save entries that contradict each other, for example
"use JWT tokens" and "use session cookies" for the same part of a project. FlowState now
puts the two side by side in one card: Claim A and Claim B, which app wrote each one and when,
and up to two short pieces of evidence (a file:line or a bit of output). You pick
Keep A, Keep B or Keep both, or dismiss the card. The entry you don't keep is
marked "superseded". It is not deleted.

You see the card:

• on the review page (flowstate review-page, or the "FlowState review" desktop shortcut),
• in the chat as plain text, in any app,
• as a small in-chat card with buttons, in apps that support MCP Apps (tested in Claude Desktop).
  You can also ask the AI to show the card for a disagreement.

Deletes now list the exact records. When approvals are on and an AI asks to delete
something, the request now shows what the database will actually remove: the record, its
key fields, and for a project or component the records inside it, by name. The AI's own
explanation is shown separately, labelled "AI's note".

Fixed: a test that could fail on slow build machines now has a longer time limit. This
changes nothing for users.

Upgrading

• flowstate update works from 2.4.0, 2.4.1 or 2.4.2. Then quit and reopen your AI apps.
• There are no new dependencies. One database change: FlowState adds three new tables
  for the cards and makes a backup first. Your existing records are not changed.

Known follow-up

FlowState can't yet prove that a tap on the in-chat card came from a person and not from the
AI. The button tool is hidden from the AI, and it refuses anything that looks like chat text.
Through the relay with chat approvals off (the default), a tap is refused and you get the
phone link instead. For anything important, decide it on the review page or your phone.

FlowState 2.4.2

FlowState 2.4.2

A small release about who can approve things, plus fixes. Please read the first point before
you update.

Changed: AIs on the relay can't approve in the chat any more (unless you allow it)

• If you use the optional FlowStateMCP relay (claude.ai, ChatGPT and other cloud AIs reach your
  FlowState through it), those AIs can no longer approve or reject review items in the chat
  after you update, even when they quote you. They answer that nothing was decided and give
  you the item's phone link, so you decide it yourself on your phone (or on the computer where
  FlowState runs).
• To allow it again, run flowstate relay chat-approvals on in your own terminal (it asks you
  to type y). flowstate relay chat-approvals off turns it back off, and
  flowstate relay chat-approvals shows the setting. There is no tool for it, so an AI can't
  turn it on through FlowState.
• Items that are yours alone stay locked either way (with approvals on: deletes and turning
  review off; and "did you say this yourself?" checks).
• Apps connected directly (on your computer, your own network or your own tunnel) are not
  affected.

Fixed

• When an AI's answer puts something in your review queue, it now also says how you decide it:
  your phone link (with the relay) or the review page link (apps on the computer where FlowState
  runs), and a plain line telling the AI not to approve it itself. Before, through the relay
  the answer had no link, so an AI offered to approve the item in the chat.
• Tests only: the desktop shortcut test failed on Linux, the test setup crashed on stock
  Debian / Ubuntu Python, and the wheel install test failed on Windows. FlowState itself was
  not affected by any of them.

Also

• The README now has two phone screenshots of the review page (relay users).
• No new dependencies, no database changes, no new tools.

How to update

• You have 2.4.0 or 2.4.1 from the FlowState folder: ask your AI to "update FlowState", or
  run <venv python> -m flowstate update in the FlowState folder. The dependencies are the
  same, so it needs no new .venv and works on Windows too. Then quit and reopen your AI apps.
• You don't have 2.4.0 yet: in your FlowState folder run git pull (or git fetch --tags
  and git checkout v2.4.2 if your folder is at a release tag), then
  python setup_flowstate.py --clients <your apps> --verify with the same options as when you
  set it up, then quit and reopen your AI apps.
• You installed with plain pip: reinstall from the 2.4.2 code the same way (for example
  pip install ./mcp-server in a 2.4.2 copy of the FlowState folder). Your database is kept.

FlowState 2.4.1

FlowState 2.4.1

A quick fix for one install problem in 2.4.0.

Fixed

• Installing with plain pip didn't work. If you installed FlowState with pip install (not
  pip install -e), or from a built wheel, FlowState's database file was left out, so every
  FlowState call said FlowState was unavailable. Installs from the FlowState folder
  (setup_flowstate.py, or pip install -e mcp-server) were not affected. The database file now
  ships with the package.
• That failed start also left an empty database file behind, which kept FlowState unavailable
  even after reinstalling. FlowState now sets up such an empty file as a new database.

Nothing else changed: no new dependencies, no database changes, no new tools.

How to update

• You have 2.4.0 from the FlowState folder: ask your AI to "update FlowState", or run
  <venv python> -m flowstate update in the FlowState folder. It needs no new .venv, so it
  works on Windows too. Then quit and reopen your AI apps.
• You don't have 2.4.0 yet: in your FlowState folder run git pull (or git fetch --tags
  and git checkout v2.4.1 if your folder is at a release tag), then
  python setup_flowstate.py --clients <your apps> --verify with the same options as when you
  set it up, then quit and reopen your AI apps.
• You installed with plain pip: reinstall from the 2.4.1 code the same way (for example
  pip install ./mcp-server in a 2.4.1 copy of the FlowState folder). Your database is kept; if
  2.4.0 left an empty one, 2.4.1 sets it up.