Configure a Project

You can use Flux without project configuration. Add it when a repository has conventions that Flux should follow consistently.

#Start at the project root

Flux treats the current directory as its workspace. Start from the repository root so file suggestions and tools can reach the whole project:

cd path/to/your-project
flux

@file paths are relative to this directory and cannot escape it through .. or symlinks.

#Add repository instructions

Create FLUX.md or .fluxrc at the project root. Flux uses the first non-empty file it finds.

# Project instructions

- Use pnpm for JavaScript dependencies.
- Preserve the public API response format.
- Ask before changing database migrations.

Write short, actionable rules that apply across tasks. Put the details of a one-time task in its prompt instead.

#Save project defaults

Project settings live in ./.flux/config.json and override global defaults from ~/.flux/config.json. Flux creates or enriches the project file without overwriting values already there.

{
  "provider": "openai",
  "model": "gpt-5.4-mini",
  "effort": "medium",
  "permissionMode": "ask"
}

Do not commit API keys. Use provider environment variables or secure user-level configuration for credentials. See the configuration reference for every field and the full precedence rules.

#Know what is shared

Item	Scope
FLUX.md or .fluxrc	Repository instructions
./.flux/config.json	Project defaults
~/.flux/config.json	Defaults for your user account
./.flux/skills	Reusable procedures for this project
~/.flux/skills and ~/.flux/plugins	User-level extensions
~/.flux/history	Saved interactive sessions

You have completed the beginner path. Continue with daily workflows or use the task finder.