Flow State gives you a working app with a full agentic backend already in place:
- Workers that take on tasks, and a task board they share with you.
- State and memory kept in your own stores, with output streamed to the browser as it is written.
- Models from any provider, on a direct key (OpenAI, Anthropic, Google) or through a gateway (Vercel AI Gateway, OpenRouter).
- Hand-offs to the coding agents you already use, Claude Code, Codex and Cursor, on the sign-ins you already have, including a Claude or ChatGPT subscription. Flow State coordinates those agents, so it works as a harness over them.
- Flows, the steps each worker runs, written in TypeScript you can read and edit. Use them as they are, or change them to fit how you work.
You own the code. You pick the model for each step and keep the data in systems you run. Where a step doesn't need a model, it runs as plain code.
It is open source, written in TypeScript, and runs as a web service. It is also an early preview: the starters are research software, and each one's README lists what isn't wired yet.
Today it's for developers. Where it's heading is apps that people who don't write code install and then reshape by asking the app to rewrite or reconfigure itself. That isn't here yet; flow-state.build is where it will show up.
Docs: flow-state.dev/docs.
A starter is a complete app: React pages, a team of workers, and the flows they run on. Every starter runs on the same backend packages, so what differs between them is mostly the UI and the workers' files.
- Teammates (
labs/teammates): a small team you talk to one at a time. Lead, researcher and writer each keep one long conversation, message each other where you can see it, and hand code changes to a coding agent (Claude Code, Codex or Cursor) that runs in the background. You can hire teammates of your own from the page. The teammates are listed on the left, and choosing one opens its conversation. - Claude Code-style agent (
labs/claude-code-style): one conversation driving an agent loop. The main session answers questions about your project itself and starts background tasks for the long pieces. Code changes go to a coding agent. In threads mode, where each request runs as a task in a session of its own, a run that changed files waits for you to accept it or ask for changes.
Shift Manager, an app for working a whole team's asks, tasks and workstreams, is in progress. An early version is in packages/shift-manager, where several screens are placeholders; see its docs.
The starters run from a clone of this repository. They are workspace packages that depend on the framework's source, not something you install from npm. To build your own app on one, fork this repository and work in the starter's folder (labs/<starter>). Pulling framework updates is a normal git pull from upstream.
You need Node.js 24 or newer and pnpm 12.18.0 (corepack enable && corepack prepare pnpm@12.18.0). The published packages still support Node 22 and newer; the starters, being apps, need 24.
git clone https://github.com/fixpoint-labs/flow-state-dev
cd flow-state-dev
pnpm install
pnpm build:assets # one time: builds the DevTool
pnpm --filter @flow-state-dev/teammates dev
# or
pnpm --filter @flow-state-dev/claude-code-style devEach command builds the starter's pages and serves them with its backend. Open the address it prints as App: (http://localhost:4200 by default). The DevTool: line gives the address of a browser inspector that shows every run, item and state change as it happens. It reads not served until pnpm build:assets has run.
Set keys in your shell or in a .env.local at the repository root:
| Key | Needed for |
|---|---|
One model key: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, AI_GATEWAY_API_KEY or OPENROUTER_API_KEY |
The model every worker answers on. Both starters default to OpenAI models (Teammates' helper calls always use one), so OPENAI_API_KEY or AI_GATEWAY_API_KEY works as is. For another provider, install its package at the repository root, such as pnpm add -w @ai-sdk/anthropic (or @ai-sdk/google, @openrouter/ai-sdk-provider), and change the model setting. See Setting up models and each starter's Run it section (Teammates, Claude Code-style). |
Claude Code signed in (an API key or a Claude subscription), or ANTHROPIC_API_KEY |
Coding tasks on Claude Code. The Claude Code-style starter's default coder runs on it. |
Codex signed in (codex login, with an API key or a ChatGPT sign-in), or CODEX_API_KEY |
Coding tasks on Codex. |
Cursor signed in, or CURSOR_API_KEY |
Coding tasks on Cursor. Teammates' default coder runs on it. |
TAVILY_API_KEY, EXA_API_KEY or BRAVE_API_KEY |
Optional. Teammates' researcher uses one to search the web. |
You only need the coding-agent sign-ins for the coding workers. At startup each starter logs which coding agents this machine can run and what to run for any that can't.
Both starters keep their data in a SQLite file under .fsdev/, so conversations and tasks survive a restart. By default, coding tasks work on the clone the starter runs from, so in your fork they change your fork's code. Each task runs in a git worktree on a branch of its own, and your checked-out branch and files aren't touched. Teammates takes TEAMMATES_WORKDIR to point at another checkout. The full list of settings, and a first conversation to try, is in each starter's README: Teammates, Claude Code-style.
Most of what makes a starter itself lives in plain files you can edit.
Workers are WORKER.md files. Each one sits in its own folder under the starter's workforce/teams/<team>/workers/<name>/. The frontmatter says who the worker is and what it can use; the body is its instructions. Here is Teammates' researcher, from labs/teammates/workforce/teams/teammates/workers/researcher/WORKER.md:
---
name: researcher
description: Finds facts for the team, in the working folder's files and on the web, and replies to whoever asked.
icon: "๐"
color: teal
tools: [globProjectSource, readProjectSource, grepProjectSource, search, fetch]
---
You find facts: dates, prices, what a document or the code says. Look them up, never guess: read the
working folder's files with `globProjectSource`, `grepProjectSource` and `readProjectSource`, and
search the web with `search` and `fetch`. Say where each fact came from: the file's path, or the
page's URL.description is the only required key. name is the display name, tools lists the tools it may call, and flow picks which flow it runs on. A starter's flow can accept its own settings on top: Teammates reads icon and color for the worker list, and its coding workers name a harness: (claude-code, codex or cursor). Add a folder and you've added a worker. Edit the body and its instructions change on the next start.
The team is TEAM.md. It sits at the top of the team's folder and holds what every worker on the team is told, such as which codebase they work on.
Flows are TypeScript. When a worker needs to do something the existing flows don't, write a flow of your own and point the worker at it with flow:. The Claude Code-style starter keeps its own in labs/claude-code-style/workforce/flows/. Workers can also load skills, Markdown playbooks they pull in when a task calls for one.
The UI is a React app. Each starter's pages are under its src/, built with Vite. They call the backend through typed hooks from @flow-state-dev/react, and some components come from the Flow State UI registry, copied into src/components/flow-state/ so you can edit them like any other file.
Read more:
- Workforce and Workers on disk: every
WORKER.mdandTEAM.mdkey - Flows
- Skills
- React and the UI registry
Flow State also mounts inside an existing Next.js App Router or Node project.
The quickest route is install-fsd, an install routine your coding assistant runs from your project directory. It has nothing to do with the skills workers load. It inspects the project, shows you the files it will write, then writes them. It doesn't commit, so review the result with git diff. The Quick Start builds a streaming chat with a React UI from nothing.
To wire it by hand, follow Existing project, starting with:
pnpm add @flow-state-dev/core @flow-state-dev/engine zodThe starters are built on a foundation you can use directly. You compose blocks, typed units that range from a model call to plain code, checks and routing, into flows. A flow exposes named actions, each running a block, that a client can call, and every worker runs on a flow. State and documents are typed and scoped to a session, user or org, on the store you choose. Runs are durable, so long work survives a restart and resumes where it stopped. You pick the model per block, and loops and coding runs stop at the limits you set. On the front end, a client SDK and React hooks read the same types, and the DevTool shows every run as it happens.
Everything is published under @flow-state-dev/. Install only what you use.
| Group | Packages |
|---|---|
| Core | core (blocks, flows, types), engine (runtime, stores, streaming, HTTP routes), client (API client for browsers and Node), react (hooks and renderers), contracts (shared item types, re-exported by core) |
| Workers and tasks | orchestration (task board, skills), workforce (workers and WORKER.md), workspace (a directory a worker edits files in), harness-manager (runs a task on a coding agent in its own checkout and checks the result before the task completes), shift-manager (browser app for a team) |
| Coding agents | claude-code, codex, cursor |
| Building blocks | memory, tools, patterns |
| Hosting | next, vercel, node, bullmq (durable background jobs and cron) |
| Persistence | store-sqlite, store-postgres |
| Transports | mcp, scheduled, voice-openai |
| Tooling | fsdev (the CLI), devtool, testing (harnesses and mock models) |
Concepts, guides and API reference are in the docs. For small, copy-able code, see examples/hello-chat.
For contributors to the framework.
git clone https://github.com/fixpoint-labs/flow-state-dev
cd flow-state-dev
pnpm install
pnpm packages:build # emits dist/*.d.ts so your editor resolves workspace imports
pnpm typecheck
pnpm test
pnpm lintThese should pass on a fresh clone. pnpm install also installs a pre-push hook that runs pnpm lint and the repo's naming checks, and blocks the push if any fails. See development setup.
Apps, starters and examples run against package source, so a package edit shows up in a running app without a rebuild.
packages/ published packages
apps/ docs site, DevTool source, kitchen-sink, and other maintained apps
labs/ the starters and other experimental apps
examples/ small, copy-able examples
plugins/ the flow-state-dev plugin, including the install-fsd skill
docs/ architecture reference and contributor guides
Where to read next:
CONTRIBUTING.md: how to submit a changeAGENTS.md: the working protocol and code style, for people and coding agentsdocs/philosophy.md: the principles behind design decisionsdocs/architecture/overview.md: packages and how a request flows through themdocs/contributing/best-practices.md: implementation standards
Please read the Code of Conduct. To report a vulnerability, follow SECURITY.md.
We're grateful to the sponsors who support the development of @flow-state-dev.
Neon: serverless Postgres with branching, autoscaling, and scale-to-zero.
MIT. See LICENSE for details. Copyright (c) 2026 Fixpoint Labs.