fluxy 0.4.1

AI-ready workflow contract for software projects.

Fluxy

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

It gives humans, CI, and AI coding agents one clear place to understand how a project should be run, tested, validated, and shipped.

pip install fluxy
fluxy init
fluxy doctor
fluxy run check

What is Fluxy?

Fluxy is a small CLI built around fluxy.yml.

That file describes the commands a project supports:

• local development workflows
• lint, test, check, and build commands
• required environment variables
• protected release and deploy tasks
• list safe workflows for humans and AI agents

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
fluxy list
fluxy run <task>
fluxy run <task> --agent
fluxy env check
fluxy env check --task release
fluxy doctor
fluxy --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)

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

AI agents can inspect and run only the tasks marked as safe:

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

If a task is not marked agent_safe: true, Fluxy refuses to run it in agent mode. Protected tasks such as release and deploy are blocked.

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

License

Fluxy is released under the MIT License.

Author

Created by Jasurbek Kamilov.

Maintained as the Fluxy open-source project.