FlowState Installation: Flox and Manual Setup Guide

FlowState can be installed in two ways: via Flox for a fully reproducible, zero-configuration environment, or manually using a standard Python venv and pip. The Flox path is strongly recommended for new users — a single flox activate command provisions Python, Node, the Claude Code CLI, MCP servers, and FlowState itself in one step.

Installation Options

Flox (Recommended)
Manual (pip/venv)

Flox is a declarative environment manager that pins every dependency — Python version, Node version, npm packages, and shell configuration — into a reproducible manifest. You get an identical environment on macOS (Apple Silicon and Intel) and Linux (x86_64 and ARM).Step 1 — Clone the repository:

git clone https://github.com/8BitTacoSupreme/flowstate.git
cd flowstate

Step 2 — Activate the Flox environment:

flox activate

On first activation, Flox runs the on-activate hook, which automatically:

Creates a Python venv at .venv/ and installs FlowState in editable mode
Installs the Claude Code CLI via npm into the Flox cache (nothing pollutes your system)
Installs the Context7 MCP server (@upstash/context7-mcp)
Installs the Exa MCP server (exa-mcp-server)
Configures .claude/settings.json with MCP server entries for both servers

Subsequent activations are instant — all packages are cached by Flox and only reinstalled if the manifest changes.When the environment is ready, your shell prompt will display a summary:

  ⚡ FlowState environment ready
  Python:     Python 3.13.x
  Node:       v24.x.x
  Claude CLI: claude v2.x.x
  FlowState:  flowstate, version 0.2.0

  Commands:
    flowstate init --dry-run   # test the pipeline
    flowstate init             # live GrandSlam
    flowstate status           # check tool state
    flowstate check            # verify claude bridge

Flox is supported on aarch64-darwin, x86_64-darwin, aarch64-linux, and x86_64-linux. Download it from flox.dev.

If you prefer not to use Flox, you can install FlowState manually into a standard Python virtual environment.Step 1 — Clone the repository:

git clone https://github.com/8BitTacoSupreme/flowstate.git
cd flowstate

Step 2 — Create and activate a virtual environment:

python3.12 -m venv .venv
source .venv/bin/activate

Python 3.13 is also supported:

python3.13 -m venv .venv
source .venv/bin/activate

Step 3 — Install FlowState:

pip install -e .

The -e flag installs in editable mode, so any local changes to the source take effect immediately without reinstalling.Step 4 — Install Claude Code CLI separately:The manual path does not install the Claude Code CLI for you. Follow the official install guide:

npm install -g @anthropic-ai/claude-code

Claude Code requires an active Anthropic account. Use of the claude CLI is subject to Anthropic’s Commercial Terms of Service.

Verify Your Installation

After completing either installation path, confirm that FlowState and the Claude bridge are working correctly. Check the FlowState version:

flowstate --version

Expected output:

flowstate, version 0.2.0

Check the Claude CLI bridge:

flowstate check

Expected output when the bridge is correctly configured:

claude CLI found: /Users/you/.local/bin/claude
Timeout: 300s | Max turns: 10

If the claude binary is not found, FlowState will print:

claude CLI not found.
Install Claude Code or set FLOWSTATE_CLAUDE_BIN to the binary path.

Environment Variables

FlowState reads a single environment variable for runtime configuration:

Variable	Purpose
`FLOWSTATE_CLAUDE_BIN`	Override the path to the `claude` binary

If FLOWSTATE_CLAUDE_BIN is not set, FlowState auto-detects the claude binary by checking, in order:

Your shell PATH
~/.local/bin/claude
/usr/local/bin/claude
/opt/homebrew/bin/claude

To set a custom binary path, export the variable before running FlowState commands:

export FLOWSTATE_CLAUDE_BIN="/path/to/your/claude"
flowstate check

For Flox users, if you use the Exa MCP server’s semantic search capabilities, copy the .env.example file and add your Exa API key:

cp .env.example .env
# Edit .env and set EXA_API_KEY=your_key_here

The Flox profile script automatically loads .env on each flox activate.

Get Started

Concepts

CLI Reference

Guides

FlowState Installation: Flox and Manual Setup Guide

Installation Options

Verify Your Installation

Environment Variables

Build docs developers (and LLMs) love

Get Started

Concepts

CLI Reference

Guides

Documentation Index

​Installation Options

​Verify Your Installation

​Environment Variables

Build docs developers (and LLMs) love

Installation Options

Verify Your Installation

Environment Variables