fluxy 0.4.0

AI-ready workflow contract for software projects.

Fluxy

Fluxy is an AI-ready workflow contract for software projects.

It gives a project one clear place to describe how to run, test, validate, and ship safely. Humans can use it. CI can use it. AI coding agents can use it without guessing which README command is still correct.

pip install fluxy
fluxy init
fluxy doctor
fluxy run check

What is Fluxy?

Fluxy is a small command-line tool built around a fluxy.yml file.

That file describes the workflows a project supports: linting, tests, builds, environment checks, release steps, and commands that should not be run without human confirmation.

Fluxy is not trying to be another general-purpose task runner. The product idea is higher-level: Fluxy is a contract between a software project, its developers, CI, and AI agents.

Why Fluxy?

Most projects start with commands in a README:

pytest
ruff check .
python -m build

Over time those commands drift. The README says one thing, CI runs another, local scripts do a third thing, and a new developer has to guess what is safe. AI coding agents have the same problem: they can edit code, but they often do not know which commands validate the project or which commands are dangerous.

Fluxy turns those commands into an explicit workflow contract:

• define project commands once
• list safe workflows for humans and AI agents
• validate required environment variables without printing secret values
• protect release and deploy tasks behind human confirmation
• make doctor the first place to understand project health
• leave room for CI generation from the same contract later

Cursor writes code. Fluxy tells it how to run, test, and ship safely.

Installation

pip install fluxy

For isolated CLI installation:

pipx install fluxy

Quick start

Create a workflow file:

fluxy init

Inspect the project:

fluxy doctor

List available workflows:

fluxy list

Run a workflow:

fluxy run check

Core commands

fluxy init                 # create fluxy.yml
fluxy list                 # show project workflows
fluxy run <task>           # run a workflow
fluxy run <task> --agent   # only allow agent-safe workflows
fluxy env check            # verify required environment variables
fluxy env check --task release
fluxy doctor               # inspect config, tasks, env, and safety rules
fluxy --version            # show installed version

Python API

Fluxy also exposes a small Python API for tools that want to inspect the same workflow contract:

from fluxy import check_environment, list_tasks, load_workflow, run

workflow = load_workflow("fluxy.yml")

print(list_tasks(workflow, agent_safe=True))
print(check_environment(workflow))

run(workflow, "check", agent=True)

See docs/API.md for the public v0.4 API surface.

Example workflow

project: my-python-package

tasks:
  lint:
    description: Run static checks.
    agent_safe: true
    cmd: ruff check .

  test:
    description: Run the test suite.
    agent_safe: true
    cmd: pytest

  check:
    description: Run all local validation before a pull request.
    agent_safe: true
    steps:
      - task: lint
      - task: test

  build:
    description: Build distribution files.
    agent_safe: true
    cmd: python -m build

  release:
    description: Upload the package after human review.
    protected: true
    agent_safe: false
    env:
      - name: PYPI_API_TOKEN
        description: Required only for release.
        secret: true
    steps:
      - task: check
      - task: build
      - run: python -m twine upload dist/*

Protected tasks require human confirmation:

fluxy run release

Non-interactive environments can use --yes only after an explicit human decision:

fluxy run release --yes

AI agents

Fluxy has a first-class idea of agent-safe workflows.

An AI coding agent can run:

fluxy list --agent-safe
fluxy run check --agent

This gives the agent a safe list of commands without relying on README guessing. If the task is not marked agent_safe: true, Fluxy refuses to run it in agent mode. Protected tasks such as release or deploy are also blocked.

Fluxy does not include telemetry. It does not send project names, paths, command strings, environment variables, repository URLs, or usage events anywhere.

Roadmap

Fluxy v0.4.0 is the clean baseline:

• project init
• workflow listing
• task execution
• environment validation
• protected workflows
• agent-safe workflow mode
• doctor report
• professional package metadata and documentation

Future versions may add:

• CI generation from fluxy.yml
• richer schema validation
• watch mode
• reusable workflow templates
• safer release profiles

No cloud service, marketplace, hidden telemetry, or paid plan is part of the v0.4.0 scope.

License

Fluxy is released under the MIT License.

Author

Created by Jasurbek Kamilov.

Maintained as the Fluxy open-source project.