Troubleshooting Guide

Common issues and solutions for Claude Code Tresor.

Installation Issues

Permission Denied Error

Error:

Permission denied: ./scripts/install.sh

Solution:

# Make script executable
chmod +x ./scripts/install.sh

# Run installation
./scripts/install.sh

Script Not Found Error

Error:

./scripts/install.sh: No such file or directory

Solution:

# Verify you're in repository root
pwd  # Should show: .../claude-code-tresor

# If not in correct directory
cd /path/to/claude-code-tresor

# If directory doesn't exist, re-clone
git clone https://github.com/alirezarezvani/claude-code-tresor.git
cd claude-code-tresor
./scripts/install.sh

Installation Incomplete

Problem: Some components missing after installation

Solution:

# Check what was installed
ls ~/.claude/skills/
ls ~/.claude/agents/
ls ~/.claude/commands/

# Re-run installation with specific flags
./scripts/install.sh --skills    # Install skills only
./scripts/install.sh --agents    # Install agents only
./scripts/install.sh --commands  # Install commands only

# Or full reinstall
./scripts/install.sh

Skill Issues

Skills Not Activating

Problem: Skills installed but not providing suggestions

Checklist:

✅ Restart Claude Code CLI
✅ Verify skill installed: ls ~/.claude/skills/code-reviewer/
✅ Check configuration: cat ~/.claude/skills/code-reviewer/SKILL.md
✅ Verify enabled: true in configuration
✅ Check trigger keywords match your workflow

Debug Steps:

# Enable debug mode
export CLAUDE_CODE_DEBUG=true

# Restart Claude Code
claude

# Check skill logs (if available)
cat ~/.claude/logs/skills.log

Skill Triggers Wrong Files

Problem: Skill activating for files it shouldn't

Solution: Edit skill configuration to exclude files:

---
name: "code-reviewer"
exclude_patterns:
  - "node_modules/**"
  - "dist/**"
  - "*.test.ts"
  - "*.min.js"
---

Save and restart Claude Code.

Too Many Skill Suggestions

Problem: Overwhelming number of suggestions

Solution 1: Reduce Skill Priority

---
name: "code-reviewer"
priority: "low"  # Changed from "high"
---

Solution 2: Disable Non-Essential Skills

---
name: "readme-updater"
enabled: false  # Temporarily disable
---

Solution 3: Narrow File Patterns

---
name: "test-generator"
file_patterns:
  - "src/**/*.ts"  # Only src directory
exclude_patterns:
  - "src/**/*.test.ts"  # Exclude existing tests
---

Skill Missing Dependencies

Problem: Skill fails with "dependency not found"

Solution:

# Check skill requirements in SKILL.md
cat ~/.claude/skills/security-auditor/SKILL.md

# Install missing dependencies (example for Node.js)
npm install -g eslint  # If ESLint required

# Restart Claude Code

Agent Issues

Agent Not Found

Error:

@code-reviewer not found

Solution:

# Verify agent exists
ls ~/.claude/agents/code-reviewer/

# Check agent configuration
cat ~/.claude/agents/code-reviewer/SKILL.md

# Verify name field matches
grep "name:" ~/.claude/agents/code-reviewer/SKILL.md

# If missing, reinstall
./scripts/install.sh --agents

# Restart Claude Code

Agent Fails to Execute

Problem: @agent-name invoked but fails

Debug Steps:

# Check agent configuration is valid
cat ~/.claude/agents/code-reviewer/SKILL.md

# Verify tools are available
# Tools like Bash, Task should be accessible

# Enable debug mode
export CLAUDE_CODE_DEBUG=true

# Try simpler invocation
# Instead of: @code-reviewer analyze entire codebase
# Try: @code-reviewer analyze this file

Agent Times Out

Problem: Agent takes too long and times out

Solution:

---
name: "code-reviewer"
max_iterations: 100  # Increase from default 50
timeout: 600         # Increase timeout to 10 minutes
---

Or reduce scope:

# Instead of analyzing entire codebase
@code-reviewer analyze src/components/UserProfile.tsx

# Break into smaller tasks
@code-reviewer analyze security issues only

Agent Gives Generic Responses

Problem: Agent provides vague, unhelpful answers

Solution:

Bad invocation (too vague):

@code-reviewer review this

Good invocation (specific):

@code-reviewer analyze src/api/auth.controller.ts for:
1. Security vulnerabilities (OWASP Top 10)
2. Input validation issues
3. Error handling gaps
4. Authentication/authorization flaws

Provide context:

@code-reviewer
Context: Production API serving 10k requests/minute
Review: src/api/payment.controller.ts
Focus: Race conditions, transaction safety, error recovery

Command Issues

Command Not Recognized

Error:

/review: command not found

Solution:

# Verify command exists
ls ~/.claude/commands/review/

# Check command configuration
cat ~/.claude/commands/review/command.json

# Verify enabled
grep "enabled" ~/.claude/commands/review/command.json

# If missing, reinstall
./scripts/install.sh --commands

# Restart Claude Code

# Try full path
/workflow/review --scope staged

Command Fails with Invalid Parameters

Error:

/review --invalid-option: parameter not recognized

Solution:

# Check command help
/review --help

# View valid parameters
cat ~/.claude/commands/review/command.json

# Use correct syntax
/review --scope staged --checks security,performance

Command Stuck or Hanging

Problem: Command runs but never completes

Solution:

# Cancel current command (Ctrl+C)

# Check command timeout
cat ~/.claude/commands/review/command.json
# Look for "timeout" field

# Increase timeout if needed
{
  "name": "review",
  "timeout": 600  # 10 minutes
}

# Or reduce scope
/review --scope src/components/UserProfile.tsx  # Single file
# Instead of: /review --scope all  # Entire codebase

Command Invokes Wrong Agent

Problem: Command calls unexpected agent

Solution: Check command configuration:

cat ~/.claude/commands/review/command.json

Look for agents field:

{
  "agents": [
    "@code-reviewer",
    "@security-auditor"
  ]
}

Customize if needed (edit command.json and restart).

Configuration Issues

YAML Syntax Errors

Error:

Configuration invalid: YAML parse error

Solution:

# Check YAML syntax
cat ~/.claude/skills/code-reviewer/SKILL.md

# Common YAML errors:
# 1. Incorrect indentation (use 2 spaces, not tabs)
# 2. Missing quotes around special characters
# 3. Missing colon after key

# Validate YAML online: https://www.yamllint.com/

# Fix syntax, save, restart Claude Code

Valid YAML:

---
name: "code-reviewer"
tools:
  - "Read"
  - "Write"
---

Invalid YAML:

---
name: code-reviewer  # Missing quotes (ok)
tools:
- "Read"  # Wrong indentation (should be 2 spaces)
 - "Write" # Inconsistent indentation
---

JSON Syntax Errors

Error:

Configuration invalid: JSON parse error

Solution:

# Validate JSON
cat ~/.claude/commands/review/command.json | python -m json.tool

# Common JSON errors:
# 1. Trailing commas
# 2. Single quotes instead of double quotes
# 3. Missing closing brackets

# Fix syntax, save, restart

Valid JSON:

{
  "name": "review",
  "enabled": true
}

Invalid JSON:

{
  "name": "review",
  "enabled": true,  // Trailing comma
}

Configuration Changes Not Applied

Problem: Changes to config files not taking effect

Solution:

Save configuration file
Restart Claude Code CLI completely
Verify changes:

# Check saved file
cat ~/.claude/skills/code-reviewer/SKILL.md

# Test skill/agent/command

Note: Configuration is loaded at startup. Must restart for changes to apply.

Performance Issues

Claude Code Runs Slowly

Problem: Sluggish performance with skills/agents

Solution:

Check Resource Usage:

# Check running processes
ps aux | grep claude

# Check CPU/memory
top -o cpu

Reduce Active Skills:

# Disable non-essential skills temporarily
---
name: "readme-updater"
enabled: false
---

Limit File Monitoring:

---
name: "code-reviewer"
file_patterns:
  - "src/**/*.ts"  # Only critical files
exclude_patterns:
  - "node_modules/**"
  - "dist/**"
  - "*.test.ts"
---

Use Lighter Model:

---
model: "claude-sonnet-4"  # Instead of claude-opus-4
---

High Memory Usage

Problem: Claude Code consuming excessive memory

Solution:

# Restart Claude Code
# Close unnecessary terminal windows
# Reduce concurrent skills

# Check for memory leaks
ps aux | grep claude | awk '{print $6}'  # Memory in KB

# If consistently high, report issue on GitHub

File and Path Issues

Skill Cannot Access Files

Problem: "Permission denied" or "File not found"

Solution:

# Verify file exists
ls /path/to/file.ts

# Check file permissions
ls -la /path/to/file.ts

# Ensure skill has Read permission
# Skills should have Read/Write/Edit/Grep/Glob tools

# Check skill configuration
cat ~/.claude/skills/code-reviewer/SKILL.md

Command Creates Files in Wrong Location

Problem: /scaffold creates files in unexpected directory

Solution:

# Check current directory before running command
pwd

# Navigate to correct directory first
cd /path/to/project

# Then run command
/scaffold react-component UserProfile

# Or specify full path
/scaffold react-component UserProfile --path /absolute/path/to/project/src/components

Integration Issues

Skills Conflict with Each Other

Problem: Multiple skills providing contradictory suggestions

Solution:

Option 1: Adjust Priorities

# code-reviewer gets priority
---
name: "code-reviewer"
priority: "high"
---

# security-auditor runs after
---
name: "security-auditor"
priority: "medium"
---

Option 2: Narrow Scopes

# code-reviewer handles general code
---
name: "code-reviewer"
file_patterns:
  - "src/**/*.ts"
exclude_patterns:
  - "src/api/**"  # Exclude API files
---

# security-auditor handles API only
---
name: "security-auditor"
file_patterns:
  - "src/api/**/*.ts"
---

Agent Invokes Wrong Tools

Problem: Agent tries to use tools it doesn't have access to

Solution:

# Check agent configuration
cat ~/.claude/agents/code-reviewer/SKILL.md

# Verify tools field includes needed tools
---
tools:
  - "Read"
  - "Write"
  - "Edit"
  - "Grep"
  - "Glob"
  - "Bash"  # Add if agent needs to run commands
---

# Save and restart Claude Code

Error Messages

"Skill Not Enabled"

Error:

Skill 'code-reviewer' is not enabled

Solution:

# Edit skill configuration
vi ~/.claude/skills/code-reviewer/SKILL.md

# Set enabled to true
---
enabled: true
---

# Save and restart Claude Code

"Agent Invocation Failed"

Error:

Failed to invoke @code-reviewer: configuration error

Solution:

# Check agent configuration syntax
cat ~/.claude/agents/code-reviewer/SKILL.md

# Validate YAML frontmatter
# Ensure all required fields present:
# - name
# - description
# - tools

# Fix errors, save, restart

"Command Timeout"

Error:

Command '/review' timed out after 120 seconds

Solution:

# Increase timeout in command.json
vi ~/.claude/commands/review/command.json

# Add or increase timeout
{
  "name": "review",
  "timeout": 600  # 10 minutes
}

# Or reduce command scope
/review --scope src/components/UserProfile.tsx

Getting More Help

Enable Debug Mode

# Enable detailed logging
export CLAUDE_CODE_DEBUG=true
export CLAUDE_CODE_LOG_LEVEL=debug

# Restart Claude Code
claude

# Check logs (if available)
cat ~/.claude/logs/debug.log

Collect Diagnostic Information

Before reporting issues, collect:

# Claude Code version
claude --version

# Installation verification
ls ~/.claude/skills/
ls ~/.claude/agents/
ls ~/.claude/commands/

# Configuration samples
cat ~/.claude/skills/code-reviewer/SKILL.md
cat ~/.claude/agents/code-reviewer/SKILL.md
cat ~/.claude/commands/review/command.json

# System information
uname -a  # OS version
node --version  # Node.js version (if applicable)
git --version  # Git version

Report Issues

If problems persist:

Check FAQ: FAQ →
Search GitHub Issues: Existing issues →
Create New Issue: Report bug →

Include in bug report:

Error message (full text)
Steps to reproduce
Expected vs actual behavior
Configuration files (sanitized)
System information

Ask Community: GitHub Discussions →

Emergency Recovery

Complete Reset

If all else fails, complete reset:

# Backup customizations first
cp -r ~/.claude/skills ~/.claude/skills.backup
cp -r ~/.claude/agents ~/.claude/agents.backup
cp -r ~/.claude/commands ~/.claude/commands.backup

# Remove all Claude Code Tresor components
rm -rf ~/.claude/skills/code-reviewer
rm -rf ~/.claude/skills/test-generator
# ... (remove all skills)

rm -rf ~/.claude/agents/code-reviewer
rm -rf ~/.claude/agents/test-engineer
# ... (remove all agents)

rm -rf ~/.claude/commands/scaffold
rm -rf ~/.claude/commands/review
# ... (remove all commands)

# Re-clone repository
cd ~
rm -rf claude-code-tresor
git clone https://github.com/alirezarezvani/claude-code-tresor.git
cd claude-code-tresor

# Fresh installation
./scripts/install.sh

# Restore customizations if needed
# (Manually merge from .backup directories)

# Restart Claude Code

Next Steps

Configuration Guide → - Advanced configuration
FAQ → - Common questions
GitHub Issues → - Report bugs

Last Updated: November 7, 2025 | Version: 2.0.0

Uh oh!

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

Troubleshooting Guide

Installation Issues

Permission Denied Error

Script Not Found Error

Installation Incomplete

Skill Issues

Skills Not Activating

Skill Triggers Wrong Files

Too Many Skill Suggestions

Skill Missing Dependencies

Agent Issues

Agent Not Found

Agent Fails to Execute

Agent Times Out

Agent Gives Generic Responses

Command Issues

Command Not Recognized

Command Fails with Invalid Parameters

Command Stuck or Hanging

Command Invokes Wrong Agent

Configuration Issues

YAML Syntax Errors

JSON Syntax Errors

Configuration Changes Not Applied

Performance Issues

Claude Code Runs Slowly

High Memory Usage

File and Path Issues

Skill Cannot Access Files

Command Creates Files in Wrong Location

Integration Issues

Skills Conflict with Each Other

Agent Invokes Wrong Tools

Error Messages

"Skill Not Enabled"

"Agent Invocation Failed"

"Command Timeout"

Getting More Help

Enable Debug Mode

Collect Diagnostic Information

Report Issues

Emergency Recovery

Complete Reset

Next Steps