FlumeCodeFlumeCode(Preview)Sign in

FlumeCode Guide

A quick tour of the concepts behind FlumeCode — from your first request to a merged pull request.

Core workflow

Step 1

Request

A request is how you describe the change you want. It can be a one-line idea ("add a dark-mode toggle") or a detailed spec — the agent reads your actual code and issues, so it works from the real thing, not a guess. The goal of the request step is to turn that idea into a concrete plan the agent can implement — you and the agent refine it together before any code is written.

  1. Maya Chen@maya

    Add a dark-mode toggle to the nav bar. The user's choice should persist across reloads. Keep it simple — no external theming library needed.

  2. FlumeCode agent

    A couple of questions before I plan:

    Where should the toggle live?

    Answered

    Which surfaces need dark-mode tokens?

    Answered

  3. FlumeCode agentplan

    Implementation plan

    Context — The nav bar has no way to switch themes; add a persistent toggle with no external theming library.

    1. Create src/components/ThemeToggle.tsx — a button with a sun/moon icon that flips between light/dark.
    2. Add a useTheme hook that reads localStorage on mount, falls back to prefers-color-scheme, and writes data-theme on <html>.
    3. Add [data-theme="dark"] token overrides in src/styles/tokens.css.
    4. Mount <ThemeToggle /> in the existing <Nav> (src/components/Nav.tsx).
    5. Set data-theme from an inline head script before hydration to avoid a flash of the wrong theme.

    Acceptance criteria

    • A sun/moon toggle is visible in the nav bar and switches the theme on click.
    • The preference persists across reloads and new tabs.
    • First paint matches the stored theme — no flash of light mode.
    Open a coding session →
Example: a request
Step 2

Coding session

Agents work on one plan per coding session. Their work lives in a session. A single request can fan out into many sessions, each opening its own pull request. You can follow every session in real time or pick up the report when it is done.

  • Add a dark-mode toggle to the nav bar

    request #12

  • Add dark-mode toggle to nav bar #31

    Maya Chen@maya

  • Add E2E test for theme persistence #32

    Maya Chen@maya
Example: coding sessions from one request
  1. FlumeCode agentplan

    Add E2E test for theme persistence

    1. Add a Playwright E2E spec theme-persistence.spec.ts.
    2. Toggle dark mode via the nav ThemeToggle, reload the page, and assert data-theme=\"dark\" is restored.
    3. Assert the toggle reflects the persisted preference on load.
    4. Wire the spec into the CI test job.

    Acceptance criteria

    • Reloading after enabling dark mode keeps the dark theme.
    • The E2E spec passes locally and in CI.
Example: a coding session
Step 3

Review

When a session finishes, the agent writes an easy-to-understand report — a plain-language summary of what changed and why, mapped to each acceptance criterion. You can discuss the results right in the thread and, if something is off, ask the agent to re-implement.

  1. FlumeCode agentplan

    Implementation plan

    Context — The nav bar has no way to switch themes; add a persistent toggle with no external theming library.

    1. Create src/components/ThemeToggle.tsx — a button with a sun/moon icon that flips between light/dark.
    2. Add a useTheme hook that reads localStorage on mount, falls back to prefers-color-scheme, and writes data-theme on <html>.
    3. Add [data-theme="dark"] token overrides in src/styles/tokens.css.
    4. Mount <ThemeToggle /> in the existing <Nav> (src/components/Nav.tsx).
    5. Set data-theme from an inline head script before hydration to avoid a flash of the wrong theme.

    Acceptance criteria

    • A sun/moon toggle is visible in the nav bar and switches the theme on click.
    • The preference persists across reloads and new tabs.
    • First paint matches the stored theme — no flash of light mode.
  2. FlumeCode agentreport

    Added a dark-mode toggle to the top navigation bar. The preference is persisted in localStorage and applied via a `data-theme` attribute on `<html>`.

    Files changed

    • src/components/ThemeToggle.tsx (new)
    • src/components/Nav.tsx (modified)
    • src/styles/tokens.css (modified)

    Acceptance criteria

    • ✓ metA toggle is visible in the nav bar

      ThemeToggle renders as a button inside Nav with a sun/moon icon.

      src/components/Nav.tsx

      ThemeToggle imported and placed in the nav.

      @@ -12,6 +12,7 @@
+import { ThemeToggle } from './ThemeToggle';
 ...
+<ThemeToggle />
    • ✓ metPreference persists across page reloads

      The hook reads and writes to localStorage on mount and on toggle.

      src/components/ThemeToggle.tsx
      @@ -0,0 +1,22 @@
+const stored = localStorage.getItem('theme');
+document.documentElement.dataset.theme = stored ?? 'light';

    Code quality

    Clean implementation. The toggle is self-contained and the CSS token approach means no component-level style overrides are needed.

    Caveats / follow-ups

    None.

Example: an agent report

Set up

You need to add two things to use FlumeCode: agents and runners. Agents run their tasks on your runners. Runners are your own devices — your laptop or any machine you control — and they give the agents the compute and AI-service access they need to work.

Agent

The agent is the AI model that does the work inside a session. It reads your code, writes changes, runs commands, and reports back with a structured summary of every decision it made — so you always know why the code looks the way it does.

AnthropicClaude models (Opus, Sonnet, Haiku)
OpenAI CodexOpenAI Codex via your local codex CLI login

No API key needed — this agent runs on your machine through a runner using your own Claude Code login.

Example: adding an agent

Runners

Runners are the machines that execute the agent's jobs — your own laptop, a dedicated server, or any box you control. Jobs queue up and the runner picks them up automatically. You can watch which runners are connected and whether Claude Code is ready on each one.

  • maya-mbpv1.2.3 · last seen 2 min ago · added Jun 8
    ConnectedClaude Code ready
  • dev-serverv1.2.3 · last seen 3 days ago · added May 22
    OfflineClaude Code unknown
Example: your runners

Utilities

Sketches

Sketches let you explore and iterate on an idea before committing it to a full request. When you are not sure exactly what you want, start with a sketch — refine the idea in conversation, then promote it into a request that drives coding sessions.

  1. Maya Chen@maya

    I'm thinking about adding a dark-mode toggle but not sure where it should live — nav bar, settings page, or a floating button? Let's sketch a few options.

  2. Sam Rivera@sam

    Love this, Maya — the nav-bar option feels right. This is solid enough to promote into a request and start a coding session.

Example: a sketch conversation

Plugins

Plugins give a repo extra capabilities wired directly into the request → coding-session flow. Enable test-coverage to get a coverage report on every session, ui-preview to screenshot UI changes before they merge, or changeset to auto-generate release notes. Each plugin activates only when relevant.

  1. FlumeCode agentreport

    Added a dark-mode toggle to the top navigation bar. The preference is persisted in localStorage and applied via a `data-theme` attribute on `<html>`.

    Files changed

    • src/components/ThemeToggle.tsx (new)
    • src/components/Nav.tsx (modified)
    • src/styles/tokens.css (modified)

    Acceptance criteria

    • ✓ metA toggle is visible in the nav bar

      ThemeToggle renders as a button inside Nav with a sun/moon icon.

      src/components/Nav.tsx

      ThemeToggle imported and placed in the nav.

      @@ -12,6 +12,7 @@
+import { ThemeToggle } from './ThemeToggle';
 ...
+<ThemeToggle />
    • ✓ metPreference persists across page reloads

      The hook reads and writes to localStorage on mount and on toggle.

      src/components/ThemeToggle.tsx
      @@ -0,0 +1,22 @@
+const stored = localStorage.getItem('theme');
+document.documentElement.dataset.theme = stored ?? 'light';

    Code quality

    Clean implementation. The toggle is self-contained and the CSS token approach means no component-level style overrides are needed.

    Caveats / follow-ups

    None.

    Plugins

    UI Preview
    desktop previewmobile preview
    Test Coverage

    All suites passing; theme toggle covered by unit + E2E tests.

    • Passed: 42
    • Failed: 0
    • Total: 42
    • Coverage: 87%
Example: a coding session report