🆘 Troubleshooting & FAQ Guide

🆘 Troubleshooting & FAQ Guide

**🌟 Created by SenaiVerse** *Claude Code Agent System for Expo/React Native Development*

---

**Your complete reference for solving common issues and understanding the Claude Code Agent System**

---

📋 Table of Contents

undefined

---

🚨 Critical Issues & Fixes

❌ Problem: "Agent not found" error

**Symptoms:**

Error: Agent 'design-token-guardian' not found
Unable to invoke @design-token-guardian

**Root Causes & Fixes:**

Cause	How to Verify	Fix
Agent not installed	ls ~/.claude/agents/	Run install-agents.ps1
Wrong agent name	Check exact name in file	Use @design-token-guardian (not @design-guardian)
File in wrong location	Check path	Move to ~/.claude/agents/tier-1-daily/
YAML frontmatter error	Open .md file	Verify name: matches exactly

**Step-by-Step Fix:**

# 1. Verify agents directory exists
ls ~/.claude/agents/

# 2. Check specific agent file
cat ~/.claude/agents/tier-1-daily/design-token-guardian.md

# 3. Verify YAML frontmatter
# Should see:
# ---
# name: design-token-guardian
# description: ...
# ---

# 4. If missing, re-run installer
cd ~/claude-code-expo-system/scripts
.\install-agents.ps1

---

❌ Problem: Claude Code command not recognized

**Symptoms:**

PS> claude
claude : The term 'claude' is not recognized...

**Root Cause:** Claude Code not installed or not in PATH

**Fix:**

# Option 1: Install Claude Code globally
npm install -g @anthropic-ai/claude-code

# Option 2: Verify installation
where.exe claude

# Option 3: If installed but not in PATH, add to PATH
# Windows: Add npm global folder to PATH
# Find npm global folder:
npm config get prefix
# Example: C:\Users\Senai\AppData\Roaming\npm

# Add to PATH in System Environment Variables

**Verification:**

claude --version
# Should output: 2.0.5 (or your version)

---

❌ Problem: Permission Denied (Windows)

**Symptoms:**

.\install-agents.ps1 : File cannot be loaded because running scripts is disabled...

**Fix:**

# Run PowerShell as Administrator
# Then run:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# Verify:
Get-ExecutionPolicy
# Should show: RemoteSigned

# Now retry installation
.\install-agents.ps1

---

❌ Problem: Agents not auto-invoking

**Symptoms:**

undefined