---
title: Star Flow
description: Product and technical spec for Star Flow, GitHub Flow for everyday people: a free, zero-setup web app where anyone writes with Claude through a review-and-approve loop, starting with one flavor for writers.
date: 2026-09-24
lang: en-US
author: Julien Béranger
model: Claude Opus 5.5
source: https://julienberanger.com/star-flow
---

# Star Flow

> **GitHub Flow for everyday people.**

## The idea

The [GitHub Flow](https://julienberanger.com/github-workflow) 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](https://code.claude.com/docs) 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](https://code.visualstudio.com/), [Git](https://git-scm.com/), [GitHub](https://github.com/), 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**.

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

## The vocabulary

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

| Under the hood | Writers flavor | What the user sees |
| --- | --- | --- |
| Repository | Project | "My story" |
| `main` | The published version | The clean text on the *Read* tab |
| Issue | Idea | A card: "Add a twist in the second act" |
| Branch | Draft | "Working on: Add a twist…" |
| Unstaged chunk | Suggestion | A highlighted redline in the text |
| `git add` (stage) | Keep | Green button on each suggestion |
| Rejection | Change it | A small box to say what to change |
| Commit | Saved step | A dot on the timeline |
| Pull request | Ready to read | A summary of the draft before publishing |
| CI checks | Proofreading | Spelling, style and consistency checks |
| Squash merge | Publish | The draft becomes the published version |
| Git log | Story of the story | A timeline: why each change happened |

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

```mermaid
sequenceDiagram
    actor U as User
    participant G as Genji UI
    participant C as Control plane
    participant W as Worker container
    U->>G: "A story about a lighthouse keeper"
    G->>C: create idea
    C->>W: start task
    W-->>G: Idea card (restated)
    U->>G: Go
    W-->>G: Suggestion 1 (redline, streamed)
    U->>G: Keep
    G->>C: approve
    C->>W: stage + commit
    W-->>G: Saved step, Suggestion 2
    U->>G: Publish
    C->>W: proofread + merge
```

## Architecture

Three pieces, each with one job.

### 1. Frontend: Genji

[Genji](https://github.com/w3hc/genji) is the UI template: [Next.js](https://nextjs.org/), [Chakra UI](https://chakra-ui.com/), [w3pk](https://w3pk.w3hc.org/) passkey authentication and [WCAG 2.1 AA](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.1&levels=aa) accessibility, which matters for the public-sector and regulated flavors later. The Web3 parts ([Ethers](https://docs.ethers.org/)) 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](https://en.wikipedia.org/wiki/Markdown) as word-level track changes, built on [TipTap](https://tiptap.dev/) (itself based on [ProseMirror](https://prosemirror.net/)). Progress is received through [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/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](https://nestjs.com/) 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](https://docs.github.com/en/apps) 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](https://docs.nestjs.com/techniques/server-sent-events).
- **Guardrails.** Rate limits, per-session budgets and bot protection (see *Keeping it free*).

```ts
@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](https://code.claude.com/docs/en/agent-sdk/hosting) for TypeScript, which ships its own Claude Code binary and runs it as a subprocess;
- the flavor's `CLAUDE.md` and [skills](https://code.claude.com/docs/en/skills);
- a small NestJS worker, using the [Fastify adapter](https://docs.nestjs.com/techniques/performance) to reduce boot time and memory.

```dockerfile
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:

| Endpoint | Purpose |
| --- | --- |
| `POST /ideas` | Start a task from the user's request; returns the restated Idea |
| `POST /ideas/:id/go` | Confirm the Idea; creates the branch and starts writing |
| `GET /events` | Stream of suggestions, saved steps, check results |
| `GET /diff` | Current unstaged changes, for the redline view |
| `POST /keep` | Stage the given files or hunks, run checks, commit, push |
| `POST /change` | Reject a suggestion with the user's feedback |
| `POST /publish` | Open the pull request, run proofreading, squash-merge |

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

| Option | Why | Trade-off |
| --- | --- | --- |
| [Hono](https://hono.dev/) | Tiny, fast cold starts, no runtime dependencies, built-in SSE | Fewer batteries included |
| [Fastify](https://fastify.dev/) | Fast, mature, schema validation | Slightly more setup than Hono |
| [Express](https://expressjs.com/) | Universally known | Slower, weaker TypeScript |
| [FastAPI](https://fastapi.tiangolo.com/) | If the Python Agent SDK is preferred | Second language in the stack |
| Queue pattern | Containers pull jobs and push events through a queue, exposing no ports | One more piece of infrastructure |
| [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) | Anthropic hosts the agent and the sandbox; no worker at all | Less control over the environment |

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](https://e2b.dev/), [Modal](https://modal.com/), [Daytona](https://www.daytona.io/) or [Fly Machines](https://fly.io/docs/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](https://en.wikipedia.org/wiki/Prompt_injection)).

- One container per workspace, never shared between users; stronger isolation with [gVisor](https://gvisor.dev/) or [Firecracker](https://firecracker-microvm.github.io/) 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](https://julienberanger.com/github-workflow): 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](https://vale.sh/) 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](https://pandoc.org/) 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](https://www.anthropic.com/claude/sonnet) 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](https://www.cloudflare.com/products/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.

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

## 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).

## Further reading

- [Introduction to the GitHub Flow](https://julienberanger.com/github-workflow), the workflow Star Flow is built on
- [GitHub flow, GitHub documentation](https://docs.github.com/en/get-started/using-github/github-flow)
- [Hosting the Agent SDK](https://code.claude.com/docs/en/agent-sdk/hosting)
- [CLAUDE.md and memory in Claude Code](https://code.claude.com/docs/en/memory)
- [Genji](https://github.com/w3hc/genji), the UI template