Documentation Index
Fetch the complete documentation index at: https://mintlify.com/8BitTacoSupreme/flowstate/llms.txt
Use this file to discover all available pages before exploring further.
FlowState uses a two-layer configuration system: environment variables set persistent runtime behaviour (such as which claude binary to use), while CLI flags on flowstate init and flowstate run control per-run preferences. Preferences set via CLI flags are serialised into flowstate.json so subsequent commands — like flowstate run or flowstate context — automatically reuse them without you having to repeat the flags.
Environment variables
| Variable | Purpose |
|---|
FLOWSTATE_CLAUDE_BIN | Override the path to the claude binary. Takes precedence over PATH auto-detection and all common install location checks. |
claude in this order:
FLOWSTATE_CLAUDE_BIN environment variableclaude on PATH (via shutil.which)- Common install locations:
~/.local/bin/claude, /usr/local/bin/claude, /opt/homebrew/bin/claude
If none of these resolve to a file, the pipeline falls back to dry-run mode automatically.
# Example: point to a non-standard install location
export FLOWSTATE_CLAUDE_BIN=/home/user/bin/claude
flowstate check
When using Flox, FLOWSTATE_CLAUDE_BIN is set automatically in the [profile] block of manifest.toml to point at the Flox-managed claude binary. You don’t need to set it manually inside a flox activate shell.
CLI flags
These flags are available on flowstate init and flowstate run:
| Flag | Type | Default | Description |
|---|
--model | TEXT | (config default) | Claude model to use for all bridge calls in the run. Examples: sonnet, opus, haiku. |
--budget | FLOAT | None | Maximum spend per bridge call in USD. Passed as --max-budget-usd to each claude --print invocation via BridgeConfig. |
--effort | TEXT | (none) | Effort level for all claude CLI calls. Accepts low, medium, or high. Passed as --effort to the CLI. |
--dry-run | flag | False | Simulate the pipeline without real LLM calls. See Dry Run. |
--skip-interview | flag | False | Reuse existing interview answers from flowstate.json instead of prompting again. |
Example: full flag combination
flowstate init \
--model haiku \
--budget 0.50 \
--effort low \
--skip-interview
claude-haiku, caps each call at $0.50, and passes --effort low to the CLI.
BridgeConfig defaults
BridgeConfig is the dataclass that wraps every claude --print invocation. The defaults are:
| Field | Default | Description |
|---|
timeout | 300 | Seconds before a claude --print call is killed with TimeoutExpired. |
max_turns | 10 | Maximum agentic turns per bridge call (passed as --max-turns). |
allowed_tools | [] | Tool permissions passed as --allowedTools. Empty means no tools are restricted. |
model | None | No model flag is sent unless explicitly set. |
max_budget_usd | None | No budget cap unless set via --budget. |
effort | None | No effort flag unless set via --effort. |
max_turns per call. The research adapter uses max_turns=3 per topic; the strategy adapter uses max_turns=5.
ProjectPreferences model
CLI flags on flowstate init are stored in flowstate.json under the preferences key as a ProjectPreferences Pydantic model:
class ProjectPreferences(BaseModel):
project_name: str = ""
dry_run: bool = False
auto_branch_on_hardening: bool = True
model: str = ""
max_budget_usd: float | None = None
effort: str = ""
| Field | CLI flag | Description |
|---|
project_name | (interview) | Set during the interview. Used as the title in generated context files. |
dry_run | --dry-run | Stored so flowstate run and flowstate context know whether to use mock mode. |
auto_branch_on_hardening | (default true) | Reserved for auto git-branch creation on hardening phases. |
model | --model | Persisted for reuse in subsequent commands. |
max_budget_usd | --budget | Persisted for reuse in subsequent commands. |
effort | --effort | Persisted for reuse in subsequent commands. |
State file: flowstate.json
flowstate.json is the single source of truth for a FlowState project. It is:
- Pydantic-validated — loaded and validated against
FlowStateModel on every read
- Written after every pipeline step — crash-resilient; a mid-run failure leaves a valid partial state
- Auto-migrated — v0.1.0 state files are migrated to v0.2.0 format on load (old tool keys
autoresearch, gstack, superpowers are renamed to research, strategy, discipline)
Do not delete flowstate.json between runs. FlowState uses it to resume from failures, inject prior state into bridge prompts via --skip-interview, and track which artifacts have been created. If you need a clean slate, delete it intentionally and start a fresh flowstate init.
flowstate.json structure:
{
"version": "0.2.0",
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:05:00Z",
"interview": {
"research_focus": "vector databases, embedding models",
"core_problem": "Semantic search is slow and expensive at scale",
"ten_x_vision": "Sub-10ms semantic search for 1B documents",
"milestones": ["MVP indexer", "Query optimisation", "Production hardening"],
"test_coverage": 80,
"architecture_pattern": "microservices"
},
"preferences": {
"project_name": "semantic-search",
"dry_run": false,
"auto_branch_on_hardening": true,
"model": "sonnet",
"max_budget_usd": null,
"effort": ""
},
"tools": {
"research": { "status": "completed", "artifacts": ["research/report.md"] },
"strategy": { "status": "completed", "artifacts": ["research/strategy.md"] },
"gsd": { "status": "completed", "artifacts": [".planning/PROJECT.md"] },
"discipline": { "status": "completed", "artifacts": [] }
},
"context_files": [
".planning/PROJECT.md",
".planning/ROADMAP.md",
".planning/config.json",
".claude/CLAUDE.md",
"research/brief.md"
]
}
Memory file: memory.db
memory.db is a SQLite database using FTS5 full-text search with porter stemming. It stores research findings, strategy assessments, interview decisions, and failure logs across pipeline runs. On each subsequent run, relevant prior knowledge is automatically retrieved and prepended to bridge prompts as a ## Prior Knowledge section.
| Property | Value |
|---|
| Location | memory.db in the project root |
| Format | SQLite FTS5 |
| Gitignored | Yes (by default) |
| Clearable | flowstate memory clear |
memory.db is portable and inspectable with any SQLite client. Run flowstate memory stats to see entry counts by kind, and flowstate memory search "your query" to see what prior knowledge would be injected for a given topic.
