$50 OFF · First 100 buyers

Troubleshooting

Solutions for common issues, organized by category. If your problem isn't listed here, check your platform-specific guide:

Claude Code · Cursor Agent · Codex · Gemini CLI · OpenCode

Installation & setup

Skill not recognized after installation

  • Verify you're on the latest version of Claude Code, Cursor Agent, 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

Installation failed or incomplete

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

Command errors

/ideatwister command not found

  • 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

Skill not found (CLI platforms)

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

Runtime issues

Run times out or gets stuck

  • Interrupt the run (Ctrl+C or Cmd+C)
  • Check your network connection - the web research phase requires internet
  • Try a smaller depth mode (e.g. Quick or Standard) to confirm the install works end to end
  • Re-run the command on a fresh slug; if the issue persists, generate a support bundle (/ideatwister support-bundle) and email hello@ideatwister.com

Run completes but no dashboard generated

  • 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

High memory or CPU usage during run

  • 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 the variation generation and validation phases
  • If your machine struggles, try a lighter depth mode (Quick or Standard) on the next run

Data & storage

Data store not initialized error

Run the init script for your platform:

# Claude Code
~/.claude/skills/ideatwister/scripts/init-store.sh

# CLI platforms (Cursor Agent, Codex, Gemini, OpenCode)
~/.agents/skills/ideatwister/scripts/init-store.sh

Then restart your app or terminal.

Permission denied on ~/.ideatwister/

chmod -R u+w ~/.ideatwister/

If that doesn't work:

sudo chown -R $(whoami) ~/.ideatwister/

Can't see past runs

ls -la ~/.ideatwister/runs/

Then 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 whether they're in a different user directory (multi-user systems).

Platform-specific issues

Claude Code: dashboard doesn't open automatically

  • Copy the printed path
  • Open it manually:
open ~/.ideatwister/runs/{slug}/dashboard.html

This usually works on macOS and Linux; on Windows you may need to open the path manually in your browser.

Cursor Agent: can't open dashboard

Cursor Agent doesn't auto-open browsers. Copy the path from chat output and paste it in your browser address bar:

file:///Users/<username>/.ideatwister/runs/{slug}/dashboard.html

CLI platforms (Codex, Gemini, OpenCode): symlink not working

Verify the 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

Then restart your terminal.

Web search & research

Web search phase fails or skips

  • This is normal if you're offline - the 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

Web search returns "0 searches" (Claude Code + OpenRouter)

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.

Variations seem generic or lack research

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

API & environment

AI provider rate limits (429 errors)

  • IdeaTwister is intensive; you may hit rate limits on lower-tier API plans
  • Wait 5–10 minutes, then start a fresh run
  • Try a lighter depth mode (Quick or Standard) which makes fewer calls
  • Consider upgrading your AI provider tier for higher throughput

Missing system dependencies

  • 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

Slash-commands not resolving

  • 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

General tips

1. Check permissions

Many issues stem from directory permissions. Try:

chmod -R u+w ~/.ideatwister

2. Restart everything

Many issues clear after restarting your AI tool, your terminal, or your machine. Try this first.

3. Verify installation

Check that the skill actually installed:

ls -la ~/.claude/skills/ideatwister/

Should show files. If empty, reinstall.

4. Check internet connection

Web research (Phase 2) requires internet. If your connection is unstable or slow, runs may time out or data may be incomplete.

5. Pick a lighter depth mode if you're debugging

If you're trying to confirm an install works or chasing down a runtime issue, run with Quick mode first (~5 minutes). It's the fastest way to validate the full pipeline end to end without burning through 25–50 minutes of API spend.

Still stuck?

Run /ideatwister support-bundle to generate a self-contained ZIP of logs and configuration (excludes your idea text by default). Email hello@ideatwister.com with the bundle attached. We respond to support email within two business days.