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.

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:

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.

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

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, 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