Fluxy

Workflow orchestration CLI for automated software development. Define a pipeline as YAML, and Fluxy executes it — from implementation to PR — using Claude SDK, with parallel execution, smart retries, and zero human intervention.

Getting Started

What you need

What	Where	How often
Install Fluxy	Your machine	Once
`~/.fluxy/credentials.yaml`	Your machine	Once
`.fluxy/workflow.yaml`	Each repo	Once per repo
`fluxy run --prompt "..."`	Terminal	Each task

Step 1: Install Fluxy (one-time)

git clone https://github.com/CristianAmbrosini/fluxy.git
cd fluxy
npm install
npm run build
npm link   # makes `fluxy` available globally

Step 2: Set up credentials (one-time)

fluxy init   # creates ~/.fluxy/credentials.yaml (chmod 600)

Edit ~/.fluxy/credentials.yaml:

# Direct Anthropic API
anthropic:
  api_key: sk-ant-...

# Or via Portkey/gateway
anthropic:
  base_url: https://api.portkey.ai
  auth_token: your-portkey-key
  api_key: your-anthropic-key

# For PR creation
github:
  token: ghp_...

# Future integrations
jira:
  token: ...
  base_url: https://your-org.atlassian.net
figma:
  token: ...

Alternatively, use environment variables (they take precedence over the file):

export ANTHROPIC_API_KEY=sk-ant-...
export ANTHROPIC_BASE_URL=https://api.portkey.ai    # for Portkey
export ANTHROPIC_AUTH_TOKEN=your-portkey-key         # for Portkey
export GITHUB_TOKEN=ghp_...

Step 3: Add workflow to your repo (once per repo)

mkdir -p .fluxy

Create .fluxy/workflow.yaml — see Example Workflow below.

Step 4: Run

fluxy run --prompt "Add dark mode toggle to the header"

# With options
fluxy run --prompt "Fix login bug" --model claude-opus-4-6 --max-retries 5
fluxy run --config .fluxy/workflow.yaml --repo /path/to/repo --prompt "..."

Example Workflow

Minimal

name: my-project
steps:
  - id: implement
    block: claude-implement
  - id: check
    block: run-commands
    depends_on: [implement]
    params:
      commands: ["npm test"]
  - id: publish
    block: git-pr
    depends_on: [check]

Real-world (SonarCloud webapp)

name: sonarcloud-webapp
version: 1

defaults:
  model: claude-opus-4-6
  max_retries: 3
  retry_delay: exponential
  circuit_breaker: 15

steps:
  - id: prompt
    block: prompt-input

  - id: implement
    block: claude-implement
    depends_on: [prompt]
    params:
      model: claude-opus-4-6
      system_prompt: |
        You are a senior frontend engineer working on the SonarCloud webapp.
        This is an Nx monorepo with React 19, TypeScript, Vite, Tailwind (sw-* prefix),
        and Echoes design system.
        Key rules:
        - Functional components, named exports, Echoes over legacy design-system
        - Localization: keys only, destructure useIntl
        - React Query: reuse existing queries, standard TanStack results
      files_context:
        - CLAUDE.md
        - package.json
        - nx.json
    retry:
      max_attempts: 5
      on_failure: iterate

  - id: format
    block: run-commands
    depends_on: [implement]
    params:
      commands:
        - git diff --name-only HEAD~1 | xargs npx prettier --write
    retry:
      max_attempts: 1
      on_failure: skip

  # 3 parallel review agents
  - id: review-security
    block: claude-review
    depends_on: [format]
    params:
      focus: security

  - id: review-quality
    block: claude-review
    depends_on: [format]
    params:
      focus: [code-quality, react-patterns, echoes-compliance]

  - id: review-performance
    block: claude-review
    depends_on: [format]
    params:
      focus: [performance, bundle-size, react-query-patterns]

  # CI validation
  - id: ci-check
    block: run-commands
    depends_on: [review-security, review-quality, review-performance]
    params:
      commands:
        - npx nx run sq-cloud:ts-check
        - npx nx run sq-server:ts-check
        - yarn test
        - yarn lint
        - yarn format-check
      fail_fast: true
    retry:
      max_attempts: 3
      on_failure: iterate

  - id: publish
    block: git-pr
    depends_on: [ci-check]
    params:
      title_prefix: "[Fluxy]"
      include_screenshots: true
      include_review_summary: true

Pipeline flow:

prompt → implement → format → ┬→ review-security    ┐
                               ├→ review-quality     ├→ ci-check → publish
                               └→ review-performance ┘

CLI Usage

fluxy run --prompt <prompt> [options]
fluxy init                              # create credentials file
fluxy --version

Option	Default	Description
`-p, --prompt <text>`	required	Task description
`-c, --config <path>`	`.fluxy/workflow.yaml`	Workflow config file
`-m, --model <model>`	`claude-sonnet-4-6`	Override default model
`--max-retries <n>`	`3`	Override max retries
`--repo <path>`	`.`	Target repository path

Credentials

Tokens are stored centrally in ~/.fluxy/credentials.yaml (chmod 600) — never in your repo.

Resolution Order

Env var > ~/.fluxy/credentials.yaml

Service	Credential	Env var
`anthropic`	`api_key`	`ANTHROPIC_API_KEY`
`anthropic`	`base_url`	`ANTHROPIC_BASE_URL`
`anthropic`	`auth_token`	`ANTHROPIC_AUTH_TOKEN`
`github`	`token`	`GITHUB_TOKEN`
`jira`	`token`	`JIRA_TOKEN`
`jira`	`base_url`	`JIRA_BASE_URL`
`figma`	`token`	`FIGMA_TOKEN`

Which Blocks Need What

Block	Required credential
`claude-implement`	`anthropic.api_key` (or `auth_token` for gateway)
`claude-review`	`anthropic.api_key` (or `auth_token` for gateway)
`git-pr`	`github.token`

Fluxy gives a clear error with setup instructions if a required credential is missing.

YAML Configuration

Config Resolution

Three-level merge: built-in defaults < YAML defaults section < per-block params. CLI args (--model, --max-retries) override everything.

Defaults Reference

Parameter	Default	Scope
`model`	`claude-sonnet-4-6`	Pipeline-wide, overridable per block
`max_retries`	`3`	Pipeline-wide, overridable per block
`retry_delay`	`exponential`	Pipeline-wide, overridable per block
`on_failure`	`iterate`	Per block
`circuit_breaker`	`15`	Pipeline-wide
`timeout`	`300000` (5min) / `600000` (10min for Claude)	Per block
`reviewers`	`1`	claude-review
`focus`	`["code-quality"]`	claude-review
`fail_fast`	`true`	run-commands
`parallel`	`false`	run-commands
`screenshots`	`false`	playwright-test
`screenshot_dir`	`.fluxy/screenshots`	playwright-test / screenshot
`draft`	`false`	git-pr
`title_prefix`	`[Fluxy]`	git-pr
`include_screenshots`	`true`	git-pr
`include_review_summary`	`true`	git-pr
`viewport`	`{ width: 1280, height: 720 }`	screenshot

Built-in Blocks

`prompt-input`

Entry point. Passes the CLI prompt into pipeline context. No parameters.

`claude-implement`

Generates or modifies code using Claude SDK with tool_use. Creates a working branch, explores the repo (search, list, read files), writes changes.

Param	Default	Description
`model`	`claude-sonnet-4-6`	Claude model to use
`system_prompt`	generic engineer prompt	System prompt for Claude
`files_context`	`[]`	Glob patterns for context files to pre-load

`claude-review`

Spawns N parallel review agents. Each reviews the diff with a specific focus. Fails if any reviewer flags blocking issues.

Param	Default	Description
`model`	`claude-sonnet-4-6`	Claude model to use
`reviewers`	`1`	Number of parallel reviewers
`focus`	`["code-quality"]`	Review focus areas

`run-commands`

Executes shell commands. Captures stdout/stderr.

Param	Default	Description
`commands`	`[]`	Shell commands to run
`fail_fast`	`true`	Stop on first failure
`parallel`	`false`	Run commands in parallel

`playwright-test`

Starts a dev server, runs Playwright tests, optionally captures screenshots.

Param	Default	Description
`start_server`	—	Command to start dev server
`test_files`	—	Glob patterns for test files
`screenshots`	`false`	Capture screenshots
`screenshot_dir`	`.fluxy/screenshots`	Screenshot output directory

`screenshot`

Captures browser screenshots of specified URLs.

Param	Default	Description
`urls`	`[]`	URLs to screenshot
`viewport`	`{ width: 1280, height: 720 }`	Browser viewport size
`output_dir`	`.fluxy/screenshots`	Output directory

`git-pr`

Creates or updates a GitHub PR via gh CLI. Assembles description from upstream block summaries and screenshots.

Param	Default	Description
`title_prefix`	`[Fluxy]`	PR title prefix
`include_screenshots`	`true`	Attach screenshots to PR
`include_review_summary`	`true`	Include review summary in PR body
`draft`	`false`	Create as draft PR

Pipeline Execution

Steps form a DAG (directed acyclic graph). Independent steps run in parallel. Dependencies are declared with depends_on.

Retry Behavior

Each block has a failure mode:

Mode	Behavior
`iterate`	Retry with failure context fed back (default)
`skip`	Mark as skipped, continue pipeline
`fail`	Halt pipeline immediately

On retry, the block receives full failure history — including downstream failures. For example, if CI fails due to a type error, claude-implement retries with the exact error message.

Safety Limits

Limit	Default	Description
Circuit breaker	`15`	Max total retries across all blocks
Block timeout	`5min` (commands) / `10min` (Claude)	Per-block timeout

Development

npm install          # install dependencies
npm run build        # build CLI
npm test             # run tests
npm run test:watch   # run tests in watch mode
npm run lint         # type check

Project Structure

src/
├── cli/           # CLI entry point (Commander.js)
├── engine/        # DAG, scheduler, retry, pipeline orchestrator
├── blocks/        # Built-in block implementations
├── config/        # YAML parsing, Zod schemas, defaults, credentials
├── context/       # Pipeline shared state
└── logger/        # Structured logging
tests/
├── unit/          # Unit tests (DAG, config, retry, credentials)
├── integration/   # Integration tests
└── e2e/           # End-to-end tests

Requirements

Node.js >= 20
Credentials configured via fluxy init or env vars (see Credentials)
gh CLI (for git-pr block)
Playwright (for playwright-test and screenshot blocks): npx playwright install

Name		Name	Last commit message	Last commit date
docs		docs
src		src
tests/unit		tests/unit
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

Fluxy

Getting Started

What you need

Step 1: Install Fluxy (one-time)

Step 2: Set up credentials (one-time)

Step 3: Add workflow to your repo (once per repo)

Step 4: Run

Example Workflow

Minimal

Real-world (SonarCloud webapp)

CLI Usage

Credentials

Resolution Order

Which Blocks Need What

YAML Configuration

Config Resolution

Defaults Reference

Built-in Blocks

`prompt-input`

`claude-implement`

`claude-review`

`run-commands`

`playwright-test`

`screenshot`

`git-pr`

Pipeline Execution

Retry Behavior

Safety Limits

Development

Project Structure

Requirements

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Fluxy

Getting Started

What you need

Step 1: Install Fluxy (one-time)

Step 2: Set up credentials (one-time)

Step 3: Add workflow to your repo (once per repo)

Step 4: Run

Example Workflow

Minimal

Real-world (SonarCloud webapp)

CLI Usage

Credentials

Resolution Order

Which Blocks Need What

YAML Configuration

Config Resolution

Defaults Reference

Built-in Blocks

prompt-input

claude-implement

claude-review

run-commands

playwright-test

screenshot

git-pr

Pipeline Execution

Retry Behavior

Safety Limits

Development

Project Structure

Requirements

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`prompt-input`

`claude-implement`

`claude-review`

`run-commands`

`playwright-test`

`screenshot`

`git-pr`