Flux

You could write a shell script. Here's why you won't.

A script that runs claude -p with a prompt is fifteen lines. A script that also reads exported design tokens, validates them against your codebase, catches field name mismatches between your mock data and your real API, opens a branch, commits with a useful message, and gives the next teammate a folder they recognise — is not.

Flux is that not-fifteen-lines, plus a convention (handoff/PROMPT.md) that travels across teams, repos, and tools you haven't picked yet.

handoff/ is the standard. Flux is one implementation.

Any repository can adopt the handoff/ convention without installing Flux:

handoff/
├── PROMPT.md       # natural-language intent + acceptance criteria
├── tokens.json     # design tokens (optional)
├── screens/        # PNG exports (optional)
└── components/     # exported component code (optional)

PROMPT.md is the file. Like Dockerfile, Makefile, or package.json, it's a name that travels. A designer who drops one in a repo communicates intent to every human, agent, and tool downstream. Flux just happens to be the fastest way to execute one.

Who this is for

• You ship React, Next.js, Svelte, or Vue. Backend-only repos won't feel it.
• You already pay for Claude (Pro, Team, or API). Flux orchestrates claude -p; it does not bring its own model.
• You touch the Design → Code seam at least weekly. If you redesign twice a year, write the shell script.
• You work solo or on a team under ~15 engineers. Larger teams have internal platforms that swallow this need.

If three of four match, install it. If one matches, star it and come back in six months.

What Flux does

1. Prototype in Claude Design   →  export JSX + PNG to handoff/
2. Run: flux deploy --analyze   →  Claude generates spec, Claude Code implements
3. Check live site              →  done

flux analyze reads your handoff files, sends them to the Anthropic API with an engineered system prompt, and writes a calibrated PROMPT.md — complete with API call preservation, field name mappings, landmine detection, and deploy commands.

flux deploy fires Claude Code non-interactively against that spec. Claude Code implements the changes, commits, and pushes.

One command. No manual spec writing. No back-and-forth.

Install

npm install -g claude-flux

Prerequisite: Claude Code installed and authenticated.

For flux analyze: set ANTHROPIC_API_KEY in your environment (console.anthropic.com).

Quick start

# Scaffold a handoff folder
flux init

# Drop your design exports into handoff/
# Edit handoff/PROMPT.md — or let analyze write it for you

# Generate a calibrated spec from your handoff files
flux analyze

# Review the spec, then deploy
flux deploy

# Or skip the review — analyze and deploy in one shot
flux deploy --analyze

Commands

| Command | What it does | |---------|-------------| | flux deploy | Run Claude Code against handoff/PROMPT.md | | flux analyze | Generate calibrated PROMPT.md from handoff/ files via Anthropic API | | flux deploy --analyze | Analyze then deploy in one shot | | flux init | Create handoff/ with a PROMPT.md template | | flux validate | Pre-flight checks before deploying | | flux status | Recent commits + handoff contents |

| Flag | Default | Description | |------|---------|-------------| | --handoff DIR | handoff | Path to handoff folder | | --model MODEL | claude-sonnet-4-5 | Model for analyze (also: claude-opus-4-5) | | --dry-run | — | Preview without running anything | | --output FILE | handoff/PROMPT.md | Where to write the generated spec |

A real PROMPT.md

Not a template — a filled-in example you can copy and adapt:

# Hero section redesign — pricing page

## Intent
Replace the current hero on /pricing with the new variant from Claude
Design. Keep the existing CTA wiring (it routes to /signup?plan=).

## Acceptance criteria
- Matches screens/hero.png at viewport >= 1024px
- Mobile: stacks vertically, CTA full-width below 640px
- Uses tokens.json for colour + spacing (no new Tailwind classes)
- Existing Cypress test pricing-hero.cy.ts still passes
- No new dependencies

## Out of scope
- Footer changes (separate handoff coming this week)
- Copy on the comparison table below the hero

The realism is the point. flux analyze generates specs at this level of detail automatically — field mappings, API call preservation, landmine flags, deploy commands.

flux.config.json — institutional knowledge

Create flux.config.json in your repo root to encode everything that would otherwise live in someone's head. Copy flux.config.template.json to start.

{
  "repo": {
    "deploy": "my-app",
    "src": "src/"
  },
  "design_system": {
    "accent": "#00d4ff",
    "font_display": "Inter",
    "rule": "CSS variables only — no hardcoded hex"
  },
  "known_landmines": [
    "useIsMobile must be called before any conditional return",
    "design-canvas.jsx is dev-only — always strip"
  ]
}

Every landmine you discover goes in this file. The more populated it is, the better every future flux analyze run gets. Your config compounds; a fresh install starts from zero.

The three objections

"I can just write a shell script."

You can. You did. It now has nine flags, a hardcoded path to your teammate's machine, and a TODO from October. Flux is the version of that script that didn't accrete. The convention matters more than the binary — if you outgrow Flux, you keep handoff/ and move on.

"Claude Design already has GitHub integration."

Claude Design's integration opens a PR with code. Flux opens a PR with code plus the handoff/ folder that produced it, so the next iteration starts from the same artifact instead of a fresh chat. The handoff is the source; the code is the derivative.

"This only works with Claude Code."

Today, yes. The handoff/ convention is model-agnostic; the runner isn't. A Codex or Gemini adapter is one file. Open an issue if you want one before we get to it.

Cost

| Component | Cost | |-----------|------| | flux deploy | Free — uses your Claude Code / Claude Max subscription | | flux analyze (Sonnet) | ~$0.05–0.10 per run | | flux analyze (Opus) | ~$0.50–0.65 per run |

Roadmap

• [x] Phase 1 — Core scripts (PowerShell + Bash)
• [x] Phase 2 — npm package, claude-flux CLI
• [x] Phase 2.5 — flux analyze (automated spec generation via API)
• [ ] Phase 3 — Watcher mode: auto-deploy when handoff/ changes
• [ ] Phase 4 — MCP server: Claude Design POSTs directly, zero manual steps

Contributing

Bug reports and PRs welcome. Open an issue first for anything significant.

git clone https://github.com/KlossKarl/claude-flux
cd claude-flux
node test/basic.test.js   # 7 tests, should all pass

If Flux saves you time, a star goes a long way.

License

MIT