Troubleshooting

The agent can't find your API key. There are two ways to set it:

Method 1 — .env file (easiest):

cp .env.example .env
# then open .env in a text editor and add:
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

Method 2 — shell export (lasts for the current terminal session):

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

To make it permanent, add that export line to your ~/.zshrc or ~/.bashrc and run source ~/.zshrc.

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

After setting it, run igor kb-info to confirm the agent can start up without errors before trying igor chat.

Python isn't installed or isn't on your PATH.

• macOS/Linux: Follow the macOS or Linux install steps. On Ubuntu, sudo apt install python3.12 python3.12-venv is the quick fix.
• Windows: Download Python from python.org and re-run the installer. On the first screen, check "Add Python to PATH" before clicking Install.

After installing, close and reopen your terminal, then try python --version again.

The virtual environment isn't activated. The igor command only exists inside the venv.

# macOS / Linux / WSL2:
source .venv/bin/activate

# Windows Command Prompt:
.venv\Scripts\activate.bat

# Windows PowerShell:
.venv\Scripts\Activate.ps1

Your prompt should show (.venv) at the left when the venv is active. You need to activate it in every new terminal session — it doesn't persist automatically.

If you get a PowerShell execution policy error, see the Windows install section.

The agent requires Python 3.11 or newer. Check your version:

python --version
python3 --version

If you're below 3.11, install a newer version. On macOS: brew install python@3.12. On Ubuntu: use the deadsnakes PPA (see Linux install guide). Then recreate your venv with the new Python binary explicitly:

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

The knowledge base JSON files aren't loading. Run:

igor kb-info

If the output shows Modules loaded: 0 or errors about missing files, the kb/ directory is either missing or in the wrong location.

Check that you're running igor from inside the project directory (where kb/ lives), or pass the path explicitly:

igor chat --kb-dir /absolute/path/to/igor-hypnosis/kb

If the kb/ directory is genuinely empty, re-clone or re-download the repository — the knowledge base files should be included.

The igor mbl command uses a verbify helper to turn noun-form problems into verb phrases. If you give it a noun like "anxiety" the output may be less natural than if you give it a verb phrase like "being anxious" or a gerund like "feeling anxious".

# Less natural:
igor mbl "anxiety" "calm"

# More natural:
igor mbl "feeling anxious" "feeling calm"
igor mbl "being overwhelmed" "being grounded"

You can also adjust the verbify helper directly in igor/mbl.py — the function is called verbify() and is simple enough to modify. Pull requests welcome.

Session prose length is influenced by the executor's temperature and max-token settings. These are set in igor/config.py:

# For longer, more elaborate prose:
EXECUTOR_MAX_TOKENS = 800   # default: 400
EXECUTOR_TEMPERATURE = 0.9  # default: 0.7

# For shorter, tighter prose:
EXECUTOR_MAX_TOKENS = 200
EXECUTOR_TEMPERATURE = 0.5

The course material (particularly Modules 3–4 on hypnotic language) notes that quality of attention direction matters more than length — resist the urge to crank tokens up indefinitely. More words don't automatically mean more hypnotic impact.

This is a planner state issue. The planner model tracks which PCAT phase the session is in, and occasionally misclassifies the transition. To inspect the current planner state mid-session, open a second terminal and run:

igor session-state --db-path .igor/igor.db

This prints the current session's phase, the classified problem (P), and the classified resource (R). If P or R is blank or wrong, the planner is working from bad parameters — the session took a tangent before they were established. Starting a fresh session with a clearer initial statement usually resolves this. If it recurs, the planner prompt in igor/planner.py may need tuning for your style of initial input.

Set the environment variable:

export IGOR_INSTANT_OUTPUT=1
igor chat

Or add it to your .env file:

IGOR_INSTANT_OUTPUT=1

This disables the character-by-character typing animation and prints full responses immediately. Useful for testing, debugging, and when you just want to read fast.

You've hit Anthropic's rate limit for your account tier. Options:

• Wait 30–60 seconds and retry — the rate limit resets on a rolling window.
• Add a payment method to your Anthropic account to increase your rate limit tier.
• Switch to a lighter model: in igor/config.py, set EXECUTOR_MODEL = "claude-haiku-3-5". Haiku is faster, cheaper, and has higher rate limits — the prose quality is slightly lower but perfectly serviceable for learning.

If you're hitting rate limits during normal single-session use (not bulk testing), something may be causing excessive API calls — check that no loop is running in the background.

The crisis detection is regex-based and intentionally conservative. It triggers on phrases that pattern-match to self-harm or suicidal ideation, even if the context is clearly casual or metaphorical (e.g., "I could kill for a coffee right now").

This is expected behaviour — erring on the side of interrupting unnecessarily is safer than missing a genuine distress signal. The agent is not making a judgment about you; it's responding to a pattern match.

If you want to test or demo the agent without triggering this, rephrase the input to avoid the matched patterns. A future version may allow context-aware override for clearly figurative language. For now, the conservative setting stays.

If you triggered it genuinely and something is difficult: the ethics page has crisis line numbers.

Set the planned environment flag:

IGOR_SKIP_CONSENT=1

Note: This flag is not yet implemented in the current release — it is documented here as a planned feature. In the meantime, you can pass --yes to auto-accept the consent prompt in test mode:

igor chat --yes

Do not use this flag in any context where a real person is the session subject. The consent flow exists for good reason. See the ethics page.

Every session is written to SQLite in real time at .igor/igor.db. If the session crashes (API timeout, network drop, keyboard interrupt), the transcript up to that point is preserved.

To resume or review:

igor sessions list           # show recent sessions
igor sessions view --id N    # print transcript for session N

You cannot automatically resume a mid-session trance state — that would require the client to re-enter trance. However, reviewing the transcript lets you pick up the thread: you can see what phase was reached and what the planner's last state was, then start a new session from that point.

After a crash, always take a moment to reorient yourself before doing anything else. Type "stop" if the session was still running in any sense when it crashed.

Another igor process has the database open. This usually means a session is running in another terminal window, or a previous session didn't close cleanly.

# Find the other process:
ps aux | grep igor

# Kill it if needed:
kill <PID>

SQLite only allows one writer at a time. If you want to run multiple concurrent sessions (e.g., for testing), pass different --db-path values to each session so they use separate database files.

Every session transcript is stored in full. After many sessions, the database can grow to tens or hundreds of megabytes. To archive old sessions:

igor sessions archive --before 2025-01-01

This moves sessions older than the given date to a compressed archive file and removes them from the active database. The archive is kept in .igor/archive/ and can be restored if needed.

You can also just delete .igor/igor.db entirely if you don't need the history — the agent will create a fresh database on next run.

The voice dependencies aren't installed. Run:

pip install "igor-hypnosis[voice]"

If you still get errors:

• Linux: Install the system TTS engine: sudo apt install espeak-ng (Ubuntu/Debian) or sudo dnf install espeak-ng (Fedora).
• macOS: The built-in say command should work automatically. If it doesn't, check System Preferences → Accessibility → Spoken Content.
• WSL2: Audio output from WSL2 requires PulseAudio or PipeWire configured to forward to the Windows host. This is a known WSL2 limitation. The easiest workaround is to use the native Windows install for voice sessions.

Two-step install required:

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

The second command downloads a local Chromium binary (~130 MB). It only needs to run once. If playwright isn't found after the pip install, try python -m playwright install chromium.

If the browser opens but the page is blank or stuck on "connecting," check that nothing is blocking localhost traffic on port 7890. Try igor chat --browser --port 9000 to use a different port.

Local LLM support is not officially maintained, but the architecture makes it possible. Both the Planner and Executor are Python classes with a single generate(prompt: str) -> str method. To swap in a local model, subclass either (or both) and override that method:

from igor.planner import Planner

class OllamaPlanner(Planner):
    def generate(self, prompt: str) -> str:
        import requests
        resp = requests.post(
            "http://localhost:11434/api/generate",
            json={"model": "llama3", "prompt": prompt, "stream": False}
        )
        return resp.json()["response"]

Then pass your subclass when constructing the session runner. The quality of the session will depend heavily on your local model's instruction-following ability — models smaller than ~13B parameters tend to lose track of the therapeutic structure. Mistral 7B and Llama 3 8B are workable for the Executor; the Planner needs reliable JSON output so a model that follows structured output instructions is essential.

This is unsupported territory — file issues on GitHub if you find something that helps others.