Install Felix and connect Claude Code

1. Clone and install

# Clone the repository
git clone https://github.com/felix-ide/felix.git
cd felix

# Install dependencies (setup runs automatically via postinstall)
npm install

# The setup script will:
# - Verify Node.js and Python versions
# - Create Python virtual environment
# - Install Python dependencies
# - Download ~90MB embedding model (sentence-transformers/all-MiniLM-L6-v2)
# - Download TextMate grammars for syntax highlighting
# - Check Tree-sitter native parsers

2. Start Felix

# Start the full stack (server + client + MCP)
npm run dev

# Server runs on http://localhost:9000
# Open your browser to http://localhost:9000 to view the UI

MCP Server Configuration

Start Felix with npm run dev (server runs on port 9000), then connect it to Claude Code.

Option 1: Using Claude Code CLI (Recommended)

The easiest way to add Felix as an MCP server with HTTP Streaming:

claude mcp add felix --transport http http://localhost:9000/mcp --scope user

This command automatically configures Felix in your Claude Code settings.

Option 2: Manual Configuration File

Alternatively, manually edit your Claude Code settings file. The location depends on your system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add Felix to the mcpServers section:

For HTTP Streaming (recommended):

{
  "mcpServers": {
    "felix": {
      "type": "http",
      "url": "http://localhost:9000/mcp"
    }
  }
}

For SSE (legacy):

{
  "mcpServers": {
    "felix": {
      "type": "sse",
      "url": "http://localhost:9000"
    }
  }
}

Restart Claude Code/Desktop. Felix MCP tools will appear in the tool list. The AI can now search code, create tasks, manage workflows, and link documentation.

Hook Integration (Automatic Rule Injection)

Run the installer to set up hooks that inject rules and validate workflows:

cd integrations/claude-code
bash install.sh

# The installer will:
# - Copy hook scripts to ~/.claude/hooks/
# - Update ~/.claude/settings.json with hook configuration
# - Prompt for your project path and server URL
# - Create ~/.felix_claude_config with environment variables
# - Test the connection to Felix server

After installation, hooks run automatically when you use Claude Code:

# Server configuration
PORT=9000
FELIX_DATA_DIR=~/.felix
LOG_LEVEL=info
DISABLE_FILE_WATCHER=false

# Python sidecar
SIDECAR_BIND_HOST=127.0.0.1
SIDECAR_BIND_PORT=8088
SIDECAR_DEVICE=auto  # auto|cuda|mps|cpu
SIDECAR_FP16=true
SIDECAR_ALLOW_MOCK=false
MODEL_NAME=sentence-transformers/all-MiniLM-L6-v2