Installation Guide

Requirements

• Python 3.11 or newer. Earlier versions will fail at install time.
• An Anthropic API key. Free to create at console.anthropic.com. The free tier covers light use; a session costs roughly $0.03–0.10.
• Internet connection for igor chat (API calls). igor mbl and igor kb-info run offline.
• About 50 MB of disk space.

macOS

Option A — Homebrew Python (recommended)

If you don't have Homebrew: brew.sh has the one-liner install command.

# Check your current Python version first
python3 --version
# If it shows 3.11+ you can skip the brew install step

brew install python@3.12

# Confirm
python3.12 --version

Now download and install the agent:

# Download the zip from https://hypnosis.mikee.ai/download/
# (or right-click the Download button and Save Link As)

unzip ~/Downloads/igor-hypnosis-v0.1.0.zip
cd igor-hypnosis

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

pip install -e .

Option B — pyenv

pyenv lets you manage multiple Python versions cleanly and is the right choice if you work on multiple projects with different Python requirements.

brew install pyenv

# Add to your shell profile (~/.zshrc or ~/.bash_profile):
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# Restart your shell, then:
pyenv install 3.12.3
pyenv local 3.12.3   # sets version for this directory

cd igor-hypnosis
python -m venv .venv
source .venv/bin/activate
pip install -e .

Common macOS errors

xcrun: error: invalid active developer path

Run xcode-select --install and follow the prompts. Xcode Command Line Tools are required for compiling some Python packages.

pip install fails with SSL errors

Run /Applications/Python\ 3.x/Install\ Certificates.command (adjust the version number to match your install). This is a macOS-specific certificate issue.

The igor command is not found after install

The venv is probably not activated. Run source .venv/bin/activate — your prompt should show (.venv). You need to do this in every new terminal session.

Linux

Debian / Ubuntu

# Check Python version
python3 --version

# If you need 3.11+:
sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev

cd igor-hypnosis
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .

If Python 3.12 isn't in the default apt repos for your Ubuntu version, add the deadsnakes PPA first:

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.12 python3.12-venv

RHEL / Fedora / CentOS

sudo dnf install python3.12 python3.12-devel

cd igor-hypnosis
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .

On older RHEL/CentOS where dnf doesn't carry 3.12, use pyenv (same steps as macOS Option B above, substituting brew install pyenv with the pyenv installer script from github.com/pyenv/pyenv).

Arch Linux

sudo pacman -S python python-pip

cd igor-hypnosis
python -m venv .venv
source .venv/bin/activate
pip install -e .

Arch ships a recent Python by default — you almost certainly already have 3.11+.

Common Linux errors

ensurepip is not available

Install the python3.12-venv package (Debian/Ubuntu) or python3-devel (RHEL). The base Python package on many distros ships without pip support.

Permission denied when writing to .venv

Don't use sudo pip install. Create the venv in a directory you own (your home directory or the project folder) and activate it before installing.

Windows (native)

Native Windows works, but WSL2 (below) is significantly smoother for development work. Use native Windows if you specifically need it.

Install Python

Download the official installer from python.org/downloads or install from the Microsoft Store (search "Python 3.12"). During install, check "Add Python to PATH" — without this, nothing will work from the command line.

# In Command Prompt or PowerShell:
python --version
# Should show 3.12.x or similar

Clone and install

# Download the zip from https://hypnosis.mikee.ai/download/
# (or right-click the Download button and Save Link As)

unzip ~/Downloads/igor-hypnosis-v0.1.0.zip
cd igor-hypnosis

python -m venv .venv
.venv\Scripts\activate.bat   # Command Prompt
# OR
.venv\Scripts\Activate.ps1   # PowerShell

pip install -e .

Common Windows errors

python: command not found or 'python' is not recognized

Python was not added to PATH during install. Either re-run the installer and check that box, or add Python manually: Settings → System → Advanced system settings → Environment Variables → Path → add the folder containing python.exe.

PowerShell says "running scripts is disabled on this system"

Run PowerShell as Administrator and execute: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser. Then try activating the venv again.

pip install errors with long path names

Enable long paths: run regedit, navigate to HKLM\SYSTEM\CurrentControlSet\Control\FileSystem, set LongPathsEnabled to 1. Restart your terminal.

Windows WSL2 (recommended for Windows users)

WSL2 gives you a full Linux environment inside Windows. If you're going to do any serious development with this tool, this is the right setup.

Enable WSL2

# In PowerShell as Administrator:
wsl --install
# This installs Ubuntu by default. Restart when prompted.

After restart, open the Ubuntu app from the Start menu. It will finish setup and ask you to create a username and password.

Install Python in WSL2

sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev git

Clone and install

# Download the zip from https://hypnosis.mikee.ai/download/
# (or right-click the Download button and Save Link As)

unzip ~/Downloads/igor-hypnosis-v0.1.0.zip
cd igor-hypnosis

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .

Accessing your Windows files from WSL2

Your Windows drives are mounted at /mnt/c/, /mnt/d/, etc. However, for better performance, keep the project files inside the WSL2 filesystem (e.g. ~/projects/igor-hypnosis) rather than on the Windows drive.

Common WSL2 errors

WSL install fails with "Virtual Machine Platform" error

Enable virtualisation in your BIOS/UEFI. The exact option name varies by manufacturer (Intel VT-x, AMD-V, SVM Mode). Refer to your motherboard manual.

WSL2 can't connect to the internet

Try wsl --shutdown in PowerShell, then reopen Ubuntu. If that doesn't work, check your Windows Firewall isn't blocking WSL2 network adapters.

API key setup

There are two ways to provide your Anthropic API key. Use whichever fits your workflow.

Method 1 — .env file (recommended for local use)

cp .env.example .env

Open .env in a text editor and set:

ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

The agent loads this file automatically on startup. Never commit .env to version control — it's in .gitignore by default.

Method 2 — shell environment variable

# For the current session only:
export ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

# To persist across sessions, add to ~/.zshrc or ~/.bashrc:
echo 'export ANTHROPIC_API_KEY=sk-ant-api03-your-key-here' >> ~/.zshrc
source ~/.zshrc

On Windows (native), set it via System Properties → Environment Variables.

Getting a key

Create a free account at console.anthropic.com. Under "API Keys," create a new key and copy it immediately — it won't be shown again. The free tier provides enough credits for many sessions of learning use. Add a payment method if you plan to use it heavily.

First-run verification

With the venv activated and API key set, run:

igor kb-info

Expected output (approximately):

Igor Hypnosis Knowledge Base
=============================
Modules loaded: 22
Techniques indexed: 37
Language patterns: 68
MBL formula templates: 28
KB directory: /path/to/igor-hypnosis/kb/

All systems ready. Run `igor chat` to start a session.

If this looks good, try the offline MBL test:

igor mbl "stressed" "peaceful"

You should see a set of Mind-Bending Language questions immediately, with no API call needed.

Finally, start a session:

igor chat

The agent will greet you, ask for consent, and begin. Type stop at any point to end safely.

Optional: voice support

The agent can speak session content aloud and accept voice input using your system microphone. This requires additional dependencies.

pip install "igor-hypnosis[voice]"

Voice output uses your system's text-to-speech engine. Voice input uses openai-whisper for transcription (runs locally — no OpenAI account needed).

Platform notes

• macOS: Uses the built-in say command for TTS. Works immediately after install.
• Linux: Requires espeak-ng or festival: sudo apt install espeak-ng
• Windows / WSL2: TTS routes through the Windows Speech API. May require additional driver setup — check the voice troubleshooting entry.

Start a voice session with:

igor chat --voice

Optional: browser delivery

The browser delivery mode renders the session as a styled web interface in your default browser, with animated text output and a cleaner visual experience than the terminal.

pip install "igor-hypnosis[browser]"
playwright install chromium

The playwright install chromium step downloads a local Chromium binary (~130 MB). This only needs to be done once.

Start a browser session:

igor chat --browser

Your default browser will open automatically. The session runs in a local tab — no server, no internet required (beyond the API call to Anthropic).

Common errors

playwright: command not found after install

Make sure your venv is activated. Run python -m playwright install chromium as an alternative.

Browser opens but shows a blank page

Check your firewall isn't blocking localhost. The browser delivery uses a local port (default 7890). Try igor chat --browser --port 8080 to use a different port.