Skip to main content

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.

Most FlowState issues fall into a small set of categories: the claude CLI isn’t where FlowState expects it, a pipeline step fails and marks itself BLOCKED, a pre-commit hook breaks outside the managed environment, or a state file from an older version needs migration. The sections below walk through each issue and its fix. If none of these apply, run flowstate init --dry-run to isolate whether the problem is in the orchestration layer or in the LLM calls.

​
Issues

Symptom: FlowState prints a warning about the claude CLI not being found, or flowstate check returns nothing.Diagnosis: Run flowstate check to see what FlowState finds:
flowstate check
# ✗ claude CLI not found
Fix 1 — Set FLOWSTATE_CLAUDE_BIN:If claude is installed but not on your PATH, point FlowState directly to the binary:
export FLOWSTATE_CLAUDE_BIN=/path/to/claude
flowstate check
# ✓ claude CLI found: /path/to/claude
Fix 2 — Install Claude Code:If Claude Code isn’t installed, follow the official install guide:
npm install -g @anthropic-ai/claude-code
Auto-detection locations: FlowState checks these paths in order before giving up:
  1. $FLOWSTATE_CLAUDE_BIN environment variable
  2. claude on $PATH
  3. ~/.local/bin/claude
  4. /usr/local/bin/claude
  5. /opt/homebrew/bin/claude
If claude is not found at all, FlowState falls back to dry-run mode automatically so the pipeline always completes. Check artifact files for the *Generated by FlowState (mock mode)* footer to confirm whether a run used real LLM calls.
Symptom: flowstate status shows a tool with status BLOCKED.
│ research     │ Research     │ blocked   │ ---        │
What BLOCKED means: The tool failed but the pipeline continued rather than aborting. The error is stored on the tool’s state entry in flowstate.json.Diagnosis: Run flowstate status — it displays the stored error message alongside the BLOCKED status. You can also inspect flowstate.json directly:
cat flowstate.json | jq '.tools.research.error'
Fix: Resolve the underlying issue (API key, network, timeout), then re-run the pipeline reusing existing interview answers:
flowstate init --skip-interview
--skip-interview reads your prior answers from flowstate.json and reruns all steps from the beginning, resetting each tool to ready before the run starts.
Do not delete flowstate.json to “fix” a blocked step — you’ll lose your interview answers, stored preferences, and any successfully completed artifacts. Use --skip-interview to retry instead.
Symptom: git push fails with an error like .venv/bin/python: No such file or directory from the pytest-cov pre-push hook.Root cause: The .pre-commit-config.yaml local hook uses the project-local .venv/bin/python path directly as its entry point:
- repo: local
  hooks:
    - id: pytest-cov
      name: pytest with coverage (80% min)
      entry: .venv/bin/python -m pytest tests/ --cov=flowstate --cov-fail-under=80 --tb=short -q
      language: system
      types: [python]
      pass_filenames: false
      always_run: true
      stages: [pre-push]
Because the entry is a relative path, the hook fails if .venv hasn’t been created yet — for example, if you cloned the repo and skipped flox activate or manual venv setup before your first push.Fix 1 — Always push from inside the managed environment:
flox activate
git push
Or from inside the plain venv:
source .venv/bin/activate
git push
Fix 2 — Bypass the hook temporarily:
git push --no-verify
Use this only as a short-term workaround. The hook enforces 80% test coverage and running it is recommended before pushing to main.
Symptom: The research pipeline step takes a very long time or returns a TimeoutExpired error. flowstate status shows research as BLOCKED with a timeout message.Root cause: The research adapter runs one claude --print call per comma-separated topic in research_focus. Each call uses max_turns=3 and a 300-second timeout. With many topics or complex questions, calls can approach or exceed the limit.Fix 1 — Reduce the number of topics:Edit flowstate.json to reduce the number of comma-separated values in interview.research_focus, then re-run:
# Before: "vector databases, embedding models, reranking, hybrid search, ANN algorithms"
# After:  "vector databases, embedding models"
flowstate init --skip-interview
Fix 2 — Use a faster model:
flowstate init --model haiku --skip-interview
haiku produces less thorough research but completes in a fraction of the time. Use it during development and switch to sonnet for final runs.Fix 3 — Increase timeout via BridgeConfig:The default bridge timeout is 300 seconds. This is not currently configurable via CLI flag — if you consistently need more time, set a higher value in your bridge configuration or split your research_focus into fewer, more focused topics.
Symptom: After running git commit, the commit fails and you see a message from Ruff that files were modified.Root cause: The .pre-commit-config.yaml includes the ruff hook with --fix and ruff-format. When Ruff finds formatting issues, it auto-applies fixes and exits with a non-zero code, which causes the commit to abort:
- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.15.9
  hooks:
    - id: ruff
      args: [--fix, --exit-non-zero-on-fix]
    - id: ruff-format
Fix: Re-stage the Ruff-modified files and commit again:
git add -u
git commit -m "your message"
The second commit will pass because Ruff already applied its fixes and has nothing more to change.
On the first commit in a new environment, pre-commit may take ~30 seconds to install Ruff. This is a one-time setup cost — subsequent commits are fast.
Symptom: After upgrading FlowState, flowstate status shows unexpected tool names or an empty tool table.Root cause: FlowState v0.1.0 used different tool keys in flowstate.json:
v0.1.0 keyv0.2.0 key
autoresearchresearch
gstackstrategy
superpowersdiscipline
Fix: FlowState auto-migrates v0.1.0 state files on load. The migration runs automatically whenever flowstate.json has "version": "0.1.0" (or no version field). You don’t need to do anything — just run any FlowState command and the migration will apply:
flowstate status
# State migrated from v0.1.0 to v0.2.0
The migrated state is written back to flowstate.json with "version": "0.2.0" and the renamed tool keys. Old artifact paths stored under the old keys are preserved.If migration doesn’t resolve the issue, inspect the raw file and confirm the version field:
cat flowstate.json | jq '.version, (.tools | keys)'
Symptom: FlowState prints an error about memory.db, or flowstate memory search returns an error.Common causes:
  • memory.db was created by a different SQLite version
  • The FTS5 virtual tables are corrupted
  • Disk full when writing during a pipeline run
Fix 1 — Clear all entries without deleting the file:
flowstate memory clear
This removes all memory entries but keeps the database schema intact. FlowState will recreate entries on the next pipeline run.Fix 2 — Delete the database entirely:
rm memory.db
FlowState creates a fresh memory.db on the next run. You’ll lose all prior research findings and strategy assessments stored in memory, but flowstate.json and all artifact files are unaffected.
memory.db is gitignored by default. Losing it only affects the ## Prior Knowledge injection into future bridge prompts — it does not affect the pipeline itself or any generated files.

​
General diagnosis tip

When in doubt, run flowstate init --dry-run to walk through the entire pipeline without making LLM calls. If dry-run succeeds but a live run fails, the issue is in the bridge layer (API keys, claude CLI, network, timeouts). If dry-run itself fails, the issue is in the orchestration or state layer and is reproducible without any external dependencies.

Build docs developers (and LLMs) love

Get started for freeTalk to us