Troubleshooting

Common problems and how to fix them. Start here if something isn't working.

Installation Issues

MCP server not appearing in Claude Code

Symptom: After installing and configuring, /asciikit-* commands aren't available.

Common causes:

1. Config file has syntax errors
2. AsciiKit is in the wrong section of ~/.claude.json
3. Using project-specific config but running from different directory

Fix:

Step 1: Verify config file

Check ~/.claude.json exists and is valid JSON:

cat ~/.claude.json

Step 2: Check configuration location

For global configuration, AsciiKit must be under the root mcpServers:

{
  "mcpServers": {
    "asciikit": {
      "command": "asciikit-mcp",
      "env": {
        "ASCIIKIT_LICENSE_KEY": "..."
      }
    }
  }
}

NOT inside "projects":

{
  "projects": {
    "/some/path": {
      "mcpServers": {
        "asciikit": { ... }  ← Only works in this directory
      }
    }
  }
}

Step 3: Validate JSON syntax

Common mistakes:

• Missing commas between sections
• Missing quotes around strings
• Extra comma after last item

Copy your config and validate at jsonlint.com

Step 4: Start fresh session

Exit Claude Code and start a new session:

claude
/mcp

You should see asciikit in the list.

"command not found: asciikit-mcp"

Symptom: After running npm install -g asciikit-mcp, you get "command not found" when trying to run it.

Cause: npm's global bin directory isn't in your system PATH.

Fix:

Step 1: Find npm's global directory

npm config get prefix

This shows where npm installs global packages (e.g., /usr/local or ~/.npm-global).

Step 2: Add to PATH

On macOS/Linux:

Edit your shell config file:

# For zsh (default on macOS):
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# For bash:
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

On Windows:

1. Open System Properties → Environment Variables
2. Find "Path" in User variables
3. Add: C:\Users\YourUsername\AppData\Roaming\npm
4. Restart terminal

Step 3: Verify

asciikit-mcp --version

Should show the version number.

npm install fails with EACCES permission error

Symptom: npm install -g asciikit-mcp fails with permission errors.

Cause: npm doesn't have permission to write to global directory.

Fix (Option 1): Use npx (recommended)

npx -y asciikit-mcp@latest

This downloads and runs without global installation.

Update ~/.claude.json to use npx:

{
  "mcpServers": {
    "asciikit": {
      "command": "npx",
      "args": ["-y", "asciikit-mcp@latest"],
      "env": {
        "ASCIIKIT_LICENSE_KEY": "your_key_here"
      }
    }
  }
}

Fix (Option 2): Fix npm permissions (one-time setup)

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g asciikit-mcp

License Issues

"Invalid license key" error

Symptom: MCP server fails to start with "Invalid license key" error.

Common causes:

1. License key is wrong
2. Extra spaces or line breaks in config
3. Missing quotes around license key

Fix:

Step 1: Verify license key format

License keys look like:

• Trial: ak_trial_ + 32 hex characters
• Paid: ak_live_ + 32 hex characters

Example: ak_trial_a1b2c3d4e5f6789012345678901234567

Step 2: Check config file

Open ~/.claude.json and verify:

{
  "mcpServers": {
    "asciikit": {
      "command": "asciikit-mcp",
      "env": {
        "ASCIIKIT_LICENSE_KEY": "ak_trial_a1b2c3d4..."
      }
    }
  }
}

✅ License key is in quotes ✅ No extra spaces before/after ✅ Correct env variable name: ASCIIKIT_LICENSE_KEY

Step 3: Copy license key from email

Don't retype - copy-paste directly from your trial/purchase email to avoid typos.

Step 4: Test manually

export ASCIIKIT_LICENSE_KEY="your_key_here"
asciikit-mcp --version

If this works, the issue is in your config file.

"License validation failed: Network error"

Symptom: License validation fails with network error.

What this means: The license API couldn't be reached, but you can still use AsciiKit.

Why it works: For network failures, AsciiKit "fails open" to avoid blocking you due to temporary connectivity issues. Your existing usage continues normally.

When to worry: If this message persists for days, there may be a network configuration issue on your side.

Fix:

Step 1: Check internet connection

Make sure you're online.

Step 2: Test API access

curl https://asciikit-license-api.currently-studio.workers.dev/health

Should return: {"status":"ok"}

If this fails, check:

• Firewall blocking Cloudflare domains
• VPN/proxy interfering
• Corporate network restrictions

Step 3: Check Claude Code network settings

Claude Code needs internet access for license validation. Check that it's not blocked by:

• Firewall rules
• Antivirus software
• Network security policies

Step 4: Try again later

Temporary server issues happen. Wait 5-10 minutes and try again.

"Trial usage limit exceeded"

Symptom: After using trial for a while, validation fails with "usage limit exceeded".

Cause: You've used all 10 trial uses.

What this means:

Trial licenses have 10 command uses. Each time you generate a wireframe, that counts as 1 use.

To check your usage:

Email hello@asciikit.com with your license key (or email address) and we'll tell you how many uses remain.

Solutions:

1. Subscribe for unlimited use: Visit asciikit.com

   • Monthly: $19/month
   • 3-Month: $49
   • Yearly: $149

2. Contact support: If you hit the limit quickly and want to discuss options, email hello@asciikit.com

Usage Issues

I see messy tool output while Claude is designing

Symptom: While Claude works, you see lines like:

⏺ asciikit - get_design_intelligence (MCP)(domain: "health", ...)
  ⎿  { "context_summary": "...", "psychology": { ... +172 lines

⏺ asciikit - validate_wireframe (MCP)(wireframe: "┌────\n│...")
  ⎿  ✓ Auto-fixed width issues. Use this corrected version:

This is completely normal! This is Claude Code showing MCP tool activity as Claude works. You're seeing the intelligence frameworks in action:

• Design psychology being analyzed
• Wireframes being validated and auto-corrected
• Multiple design options being generated

Why it looks messy:

• Wireframe parameters show \n escape characters for line breaks
• Long JSON responses get collapsed (… +172 lines (ctrl+o to expand))
• Multiple validation passes create visual noise

The good news:

• ✅ Final wireframes are always clean and perfectly formatted
• ✅ This proves the intelligence is real - you're seeing the "design kitchen"
• ✅ You can safely ignore the tool output and focus on the final designs

Can I hide this output?

No - this is how Claude Code renders all MCP tool calls. It's like watching a designer think through user psychology, cognitive science, and accessibility before presenting their work. The process looks messy, but the results are polished.

Pro tip: Think of it as proof the intelligence isn't fake - you're literally watching 6 psychological frameworks analyze your requirements in real-time.

Claude doesn't apply appropriate psychology

Symptom: Claude generates wireframes that don't match the psychological context you described.

Cause: Prompt might lack sufficient user context, emotional state, or domain information.

Fix:

Be more specific about user context:

❌ "I need a dashboard" ✅ "I need a dashboard for anxious first-time investors showing their portfolio status"

Include emotional and cognitive context:

❌ "I need a checkout form" ✅ "I need a checkout form that builds trust for skeptical users making their first purchase"

Describe user goals and psychological state:

❌ "I need a modal with buttons" ✅ "Users need reassurance before deleting their account permanently - they're anxious about data loss"

See Writing Effective Prompts for more tips.

Wireframes are wrong width (not 38 characters)

Symptom: Generated wireframes aren't the standard 38-character width.

Cause: Claude occasionally generates custom-sized wireframes.

Fix:

Tell Claude to fix it:

Please regenerate this at 38 characters wide (A2 format)

Claude knows the A2 standard and will correct it.

Claude generates code instead of wireframes

Symptom: Claude gives you React/HTML code instead of ASCII wireframes.

Cause: Prompt sounded like you wanted code implementation.

Fix:

Be clear you want wireframes:

Show me an ASCII wireframe for [your goal]

Or use the specialized workflows:

• /asciikit-quick for single screens
• /asciikit-flow for multi-screen flows

Design doesn't match my psychological intent

Symptom: Claude generated a design but it doesn't feel right for your specific context.

Cause: The psychological context wasn't specific enough in the prompt.

Fix:

Option 1: Describe what's wrong emotionally

This feels too aggressive — the users are anxious and this
will increase their anxiety, not reduce it

Claude will recalibrate the psychology.

Option 2: Add more user context

Actually, these are elderly users with technology anxiety —
they need much simpler layout and visible phone support

Claude applies the appropriate user segment psychology.

Option 3: Ask for alternative approaches

Show me 2 other psychological approaches to this same problem

Performance Issues

Claude takes a long time to generate wireframes

Symptom: Long delay before Claude shows wireframes.

Cause: This is typically a Claude Code or network issue, not AsciiKit.

Possible issues:

1. Slow internet connection (affects license validation)
2. Claude Code itself is slow (unrelated to AsciiKit)
3. Very complex prompt triggering extensive reasoning

Fix:

Check if it's AsciiKit or Claude:

Try a regular Claude request (no wireframes). If that's also slow, it's not AsciiKit.

For first-run slowness:

The first wireframe request loads patterns into memory. Subsequent requests are faster.

For persistent slowness:

1. Restart Claude Code
2. Check your internet connection
3. Close other heavy applications

Claude timeout errors

Symptom: Claude times out while generating wireframes.

Cause: Extremely complex requests might take too long.

Fix:

Break it down:

Instead of: "Show me a complete e-commerce site with 20 screens"

Try: "Show me the checkout flow" (get 3-4 screens)

Then: "Show me the product browsing flow" (get more screens)

Use the right workflow:

• Quick Screen: Single screens (fast)
• Flow Mapping: 3-8 screens (medium)
• App Specification: Full app structure (slower, but comprehensive)

License API Issues

"License API is unavailable"

Symptom: Validation fails with API unavailable message.

Cause: License API server is down (rare) or unreachable.

Fix:

Step 1: Check status

Visit status.asciikit.com (if available) or check Twitter @asciikit for status updates.

Step 2: Test directly

curl https://asciikit-license-api.currently-studio.workers.dev/health

If this fails, the API is down.

Step 3: Wait and retry

Cloudflare Workers have 99.99% uptime. Issues are usually resolved within minutes.

Step 4: Contact support

If it persists >1 hour: hello@asciikit.com

Config File Issues

"Failed to parse config file"

Symptom: Claude Code shows error about config file.

Cause: JSON syntax error in ~/.claude.json.

Fix:

Step 1: Validate JSON

1. Open your config file
2. Copy entire contents
3. Paste into jsonlint.com
4. Fix any errors it shows

Common JSON mistakes:

// ❌ Missing comma
{
  "mcpServers": {
    "asciikit": {
      "command": "asciikit-mcp"  // Missing comma here!
      "env": {
        "ASCIIKIT_LICENSE_KEY": "..."
      }
    }
  }
}

// ✅ Correct
{
  "mcpServers": {
    "asciikit": {
      "command": "asciikit-mcp",  // Comma added
      "env": {
        "ASCIIKIT_LICENSE_KEY": "..."
      }
    }
  }
}

// ❌ Extra comma at end
{
  "mcpServers": {
    "asciikit": {
      "command": "asciikit-mcp",
      "env": {
        "ASCIIKIT_LICENSE_KEY": "...",  // Extra comma!
      }
    }
  }
}

// ✅ Correct - no comma after last item
{
  "mcpServers": {
    "asciikit": {
      "command": "asciikit-mcp",
      "env": {
        "ASCIIKIT_LICENSE_KEY": "..."
      }
    }
  }
}

Advanced Configuration

Developer Mode (For Testing)

If you're developing with AsciiKit, testing integrations, or contributing to the project:

Enable dev mode:

export ASCIIKIT_DEV=true
asciikit-mcp

Or in your ~/.claude.json:

{
  "mcpServers": {
    "asciikit": {
      "command": "asciikit-mcp",
      "env": {
        "ASCIIKIT_DEV": "true",
        "ASCIIKIT_LICENSE_KEY": "your_key_here"
      }
    }
  }
}

What dev mode does:

• Bypasses license validation
• Still tracks usage count (for testing)
• No API calls made
• Logs additional debug information

Not for production use.

Custom License API URL (Enterprise)

For enterprise users with internal proxies or custom license servers:

{
  "mcpServers": {
    "asciikit": {
      "command": "asciikit-mcp",
      "env": {
        "ASCIIKIT_LICENSE_KEY": "your_key_here",
        "ASCIIKIT_LICENSE_API_URL": "https://your-proxy.example.com"
      }
    }
  }
}

This overrides the default license API endpoint. Contact hello@asciikit.com for enterprise licensing options.

Still stuck?

If none of these solutions work:

1. Check the FAQ: /docs/faq
2. Email support: hello@asciikit.com
3. Report a bug: GitHub Issues

When contacting support, include:

• Your operating system (macOS/Windows/Linux)
• Claude Code version
• Node.js version (node --version)
• License key (first 20 characters only: ak_trial_a1b2c3d4...)
• Error message (exact text or screenshot)
• What you were trying to do

This helps us debug faster!