Using Flux with Claude, Cursor, and friends

AI coding assistants are useful for Flux work in inverse proportion to how stale their training data is. Anything Flux-specific they “remember” is probably wrong — the surface moves fast and the public corpus is small. The fix is the same in every tool: hand the assistant the live docs and tell it not to guess.

Claude (browser or Desktop)

The simplest path. Open a new conversation, paste the index URL, and state the constraints.

I'm building with Flux 0.56.0 (https://github.com/edurdias/flux).
The full docs index is at https://docs.fluxhq.dev/llms.txt — fetch
pages from there as needed. Help me write a workflow that...

Claude with web access will fetch llms.txt, scan the descriptions, pull the pages it needs, and answer with current syntax. If the conversation is long-running and you want the model to have the whole corpus loaded, upload llms-full.txt as a file attachment instead — same content, no per-page fetches required.

Two small habits that pay off:

• State the Flux version explicitly in the first message. Claude’s training cutoff may pre-date the version you are on; without a version pin it will sometimes synthesize plausible-looking but wrong API shapes (the @agent decorator that does not exist, @schedule as a top-level decorator).
• When the model proposes code, ask it to cite which doc page it came from. This catches confabulation early.

Cursor, Continue, Aider, and other IDE assistants

These tools read a per-project rules file at the project root. The exact filename varies — .cursorrules for Cursor, .continuerules or .continue/config.yaml for Continue, .aider.conf.yml for Aider — but the pattern is the same: a short file that the assistant prepends to every request.

A worked example for Cursor:

# .cursorrules

This project uses Flux 0.56.0 — a durable workflow and agent framework
for Python 3.12+. Canonical docs: https://docs.fluxhq.dev/llms.txt

When writing Flux workflows, always:

- Use `@workflow` and `@task` decorators imported from the `flux` package.
- Keep workflow bodies deterministic. Non-deterministic work (clock reads,
  random numbers, network I/O) goes inside tasks, not in the workflow body.
- Take exactly one parameter after `ctx`. Wrap multi-field inputs in a
  Pydantic model so the catalog can publish a JSON schema.
- Use `agent()` from `flux.tasks.ai` for LLM calls. There is no `@agent`
  decorator — `agent()` is a factory that returns a callable task.
- Prefer `pipeline()`, `parallel()`, and native `await` over hand-rolling
  Celery-shaped chains. They are ordinary tasks; nothing magic.
- When you propose code, cite the doc page (URL from llms.txt) it came from.

Avoid:

- `@schedule` as a top-level decorator (does not exist). Schedules are
  attached via `@workflow.with_options(schedule=cron(...))`.
- Direct provider SDK imports (`anthropic`, `openai`) when an `agent()` call
  would do — the agent path is the supported one for retries, replay, and
  observability.
- Mutating module-level state inside workflows. The replay path will skip it
  silently and the bug will be invisible until it bites in production.

A few notes:

• The rules file is project-local. Different Flux projects can have different version pins and different style preferences without interfering.
• Continue and Aider accept slightly different syntax (YAML in some cases) but the content above translates more or less verbatim.
• If the assistant supports @docs references (Continue does, recent Cursor versions do), point it at https://docs.fluxhq.dev/llms.txt directly so it can fetch pages on demand. This costs nothing and replaces the version-pin habit.

MCP-based assistants (Claude Desktop, others)

Some assistants speak the Model Context Protocol. For these, Flux itself ships an MCP server. Run it with flux start mcp, point your client at the resulting endpoint, and the assistant gets a typed toolset directly: list_workflows, execute_workflow_*, get_execution_status, the lot. It can drive Flux as well as document it.

Two layers exist and are easy to confuse:

• The management MCP server (flux start mcp, mcp_server.py) exposes ~22 generic tools for listing, executing, and inspecting workflows. This is the one most users want.
• The workflows-as-services MCP path (service_mcp.py) exposes each registered workflow as its own MCP tool. Useful when the assistant should call a specific named workflow with strongly-typed inputs.

See MCP server reference for the full tool catalog. For Claude Desktop specifically, add the server to claude_desktop_config.json like any other MCP source.

Common pitfalls

A short list of things to flag for the model up front. Each of these has been documented from real verification work against Flux 0.56.0.

• Stale prose in the model’s training data. Earlier internal docs (pre-Phase 5) had some claims that were wrong (notably: task caching was described as in-memory and per-execution; the real implementation is disk-backed and cross-execution). If the assistant cites internal Flux behavior from memory, ask it to verify against /llms.txt first.
• @agent decorator hallucination. Multiple assistants will propose @agent as a decorator. It is not. agent() is a factory imported from flux.tasks.ai. See Agents overview.
• @schedule decorator hallucination. Same story. Schedules live on @workflow.with_options(schedule=cron(...)).
• Saga rollback expectations. A failing task’s rollback= runs only for that task. There is no automatic cascade to previously-completed steps. The model will sometimes assume Saga-pattern automatic compensation; tell it to read Rollback and compensation before designing one.

Refreshing the context

llms.txt is regenerated on every deploy, so simply re-fetching it gives you the current surface. For long-lived project rules files, a quarterly review is enough — pin the Flux version, regenerate the file if the version changed, re-verify the “avoid” list against the latest release notes.

This guide is dated 2026-07; AI tools and conventions change quickly. Last verified against Claude Desktop, Cursor 0.40, and Continue 0.10 in July 2026.