Skip to content

About

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

15,001 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Flow State

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.

Starters

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.

Run a starter

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 dev

Each 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.

Make it yours

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:

Add it to an app you already have

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 zod

Underneath

The 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.

Developing Flow State itself

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 lint

These 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:

Please read the Code of Conduct. To report a vulnerability, follow SECURITY.md.

Sponsors

We're grateful to the sponsors who support the development of @flow-state-dev.

Neon

Neon: serverless Postgres with branching, autoscaling, and scale-to-zero.

License

MIT. See LICENSE for details. Copyright (c) 2026 Fixpoint Labs.

About

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages