Troubleshooting

Solution:

• •Verify you're on the latest version of Claude Code, Cursor, or your platform
• •Restart your AI assistant completely (not just the chat)
• •Check that you have Node.js (v18+) and Python (v3.10+) installed
• •Verify the zip file was extracted fully and no files are missing

Solution:

• •Restart the application after attempting install
• •Try manual installation if the install script fails (see platform-specific guides)
• •Check you have sufficient disk space (~500MB)
• •Verify internet connection is stable during install

Solution:

• •Restart your AI tool or terminal completely
• •Verify the skill is correctly registered in your AI assistant's settings
• •Check the installation completed without errors (see logs if available)
• •Try the manual installation process (symlink or git clone) for your platform

Solution:

• •Check the symlink exists:
• $ls -la ~/.agents/skills/ideatwister
• •If missing, recreate it (see platform guide)
• •Verify the ~/.ideatwister directory has read/write permissions:
• $chmod -R u+w ~/.ideatwister

Solution:

• •Interrupt the run (Ctrl+C or Cmd+C)
• •Re-run the same command: /ideatwister list
• •IdeaTwister saves checkpoints after each phase and will resume
• •If still stuck after resume, check your network connection (web research phase requires internet)
• •Try again in a few minutes (temporary network issues may have caused the hang)

Solution:

• •Check the terminal/chat output for the dashboard path
• •Verify ~/.ideatwister/runs/ exists and has subdirectories:
• $ls -la ~/.ideatwister/runs/
• •Look for the run slug (e.g., remote-accountant-job-board-2026-04-24)
• •Open the path manually in your browser:
• $open ~/.ideatwister/runs/{slug}/dashboard.html

Solution:

• •This is normal - IdeaTwister is doing a lot of work in parallel
• •Close other applications to free up resources
• •Runs typically use 2–4GB RAM temporarily during phases 3–5
• •If your machine crashes, restart and re-run - it will resume from the last checkpoint

Solution:

• •Run the init script for your platform:
• •For Claude Code: ~/.claude/skills/ideatwister/scripts/init-store.sh
• •For CLI platforms: ~/.agents/skills/ideatwister/scripts/init-store.sh
• •Then restart your app/terminal

Solution:

• •Fix permissions:
• $chmod -R u+w ~/.ideatwister/
• •If that doesn't work, try:
• •sudo chown -R $(whoami) ~/.ideatwister/

Solution:

• •Check the runs exist:
• $ls -la ~/.ideatwister/runs/
• •Run /ideatwister list to see all runs
• •Runs are shared across all platforms - if you switch platforms, past runs should still be visible
• •If runs disappeared, check if they're in a different user directory (multi-user systems)

Solution:

• •Copy the printed path
• •Open it manually:
• $open ~/.ideatwister/runs/{slug}/dashboard.html
• $This usually works on macOS/Linux but may require manual opening on Windows

Solution:

• $Cursor doesn't auto-open browsers. Copy the path from chat output
• •Paste it in your browser address bar:
• •file:///Users/username/.ideatwister/runs/{slug}/dashboard.html

Solution:

• •Verify symlink:
• $ls -la ~/.agents/skills/ideatwister
• •If the symlink is broken (shows red in ls):
• •rm -f ~/.agents/skills/ideatwister
• •cp -r /path/to/ideatwister-engine/skills/ideatwister ~/.agents/skills/ideatwister
• •Restart terminal

Solution:

• •This is normal if you're offline - pipeline continues without research
• •Check your internet connection
• •Verify your API provider credentials are configured (Claude API key, Google credentials, etc.)
• •Try running again - temporary network issues may have caused failure

Solution:

• •This occurs when using Claude Code with non-Anthropic providers like OpenRouter.
• •The native WebSearch tool is proprietary to Anthropic and doesn't work with custom providers.
• •Solution A (Recommended): Add a Search MCP Server. Get a free Brave Search API key and run:
• •claude mcp add brave-search npx -y @modelcontextprotocol/server-brave-search
• •Solution B: Switch to official Anthropic models (e.g., Claude Sonnet 4.x) via your Anthropic account.

Solution:

• •This happens if the web search phase failed (see above)
• •Variations still get scored and should be viable

Solution:

• •IdeaTwister is intensive; you may hit rate limits on lower-tier API plans
• •Wait 5–10 minutes and re-run to resume from the last checkpoint
• •Consider upgrading your AI provider tier for higher throughput

Solution:

• •Ensure Node.js v18 or newer is installed: node -v
• •Ensure Python v3.10 or newer is installed: python3 --version
• •On Windows, ensure you are using PowerShell 7+ or WSL2

Solution:

• •Verify the SKILL.md file is in the root of the skill directory
• •Ensure your AI assistant has permission to read the skill directory
• •Check for path resolution errors in the terminal logs