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.

Flox is the recommended way to run FlowState. A single flox activate command gives you Python 3.13, Node 24, git, jq, ripgrep, the Claude Code CLI, and both MCP servers — all pinned, cached, and reproducible across macOS and Linux. No manual installs, no version conflicts, no system pollution. Everything lives in Flox’s own cache so your global environment stays clean.

​
What Flox provides

Runtime tools

Python 3.13, Node 24, git, jq, ripgrep — all pinned to exact versions in .flox/env/manifest.toml

Claude Code CLI

@anthropic-ai/claude-code installed via npm into the Flox cache — not your system node_modules

Context7 MCP

@upstash/context7-mcp — injects live library documentation into Claude Code sessions

Exa MCP

exa-mcp-server — semantic web search available to all Claude Code sessions inside the project

​
What happens on first flox activate

The on-activate hook in manifest.toml runs once and caches everything. Subsequent activations are instant.
1

Install Claude Code CLI via npm

Claude Code is installed into the Flox node cache ($FLOX_ENV_CACHE/node-global), not your global npm prefix. If installation fails, you’ll see a warning — set FLOWSTATE_CLAUDE_BIN manually as a fallback.
⚡ Installing Claude Code CLI...
2

Install Context7 and Exa MCP servers

Both MCP servers are installed into the same Flox node cache alongside the Claude Code CLI.
⚡ Installing Context7 MCP server...
⚡ Installing Exa MCP server...
3

Create a Python venv and install FlowState

Flox creates .venv inside your project directory and runs pip install -e . so every flowstate command reflects the live source.
⚡ Creating Python venv...
⚡ Installing FlowState...
4

Configure .claude/settings.json

Flox writes (or merges into) .claude/settings.json with entries for both MCP servers so Claude Code picks them up automatically:
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": ""
      }
    }
  }
}
On every subsequent activation, the [profile] block sources your .env file (if present) so API keys are exported automatically: 
# Flox sources .env on every activation via [profile]:
if [ -f "$FLOX_ENV_PROJECT/.env" ]; then
  set -a
  . "$FLOX_ENV_PROJECT/.env"
  set +a
fi
After activation, your shell prints a ready banner: 
  ⚡ 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 run
    flowstate status           # check tool state
    flowstate check            # verify claude bridge

​
Set up your API keys

Before activating for the first time, copy .env.example to .env and fill in your values: 
cp .env.example .env
The .env.example file contains: 
# FlowState environment variables
# Copy to .env and fill in your values:
#   cp .env.example .env

# Exa API key for semantic search (used by Exa MCP server)
# Get one at https://exa.ai
EXA_API_KEY=
EXA_API_KEY is required for the Exa MCP server to perform semantic web searches. Without it, the MCP server will start but search calls will fail. Get a key at exa.ai.

​
How MCP servers enhance the pipeline

Both MCP servers are available to every Claude Code session launched from within flox activate:
  • Context7 resolves library names to their current documentation and injects it into prompts. When the research adapter asks about a framework, Claude Code has access to accurate, version-specific docs rather than training-data snapshots.
  • Exa provides semantic web search. The research adapter’s WebSearch tool calls route through Exa when the MCP server is configured, giving more relevant results than keyword-only search.
The Flox-managed claude binary is automatically set as FLOWSTATE_CLAUDE_BIN on activation, so FlowState always prefers the Flox-installed version over any system claude.

​
Quick start

git clone https://github.com/8BitTacoSupreme/flowstate.git
cd flowstate
cp .env.example .env   # add your EXA_API_KEY
flox activate
Then verify everything is wired up: 
flowstate check
# claude CLI found: /path/to/flox/cache/node-global/bin/claude
# Timeout: 300s | Max turns: 10
Run the pipeline in dry-run mode first to confirm the full flow works before spending any API budget: 
flowstate init --dry-run

​
Fallback: manual installation

If Flox isn’t available on your system, see the installation guide for manual setup using a plain Python venv. You’ll need to install the Claude Code CLI, Node, and MCP servers yourself.
Manual installs don’t get the automatic .claude/settings.json MCP configuration or the .env sourcing that the Flox hook provides. You’ll need to configure those steps manually.

​
Supported platforms

The Flox environment is tested on all four targets declared in manifest.toml:
PlatformArchitecture
macOSApple Silicon (aarch64-darwin)
macOSIntel (x86_64-darwin)
LinuxARM64 (aarch64-linux)
Linuxx86_64 (x86_64-linux)

Build docs developers (and LLMs) love

Get started for freeTalk to us