ICR Troubleshooting Guide

This guide helps you diagnose and fix common issues with the ICR plugin.

Acknowledgement: ICR is inspired by the YouTube video "The AI Failure Mode Nobody Warned You About (And how to prevent it from happening)". Understanding the "intent problem" described in this video helps contextualize why ICR exists and why it's worth troubleshooting!

Installation Issues
Plugin Not Loading
Hooks Not Working
Commands Not Found
JSON/jq Errors
Permission Errors
Receipt Issues
Configuration Problems
Performance Issues
Getting More Help

Installation Issues

Problem: "jq: command not found"

Symptoms:

Scripts fail with "jq: command not found"
ICR checks don't run

Solution:

Install jq for your platform:

Windows (Git Bash):

# Using Chocolatey
choco install jq

# Using winget
winget install jqlang.jq

# Verify installation
jq --version

macOS:

brew install jq
jq --version

Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install jq
jq --version

Linux (Fedora/RHEL):

sudo dnf install jq
jq --version

After installation, restart your terminal and Claude Code.

Problem: "Plugin directory not found"

Symptoms:

Claude Code doesn't recognize ICR commands
/icr:stats returns "Unknown command"

Solution:

Check plugin location:

# Plugin should be in one of these locations:
ls ~/.claude/plugins/icr
# or
ls ./.claude-plugins/icr

Verify plugin.json exists:

cat ~/.claude/plugins/icr/.claude-plugin/plugin.json

If using symlink, verify it's valid:

ls -la ~/.claude/plugins/icr
# Should show the symlink target

Reinstall if necessary:

rm -rf ~/.claude/plugins/icr
cp -r /path/to/icr ~/.claude/plugins/icr

Plugin Not Loading

Problem: "ICR commands available but not working"

Symptoms:

/icr:stats shows empty or errors
Hooks don't trigger

Solution:

Check for syntax errors in plugin.json:
```
jq . ~/.claude/plugins/icr/.claude-plugin/plugin.json
```
If this fails, there's a JSON syntax error. Check for:
- Missing commas
- Missing quotes
- Trailing commas (not allowed in JSON)

Verify scripts are executable:

chmod +x ~/.claude/plugins/icr/scripts/*.sh
chmod +x ~/.claude/plugins/icr/scripts/lib/*.sh

Test a script directly:

echo '{"tool_name": "Read"}' | bash ~/.claude/plugins/icr/scripts/lib/severity.sh

Problem: "Bash script errors on Windows"

Symptoms:

Scripts fail with syntax errors
\r or carriage return issues

Solution:

Windows line endings (CRLF) can break Bash scripts.

Convert to Unix line endings:

# Using dos2unix
dos2unix scripts/*.sh
dos2unix scripts/lib/*.sh

# Or using sed
sed -i 's/\r$//' scripts/*.sh
sed -i 's/\r$//' scripts/lib/*.sh

Configure Git to not convert line endings:
```
git config core.autocrlf false
```

Hooks Not Working

Problem: "PreToolUse hook not triggering"

Symptoms:

Actions proceed without ICR checks
No receipts being created

Solution:

Verify hooks.json is valid:

jq . ~/.claude/plugins/icr/hooks/hooks.json

Check hook paths are correct:

cat ~/.claude/plugins/icr/hooks/hooks.json
# Should show paths like:
# ${CLAUDE_PLUGIN_ROOT}/scripts/pre-tool-check.sh

Verify the script exists and is executable:

ls -la ~/.claude/plugins/icr/scripts/pre-tool-check.sh

Test the hook script directly:

echo '{
  "tool_name": "Bash",
  "tool_input": {"command": "ls"},
  "session_id": "test"
}' | bash ~/.claude/plugins/icr/scripts/pre-tool-check.sh

Problem: "Tool is excluded but shouldn't be"

Symptoms:

Certain tools never trigger ICR checks

Solution:

Check the exclude list in configuration:

# View current config
cat ~/.claude/icr/config.json | jq '.hooks.preToolUse.excludeTools'

# Or check defaults
cat ~/.claude/plugins/icr/config/defaults.json | jq '.hooks.preToolUse.excludeTools'

To remove a tool from exclusion:

# Via command
/icr:config set hooks.preToolUse.excludeTools ["Read", "Glob", "Grep"]

Or edit ~/.claude/icr/config.json:

{
  "hooks": {
    "preToolUse": {
      "excludeTools": ["Read", "Glob", "Grep"]
    }
  }
}

Commands Not Found

Problem: "/icr:* command not found"

Symptoms:

Commands return "Unknown command" or similar

Solution:

Verify commands are registered in plugin.json:

jq '.commands' ~/.claude/plugins/icr/.claude-plugin/plugin.json

Check command files exist:
```
ls ~/.claude/plugins/icr/commands/
```

Verify command file format:

head -10 ~/.claude/plugins/icr/commands/receipts.md
# Should start with YAML frontmatter:
# ---
# description: View ICR receipt history
# user_invocable: true
# ---

Restart Claude Code after fixing.

JSON/jq Errors

Problem: "parse error: Invalid numeric literal"

Symptoms:

Scripts fail with JSON parse errors
Garbled output

Solution:

This usually means malformed JSON. Debug by:

Check the input:

# Save input to file
echo '<your input>' > /tmp/test.json

# Validate
jq . /tmp/test.json

Common JSON mistakes:
- Missing quotes around strings: {key: "value"} → {"key": "value"}
- Trailing commas: {"a": 1,} → {"a": 1}
- Single quotes: {'key': 'value'} → {"key": "value"}

Check script output:

bash scripts/lib/severity.sh <<< '{"tool_name": "Bash"}' 2>&1 | head -20

Problem: "jq: error: ... is not defined"

Symptoms:

jq fails with undefined variable errors

Solution:

Check jq syntax in the script. Common issues:

# Wrong: Shell variable in jq string
jq ".field == $my_var"

# Right: Use --arg
jq --arg v "$my_var" '.field == $v'

# Wrong: Accessing possibly-null field
jq '.field.nested'

# Right: Use optional operator
jq '.field.nested // "default"'

Permission Errors

Problem: "Permission denied" when running scripts

Symptoms:

Scripts fail with "Permission denied"
Hook execution fails

Solution:

Make scripts executable:

chmod +x ~/.claude/plugins/icr/scripts/*.sh
chmod +x ~/.claude/plugins/icr/scripts/lib/*.sh

Check file ownership:
```
ls -la ~/.claude/plugins/icr/scripts/
```

If in restricted environment, run explicitly:

bash ~/.claude/plugins/icr/scripts/pre-tool-check.sh

Problem: "Cannot write to receipts directory"

Symptoms:

Receipts not being saved
Errors about write permissions

Solution:

Check directory permissions:
```
ls -la ~/.claude/icr/
```

Create directory with correct permissions:

mkdir -p ~/.claude/icr/receipts
chmod 755 ~/.claude/icr/receipts

Check disk space:
```
df -h ~/.claude/
```

Receipt Issues

Problem: "Receipts not being saved"

Symptoms:

/icr:receipts shows nothing
No files in receipts directory

Solution:

Check receipts directory exists:
```
ls -la ~/.claude/icr/receipts/
```
Check for write errors in log:
```
cat ~/.claude/icr/errors.log
```

Verify receipt creation manually:

# Trigger a check
/icr:check

# Then do something (like ask Claude to create a file)

# Check if receipt was created
ls -la ~/.claude/icr/receipts/$(date +%Y-%m-%d)/

Test receipt script:

echo '{
  "session_id": "test",
  "tool_name": "Test",
  "classification": {"severity": "LOW"},
  "decision": {"route": "AUTO_APPROVE"}
}' | bash ~/.claude/plugins/icr/scripts/lib/receipt.sh create

Problem: "Receipts taking too much disk space"

Symptoms:

Large receipts directory
Disk space warnings

Solution:

Check retention settings:

jq '.receipts.retentionDays' ~/.claude/icr/config.json

Reduce retention period:

/icr:config set receipts.retentionDays 30

Manually clean old receipts:

# Remove receipts older than 30 days
find ~/.claude/icr/receipts -type d -mtime +30 -exec rm -rf {} +

Export and archive before cleanup:
```
/icr:export json
```

Configuration Problems

Problem: "Configuration changes not taking effect"

Symptoms:

Changed settings but behavior unchanged

Solution:

Check if config file exists:
```
ls -la ~/.claude/icr/config.json
```
Validate config JSON:
```
jq . ~/.claude/icr/config.json
```

Check config is being loaded:

# Enable debug logging
export DEBUG=1

# Run a script
echo '{"tool_name": "Bash"}' | bash ~/.claude/plugins/icr/scripts/lib/severity.sh

Restart Claude Code after config changes.

Problem: "Reset configuration to defaults"

Symptoms:

Configuration is broken
Need to start fresh

Solution:

# Remove user config
rm ~/.claude/icr/config.json

# ICR will use defaults from:
# ~/.claude/plugins/icr/config/defaults.json

# Restart Claude Code

Performance Issues

Problem: "ICR checks are slow"

Symptoms:

Noticeable delay before actions
Timeout errors

Solution:

Check if DEBUG mode is on:

echo $DEBUG
# Should be empty or 0
unset DEBUG

Check receipts directory size:
```
du -sh ~/.claude/icr/receipts/
```
If very large, reduce retention or archive old receipts.

Exclude low-risk tools:

/icr:config set hooks.preToolUse.excludeTools ["Read", "Glob", "Grep", "Ls", "WebFetch"]

Use trust mode for routine work:
```
/icr:trust on
```

Problem: "Too many prompts interrupting workflow"

Symptoms:

Constant human review prompts
Workflow feels slow

Solution:

Adjust thresholds for your needs:

# More permissive for MEDIUM severity
/icr:config set thresholds.MEDIUM.autoApprove 0.60

# More permissive for HIGH severity
/icr:config set thresholds.HIGH.autoApprove 0.80

Enable trust mode for focused work:

/icr:trust on
# Remember to turn off when done
/icr:trust off

Exclude more tools:

/icr:config set hooks.preToolUse.excludeTools ["Read", "Glob", "Grep", "Ls", "Write", "Edit"]

Getting More Help

Enable Debug Logging

export DEBUG=1
# Run your commands
# Check output for detailed logging

Check Error Log

cat ~/.claude/icr/errors.log

Test Components Individually

# Test severity
echo '{"tool_name": "Bash", "tool_input": {"command": "ls"}}' | \
  bash scripts/lib/severity.sh

# Test decision
bash scripts/lib/decision.sh "HIGH" "0.65" '{}' '{}' "false"

# Test receipt creation
echo '{"session_id": "test", "tool_name": "Test"}' | \
  bash scripts/lib/receipt.sh create

Verify All Files Are Present

# List all expected files
find ~/.claude/plugins/icr -type f | sort

Report an Issue

If you can't solve the problem:

Note your environment:
- Operating system and version
- jq version (jq --version)
- Claude Code version
- Bash version (bash --version)

Collect debug info:

export DEBUG=1
# Reproduce the issue
# Copy the output

Include the error log:
```
cat ~/.claude/icr/errors.log
```
Create an issue with all this information.

Quick Reference

Problem	Quick Fix
jq not found	Install jq for your platform
Scripts not running	`chmod +x scripts/.sh scripts/lib/.sh`
Commands not found	Restart Claude Code
Config not working	Validate JSON: `jq . config.json`
Too many prompts	Enable trust mode: `/icr:trust on`
Slow performance	Reduce receipts retention
Windows line endings	Run `dos2unix scripts/*.sh`

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ICR Troubleshooting Guide

Table of Contents

Installation Issues

Problem: "jq: command not found"

Problem: "Plugin directory not found"

Plugin Not Loading

Problem: "ICR commands available but not working"

Problem: "Bash script errors on Windows"

Hooks Not Working

Problem: "PreToolUse hook not triggering"

Problem: "Tool is excluded but shouldn't be"

Commands Not Found

Problem: "/icr:* command not found"

JSON/jq Errors

Problem: "parse error: Invalid numeric literal"

Problem: "jq: error: ... is not defined"

Permission Errors

Problem: "Permission denied" when running scripts

Problem: "Cannot write to receipts directory"

Receipt Issues

Problem: "Receipts not being saved"

Problem: "Receipts taking too much disk space"

Configuration Problems

Problem: "Configuration changes not taking effect"

Problem: "Reset configuration to defaults"

Performance Issues

Problem: "ICR checks are slow"

Problem: "Too many prompts interrupting workflow"

Getting More Help

Enable Debug Logging

Check Error Log

Test Components Individually

Verify All Files Are Present

Report an Issue

Quick Reference

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

ICR Troubleshooting Guide

Table of Contents

Installation Issues

Problem: "jq: command not found"

Problem: "Plugin directory not found"

Plugin Not Loading

Problem: "ICR commands available but not working"

Problem: "Bash script errors on Windows"

Hooks Not Working

Problem: "PreToolUse hook not triggering"

Problem: "Tool is excluded but shouldn't be"

Commands Not Found

Problem: "/icr:* command not found"

JSON/jq Errors

Problem: "parse error: Invalid numeric literal"

Problem: "jq: error: ... is not defined"

Permission Errors

Problem: "Permission denied" when running scripts

Problem: "Cannot write to receipts directory"

Receipt Issues

Problem: "Receipts not being saved"

Problem: "Receipts taking too much disk space"

Configuration Problems

Problem: "Configuration changes not taking effect"

Problem: "Reset configuration to defaults"

Performance Issues

Problem: "ICR checks are slow"

Problem: "Too many prompts interrupting workflow"

Getting More Help

Enable Debug Logging

Check Error Log

Test Components Individually

Verify All Files Are Present

Report an Issue

Quick Reference