Star Flow

GitHub Flow for everyday people.

The idea

The GitHub Flow is one of the best ways ever invented to work on something together: every change has a reason, every change is reviewed by someone who didn't write it, nothing reaches the official version without approval, and the whole history can be replayed. Paired with Claude Code and a stage-then-commit loop, it becomes a very pleasant way to work with an AI: Claude proposes, the human approves, Claude records.

The problem is the packaging. VS Code, Git, GitHub, terminals and branches scare most people outside software.

Star Flow keeps the flow and removes the packaging. Under the hood it is the exact same loop: issues, branches, chunks, staging, commits, pull requests, checks, merges. On screen, the user only sees plain words and a few buttons, in the vocabulary of their own trade. Each trade gets its own flavor.

One promise sits under everything: your work is safe, whatever happens. A Star Flow project is an ordinary Git repository that can live in a folder on your own machine, open in VS Code, and keep working with Claude Code even if Star Flow shuts down completely (see Local folder bridge and VS Code compatibility).

Version 1 in one sentence

A free web app where anyone lands on the page, types what they want to write, and is writing with Claude within seconds: no account, no install, no setup.

Goals

• Seamless. From landing to first suggestion in under 30 seconds. No signup wall, no email, no credit card, no tutorial.
• Fun. The loop should feel like a game: Claude suggests, you keep or change, and your piece grows.
• One flavor, done well. Version 1 ships a single flavor, Writers, to prove the loop before generalizing.
• Real Git underneath. Every kept suggestion is a real commit, so the history is genuine and exportable later.

Non-goals for version 1

• Multiple flavors, teams, or real-time collaboration between several humans.
• Uploading existing documents (.docx, PDF).
• Paid plans, billing, or bring-your-own GitHub account.
• Any persistence design beyond what Git already provides (the database question is deliberately deferred).

Why Writers as the first flavor

The long-term targets are trades with a real need for review and traceability: legal, quality management, regulated documentation. But a free, anonymous version 1 is the wrong place for confidential client documents. Writing (short stories, blog posts, letters, speeches) is low-stakes, universally understood, fun to demo, and exercises every step of the flow. It proves the loop; regulated flavors come later with accounts and stronger guarantees.

One caveat: casual writing is also where Star Flow faces the most direct competition, since a plain chat with an assistant is faster for a one-off piece. Within the Writers flavor, the standout uses are the ones where the timeline is the product rather than a bonus: students writing under AI-use policies, and authors who must disclose how AI was involved (see Where Star Flow earns its place).

Where Star Flow earns its place

Star Flow's advantages are narrow but strong. Every change has a stated reason, AI text only gets in paragraph by paragraph with human approval, checks can block publishing, the history can be replayed, the project is portable Git, and with the governance layer a community can adopt a verifiable version. So the best fits are texts that someone will later audit, contest or amend, not texts that just need to get written. The question for each case below is: why would someone pick Star Flow over Google Docs, Microsoft Word track changes, a plain Claude chat, or GitHub itself?

When the history of AI use and approval is the point

• Student writing under AI-use policies. A teacher replays the timeline and sees what Claude proposed, what the student kept and what they asked to change: grading the process rather than guessing at the product.
• Contests, publishers or journals that require AI disclosure. The timeline is a ready-made disclosure record, which a chat transcript or a shared document can't provide cleanly.
• Ghostwriting where the subject must approve every line. Memoirs, family histories, executives' op-eds, speeches: the approve-each-paragraph loop matches how sign-off actually works.
• Teaching writing itself. "Change it: make it sadder" followed by the revision is a tight feedback loop, and the story of the story shows how a piece evolves.

When document control is a real requirement (later, regulated flavors)

• Quality management documents (ISO 9001 procedures, standard operating procedures). Versioning, approval before release and a reason for each change are literally what auditors ask for. Probably the strongest commercial fit.
• Internal policies and employee handbooks. "Why did the remote-work clause change in March?" is answered by the timeline instead of someone's memory.
• Terms of service and privacy policies for small companies. Publish a readable diff of what changed for users, instead of a hand-written summary.
• Regulated marketing copy (financial promotions, health or cosmetic claims). Vale rules encode banned phrasings, so a red check blocks Publish: a compliance reviewer that never gets tired.
• Plain-language public-sector documents. Readability and style checks gate publishing, and the accessible UI matters for that audience.
• Runbooks and procedures for non-developer teams. Operations, facilities, labs, restaurants: Git-grade history without touching Git.

When a community owns the text (governance layer)

• Association statutes and bylaws. Amendments are diffs voted by members; in France, the associations loi 1901.
• Condominium rules (règlement de copropriété) and housing co-op charters: a known membership, formal votes, and later disputes about what exactly was adopted.
• Party platforms, union demands, manifestos written by members. A frozen, hash-verified edition ends "that's not the version we voted on".
• Family business charters. Long-lived, emotionally loaded, amended across generations; the history of why matters as much as the text.
• Codes of conduct for online communities (Discord servers, open-source projects, clubs), amended by member vote.
• Participatory public documents from citizens' assemblies, participatory budgeting or local charters, where citizens propose and adopt changes.
• Collaborative fiction with a reader-voted canon, and shared worldbuilding bibles for tabletop role-playing groups or fan communities.

When portability and no lock-in matter

• Long-lived personal projects that outlast apps, like a novel written over five years or a family recipe book: plain Markdown and full history in a local folder beat any service that might disappear.
• Mixed teams where some people code and some don't, such as open standards or documentation where engineers use VS Code and domain experts use the web UI, on the same repository.

Where it loses, honestly

• Quick one-off writing (an email, a bio, a cover letter): a plain Claude chat is faster, and approving paragraph by paragraph is overhead.
• Several people writing at the same moment: Google Docs wins at real-time co-editing.
• Contract negotiation with an outside party: the other side lives in Word redlines, so the history splits across two systems.
• Heavily formatted documents (layout, tables, brochures): Markdown is the ceiling until the Pandoc export exists.
• Developers: they should use Claude Code directly; Star Flow is their own tool with training wheels.
• Confidential material in version 1, ruled out until accounts and stronger guarantees exist.

The vocabulary

The user never sees a Git term. The Writers flavor maps them like this:

The user journey

1. Land. The home page has one big input: "What do you want to write today?", plus three starters (A short story, A blog post, A letter). A project is created silently in the background while the user types.
2. Say what you want. The user types "a short story about a lighthouse keeper who collects lost messages". Claude restates it as an Idea card ("Here's what I understood…") with a single Go button. This is the task-confirmation step from the original CLAUDE.md.
3. Write together. Claude writes the first Suggestion (one paragraph or scene) and stops. It appears as a redline. The user clicks Keep, or Change it with a few words ("make it sadder"). While the user reads, Claude is already drafting the next suggestion.
4. Grow the piece. Each kept suggestion becomes a Saved step on the timeline. The user can add new ideas at any time ("Add a storm scene"), each becoming its own Idea and Draft.
5. Publish. When a draft is done, Ready to read shows the full changes and runs Proofreading. One click on Publish merges it into the published version.
6. Share and keep. The published piece gets a clean shareable page. A gentle prompt offers to keep this project with a passkey (no password, no email). Without it, the project stays available on this device for a limited time.

Architecture

Three pieces, each with one job.

1. Frontend: Genji

Genji is the UI template: Next.js, Chakra UI, w3pk passkey authentication and WCAG 2.1 AA accessibility, which matters for the public-sector and regulated flavors later. The Web3 parts (Ethers) are removed for version 1.

Main screens:

• Home: the input and the three starters.
• Write: the text with inline redlines, Keep / Change it buttons on each suggestion, and a side panel with the current Idea.
• Timeline: the story of the story (ideas, saved steps, publishes).
• Read: the published version, clean, shareable.

The redline view is the heart of the product. It renders Git diffs of Markdown as word-level track changes, built on TipTap (itself based on ProseMirror). Progress is received through server-sent events with a plain EventSource.

Genji only ever talks to the control plane. It never reaches a container directly.

2. Control plane: NestJS

A NestJS service that owns everything outside the agent:

• Sessions. Anonymous sessions on first visit (signed cookie), upgraded to passkey-backed accounts when the user chooses to keep a project.
• Workspaces. Maps a session to its workspace and its container, starts containers on demand, stops them when idle.
• GitHub. Acts as a GitHub App installed on a dedicated Star Flow organization, creates one private repository per project, and mints short-lived installation tokens scoped to a single repository for each container.
• Relay. Forwards user actions (go, keep, change it, publish) to the right container and relays the container's event stream to Genji with NestJS's SSE support.
• Guardrails. Rate limits, per-session budgets and bot protection (see Keeping it free).

@Sse('workspaces/:id/events')
@UseGuards(SessionGuard)
events(@Param('id') id: string): Observable<MessageEvent> {
  return this.workspaces.streamFromContainer(id);
}

3. Workers: one NestJS container per workspace

Each active project runs in its own disposable container holding:

• the project's Git repository, cloned into /workspace;
• the Claude Agent SDK for TypeScript, which ships its own Claude Code binary and runs it as a subprocess;
• the flavor's CLAUDE.md and skills;
• a small NestJS worker, using the Fastify adapter to reduce boot time and memory.

FROM node:22-slim
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
RUN useradd -m agent
WORKDIR /app
COPY worker/ .
RUN corepack enable && pnpm i --prod
COPY flavors/ /flavors/
USER agent
CMD ["node", "dist/main.js"]

Worker endpoints, reachable only from the control plane on a private network:

The stage-then-commit loop gets simpler here. In the local setup, Claude polls git status with a background loop because it can't know when the human has staged in VS Code. In Star Flow, the worker receives the Keep click directly: it runs git add itself, then resumes the agent with "suggestion kept, run checks and commit". No polling, no missed approvals.

Other options for the worker

NestJS is chosen for consistency with the control plane: one framework, one set of conventions, shared types. The trade-off is a slower cold start and more dependencies than the job strictly needs. Alternatives, if that becomes a problem:

The worker's logic (keep, change, publish) stays the same whichever transport is used, so switching later is cheap.

Container lifecycle

• Start when a user opens or creates a project. A small pool of pre-warmed containers keeps the landing experience instant.
• Stop after about 15 minutes of inactivity.
• No precious state inside. Every kept suggestion is committed and pushed immediately, so Git is the source of truth and losing a container costs nothing. The Agent SDK session file is saved alongside so a conversation can resume.
• Hosting. A sandbox provider with an API to start and stop containers: E2B, Modal, Daytona or Fly Machines. Kubernetes is not needed for version 1.

Security

Anonymous users can type anything, so every piece of user text is treated as data, never as instructions (see prompt injection).

• One container per workspace, never shared between users; stronger isolation with gVisor or Firecracker where the provider supports it.
• The Anthropic API key never enters a container: an egress proxy injects it into outgoing requests.
• GitHub tokens are short-lived and scoped to one repository.
• Outbound network limited to GitHub and the proxy; non-root user; CPU, memory and disk limits.

The Writers flavor

A flavor is a folder: a CLAUDE.md, a few skills, a vocabulary file for the UI, and a check pipeline.

CLAUDE.md, adapted from the original: keep task confirmation, the issue → branch → chunks → pull request → merge sequence and the stage-then-commit rule; drop the developer tooling (pnpm, Foundry, rickub, changelog). Writing-specific rules:

• one suggestion = one paragraph or one short scene, small enough to read in a few seconds;
• match the language the user writes in;
• never rewrite text the user already kept unless asked;
• commit messages in plain words, since they appear on the timeline ("add the storm scene").

Skills:

• restate-idea: turn a vague request into a clear Idea card with a title and what "done" looks like;
• proofread: summarize the checks' findings in friendly language;
• title-and-blurb: propose a title and a one-line summary at publish time.

Checks (the Proofreading step): Vale for style and spelling rules, plus a Markdown lint. They run at publish time, like CI on a pull request; a red check blocks Publish and shows what to fix.

Export (later): Pandoc to produce .docx, PDF or EPUB from the published Markdown.

Keeping it free

Every suggestion costs tokens, paid by Star Flow. Version 1 stays free with a few guardrails:

• Model. A fast, affordable model such as Claude Sonnet 5 for writing, and a smaller model for restating ideas and summarizing checks.
• Budgets. A per-session budget of suggestions per day, shown playfully ("12 suggestions left today") rather than as an error.
• Bot protection. An invisible challenge such as Cloudflare Turnstile before the first suggestion, instead of a signup wall.
• Idle shutdown. Containers stop quickly; tokens, not containers, are the dominant cost, but there's no reason to pay for idle ones.
• Short projects. Anonymous projects expire after a set period unless kept with a passkey.

Governance layer

After version 1. Aimed at flavors where a community, not just the authors, owns the text: association statutes and bylaws, co-op charters, open standards, participatory public documents, or a collaborative story whose readers decide the canon.

The review loop decides what gets written; the governance layer decides what gets published. It is built on Gov, a minimalist onchain voting system based on OpenZeppelin Governor: one member, one vote, non-transferable membership NFTs, simple majority, configurable voting period and quorum. Gov shares Star Flow's motivation: a coordination tool for everyday people.

A candidate branch between drafts and main

On a governed project, pull requests no longer merge into main. They merge into a candidate branch, which accumulates accepted work until the team decides it is ready to go to a vote.

1. The team works exactly as before: ideas, drafts, keep, saved steps, pull requests, proofreading. Squash merges land on candidate.
2. When candidate is ready, someone clicks Put it to a vote. The control plane freezes it as a tag (candidate/v3) and opens a Gov proposal about that exact commit.
3. Members read the frozen version and its changes since the last edition, then vote For, Against or Abstain.
4. If the proposal passes and is executed, main is fast-forwarded to the voted commit. If it fails, candidate stays as it is and the team keeps working.

Members vote on a commit hash, never on a moving branch. Pull requests merged into candidate while a vote is open are part of the next candidate, like release trains.

The vote writes the commit onchain

A Gov proposal can execute arbitrary contract calls. The proposal's only call is to a tiny registry contract that records which commit each project has adopted:

// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.8.28;

contract Editions {
    address public immutable gov;
    mapping(bytes32 projectId => bytes20 commit) public adopted;

    event Adopted(bytes32 indexed projectId, bytes20 commit, string tag);

    constructor(address gov_) {
        gov = gov_;
    }

    function adopt(bytes32 projectId, bytes20 commit, string calldata tag) external {
        require(msg.sender == gov, "only gov");
        adopted[projectId] = commit;
        emit Adopted(projectId, commit, tag);
    }
}

The control plane listens for Adopted events and fast-forwards main to that commit; branch protection forbids any other way in. main becomes a verifiable mirror of what the community approved: anyone can check that the published text matches the hash that was voted on, without trusting Star Flow. For regulated flavors, that audit trail is a selling point in its own right.

Who votes: the operator

Membership is where Sybil resistance lives. Gov's operator role lets a designated address onboard members without a vote, so the team decides who can vote and nobody can spin up a thousand passkeys to swing a result. That fits communities with a known membership: an association's registered members, a co-op's members, a book's subscribed readers.

The operator moves trust rather than removing it: until it expires, it can mint any number of memberships. So:

• The team holds the operator, not Star Flow. Ideally a multisig of the team's passkey-backed accounts. If Star Flow's control plane held it, Star Flow would be the trust assumption for every project on the platform.
• Every mint is public. Membership is enumerable onchain, so a burst of new members just before a vote is visible to everyone.
• The operator expires. The team bootstraps the community, then the role lapses and only a governance vote can add or remove members. The community then controls its own growth.
• Late members don't vote. Voting power is snapshotted when a proposal opens (a Governor mechanism; to confirm in Gov's tests), so memberships minted during a vote don't count on it.

This makes governed publishing permissioned and transparent, which is the honest claim. It becomes genuine outside approval once the operator has expired or is held by people other than the authors.

Keeping it everyday

• No wallet on screen. Members sign in with a passkey through w3pk, which Genji already ships; the Web3 parts removed for version 1 come back for governed projects only.
• No gas for voters. Deploy on an Ethereum layer 2 and sponsor transactions, for example through account abstraction.
• A separate tempo. The writing loop runs in seconds; a vote runs in days. Governance sits above the loop, never inside it, and the UI says so ("The vote closes Friday. Keep writing: your changes go into the next edition").
• One deployment per project. Each governed project gets its own Gov instance and manifesto, so communities never share voters.

Vocabulary

Local folder bridge

Kept projects only. The goal: the user picks one folder on their computer, and that folder always holds the full project, including its complete history, as a plain Git repository.

The browser API

Next.js pages run in the browser, so the bridge uses the File System Access API. window.showDirectoryPicker() asks the user to choose a folder and returns a handle the page can read and write, with the user's explicit permission. The handle can be stored in IndexedDB, so the app remembers the folder across visits and only needs a click to reconnect it.

'use client';

import { get, set } from 'idb-keyval';

export async function connectFolder(projectId: string) {
  const dir = await window.showDirectoryPicker({ id: `starflow-${projectId}`, mode: 'readwrite' });
  await set(`folder:${projectId}`, dir); // handles survive in IndexedDB
  return dir;
}

// Must run inside a click handler: permission prompts need a user gesture.
export async function reconnectFolder(projectId: string) {
  const dir = await get<FileSystemDirectoryHandle>(`folder:${projectId}`);
  if (!dir) return null;
  const opts = { mode: 'readwrite' } as const;
  if ((await dir.queryPermission(opts)) === 'granted') return dir;
  return (await dir.requestPermission(opts)) === 'granted' ? dir : null;
}

The component is a client component ('use client'), and the feature is detected with 'showDirectoryPicker' in window before showing the Save to my computer button.

Real Git in the folder

Copying text files is not enough: the promise is the history. The browser runs isomorphic-git, a pure JavaScript Git implementation, on top of a thin adapter that maps its fs interface (readFile, writeFile, mkdir, readdir, stat…) to the directory handle. The folder then holds a genuine .git directory, and any Git tool, including VS Code, sees an ordinary clone.

• Clone. On first connection, the browser clones the project into the empty folder.
• Follow along. Each Saved step event on the SSE stream triggers a fetch and fast-forward, so the folder is never more than a few seconds behind.
• Credentials stay on the server. GitHub's Git endpoints don't allow cross-origin requests from a web page, so the browser talks Git over HTTPS to a small proxy route on the control plane. The proxy injects the repository-scoped installation token; the browser never holds a GitHub credential.
• Changes made on the computer. If the user edits a file in the folder with another app, the next check (on window focus, or a periodic statusMatrix) finds the difference and shows it as Changes from your computer, with the usual Keep / Change it. Kept changes are committed on a draft branch and pushed like any other saved step. The experimental FileSystemObserver can replace polling where available.

What goes in the folder

my-story/
├── .git/                      # full history
├── story.md                   # the text itself
├── CLAUDE.md                  # the flavor's rules for Claude
├── .claude/skills/            # restate-idea, proofread, title-and-blurb
├── .vale.ini + styles/        # proofreading rules
├── .github/workflows/         # the same checks, run by GitHub Actions
└── .starflow/flavor.json      # vocabulary for the UI

Everything Star Flow needs to run the loop is in the folder, which is exactly what makes the next section possible.

Limits and fallbacks

• Browser support. showDirectoryPicker is available in Chromium browsers (Chrome, Edge, Opera and others) on desktop, not in Firefox or Safari, and not on mobile (current support). Other browsers get Download my project: a zip of the working files plus a Git bundle, which is the whole history in a single file that git clone accepts.
• Offline companion (optional). For users who want continuous sync outside Chromium, a tiny command, npx starflow sync, or a small desktop wrapper such as Tauri can do the same job with the real Git binary.
• Safety. The app asks for one dedicated folder, suggests creating an empty one, and never asks for more; browsers already refuse sensitive locations such as the home directory root or system folders.

VS Code compatibility

A whole team, or a single member, can leave the web UI at any time and continue in VS Code with Claude Code, on the same project, without converting anything.

Same repository, same rules

This works because Star Flow never hides a proprietary format behind the vocabulary. The repository is the project:

• CLAUDE.md and skills are in the repository, not only in the worker image. Claude Code in VS Code reads the same rules and skills as the worker, so it behaves the same way: task confirmation, one paragraph per suggestion, plain-words commit messages.
• Ideas are real GitHub Issues, drafts are real branches, "Ready to read" is a real pull request. The web UI is a view on them, not a copy.
• Branch names follow the original workflow (<issue-number>-short-slug), so a draft started in the browser can be continued in VS Code and the other way round.
• Proofreading runs in GitHub Actions, not only in the worker, so a pull request opened from VS Code gets the same checks and the same red or green result.
• Branch protection is the rulebook. main (and candidate on governed projects) can only change through a reviewed pull request with passing checks, whichever tool opened it.

In VS Code, the loop is the one from the original workflow: Claude writes a chunk, the member stages it in the Source Control panel, Claude notices and commits. Same history, same timeline.

Mixed teams

The control plane subscribes to the repository's webhooks, so a commit pushed from VS Code appears on the web timeline within seconds, labelled with its author. Two rules avoid collisions:

• One owner per draft. Starting a draft assigns the Idea's issue to its owner; the web UI shows "Marie is working on this in VS Code" and doesn't let Claude write on that branch meanwhile.
• Short drafts, frequent publishes. Squash merges and small drafts keep conflicts rare; when one happens, the web UI offers Let Claude reconcile as a normal suggestion to review.

Access for VS Code users goes through GitHub: a member links a GitHub account to their passkey-backed Star Flow account, and the GitHub App adds them to the repository as a collaborator. This lifts the version 1 non-goal "bring-your-own GitHub account" for kept projects only.

If Star Flow shuts down

This is the point of the last two sections: your work is safe, whatever happens.

• The folder on your computer holds every word and the complete history, as a standard Git repository.
• The GitHub repository can be transferred to your own account at any time with Take my project with me; an export of issues and pull requests goes along.
• Claude Code keeps working on the folder, because the rules and skills live in it: VS Code plus Claude Code is Star Flow without the packaging.
• The checks keep running in GitHub Actions.
• Governed projects keep their governance. The Gov contract and the Editions registry live onchain and don't depend on Star Flow; only the automatic fast-forward of main would need to be done by hand (or by a small GitHub Action listening for Adopted events).

Star Flow adds comfort, never lock-in.

Milestones

1. The loop, locally. One worker container running on a laptop, driven by a bare page: idea → go → suggestion → keep → commit. Proves the Agent SDK integration and the keep-then-commit mechanics.
2. The redline view. Word-level track changes on Markdown diffs in Genji, with Keep and Change it.
3. The control plane. NestJS with anonymous sessions, GitHub App, container start/stop on a sandbox provider, SSE relay.
4. Publish. Pull request, proofreading checks, squash merge, shareable read page, timeline.
5. Free and safe. Budgets, bot protection, egress proxy, pre-warmed pool, passkey "keep this project".
6. Five real users. Watch people who have never heard of Git use it, and fix what confuses them.

After version 1:

1. Local folder bridge. File System Access API, isomorphic-git through the control plane proxy, Git bundle download as fallback.
2. VS Code compatibility. Flavor files and GitHub Actions checks in every repository, webhooks to the timeline, draft ownership, "Take my project with me".
3. Governance layer. candidate branch, Editions registry, one Gov deployment per governed project, gasless passkey voting.

Open questions

• Storage and database. Deliberately deferred. Git covers the content; sessions, budgets and project ownership will need a home in the control plane.
• GitHub at scale. Many anonymous private repositories under one organization: check GitHub's terms and API rate limits, or consider a self-hosted Git server for anonymous projects and GitHub only for kept ones.
• Terms of use. Anthropic's usage policies and commercial terms for a free public product built on the API.
• The second flavor. Which trade to tackle once the loop is proven, and what it needs that Writers doesn't (document upload, accounts, audit exports).
• Claude in VS Code. Members working in VS Code use their own Claude Code subscription or API key; decide whether Star Flow ever provides one.
• Which chain. Pick the layer 2 for governed projects (cost, longevity, legal comfort for associations and public bodies), and confirm Gov's voting snapshot behavior in its tests.
• Firefox and Safari. Watch the File System Access API; until then, the Git bundle download and the companion command cover those users.

Further reading

• Introduction to the GitHub Flow, the workflow Star Flow is built on
• GitHub flow, GitHub documentation
• Hosting the Agent SDK
• CLAUDE.md and memory in Claude Code
• Genji, the UI template
• Gov, the onchain voting system behind the governance layer
• OpenZeppelin Governor
• File System API, MDN
• isomorphic-git
• Patchwork, Ink & Switch's research on version control for writers