Troubleshooting Guide

This guide helps you solve common problems with the Thread-Based Engineering plugin. Problems are organized by category for easy lookup.

Installation Problems
Command Problems
Script Problems
Hook Problems
Agent Problems
Performance Problems
Platform-Specific Issues
Getting More Help

1. Installation Problems

Problem: "Command not found: claude"

Symptoms:

bash: claude: command not found

Causes:

Claude Code is not installed
Claude Code is not in your PATH

Solutions:

Install Claude Code:

npm install -g @anthropic-ai/claude-code

Check installation:
```
claude --version
```

If still not found, add npm global bin to PATH:

Windows (Git Bash):

export PATH="$PATH:$(npm config get prefix)/bin"

Mac/Linux:

export PATH="$PATH:$(npm bin -g)"

Make permanent by adding to shell config:
- Windows: Add to ~/.bashrc
- Mac: Add to ~/.zshrc or ~/.bash_profile
- Linux: Add to ~/.bashrc

Problem: "Plugin not found" after installation

Symptoms:

Plugin 'agent-threads' not found

Unknown command: /agent-threads:base

Causes:

Plugin not properly installed
Wrong directory path during install
Missing plugin.json file

Solutions:

Verify plugin.json exists:

ls -la /path/to/agent-threads/.claude-plugin/plugin.json

Reinstall the plugin:

cd /path/to/agent-threads
claude /plugin install .

Check plugin list:
```
claude /plugins
```
You should see agent-threads in the list.

Try with absolute path:

# Windows (Git Bash)
claude /plugin install /c/Users/YourName/path/to/agent-threads

# Mac/Linux
claude /plugin install /Users/YourName/path/to/agent-threads

Problem: npm installation fails

Symptoms:

npm ERR! code EACCES
npm ERR! permission denied

Causes:

Insufficient permissions for global install

Solutions:

Mac/Linux - Use sudo (not ideal):

sudo npm install -g @anthropic-ai/claude-code

Better - Fix npm permissions:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Add the export line to your shell config file.

Windows - Run Git Bash as Administrator: Right-click Git Bash → "Run as administrator"

2. Command Problems

Problem: Command shows "undefined" instead of arguments

Symptoms: When you type /agent-threads:base src/, Claude says something about "undefined"

Causes:

The $ARGUMENTS placeholder isn't being replaced properly
Older version of Claude Code

Solutions:

Update Claude Code:
```
npm update -g @anthropic-ai/claude-code
```
Pass arguments directly after the command:
```
/agent-threads:base src/main.js
```
If still broken, ask Claude directly:
```
Analyze the src/ directory for me
```

Problem: "Tool not allowed" error

Symptoms:

Error: Tool 'Bash' is not allowed for this command

Causes:

The command's frontmatter restricts available tools
Trying to do something the command wasn't designed for

Solutions:

Check what tools are allowed: Look at the command file's frontmatter:
```
allowed-tools: Read, Grep, Glob
```
Use a different command:
- For read-only work: /agent-threads:base
- For writing files: /agent-threads:chained
- For running tests: /agent-threads:zero-touch
Ask directly without using a command: Just type your request without using a slash command.

Problem: Command takes too long

Symptoms:

Claude Code seems stuck
No output for several minutes

Causes:

Large codebase taking time to analyze
Network latency
Model processing complex request

Solutions:

Be more specific: Instead of:

/agent-threads:base

Try:

/agent-threads:base src/auth/

Set a timeout:
```
claude -p "your prompt" --max-turns 10
```
Check if it's actually working: Look for tool call output (like file reads) appearing.
Cancel and try again: Press Ctrl+C and restart with a narrower scope.

3. Script Problems

Problem: "Permission denied" when running scripts

Symptoms:

bash: ./scripts/parallel-runner.sh: Permission denied

Causes:

Script doesn't have execute permissions

Solutions:

Add execute permission:
```
chmod +x scripts/*.sh
```
Or run with bash explicitly:
```
bash scripts/parallel-runner.sh
```

Problem: Scripts don't work on Windows

Symptoms:

Syntax errors
Commands not found
Path issues

Causes:

Using Windows Command Prompt instead of Git Bash
Windows path format issues

Solutions:

Always use Git Bash on Windows: Open Git Bash, not Command Prompt or PowerShell.

Use forward slashes:

# Wrong (Windows style)
cd C:\Users\name\project

# Right (Git Bash style)
cd /c/Users/name/project

Install Git for Windows: Download from https://git-scm.com/download/win
- Includes Git Bash
- Choose "Git Bash Here" context menu option during install

Problem: "jq: command not found"

Symptoms:

bash: jq: command not found

when running fusion-aggregator.sh

Causes:

jq (JSON processor) not installed

Solutions:

Windows (Git Bash):
- Download from https://stedolan.github.io/jq/download/
- Put jq.exe in a directory in your PATH
Mac:
```
brew install jq
```
Linux (Debian/Ubuntu):
```
sudo apt install jq
```
Skip jq requirement: The fusion-aggregator script is optional. You can manually aggregate results or use Claude directly.

Problem: Scripts produce wrong line endings

Symptoms:

-bash: ./script.sh: /bin/bash^M: bad interpreter

Causes:

Windows-style line endings (CRLF) instead of Unix (LF)

Solutions:

Convert line endings:
```
sed -i 's/\r$//' scripts/*.sh
```
Or use dos2unix:
```
dos2unix scripts/*.sh
```
Configure Git to handle this automatically:
```
git config --global core.autocrlf input
```

4. Hook Problems

Problem: Stop hook not triggering

Symptoms:

Claude stops without running validation
Ralph Wiggum pattern not working

Causes:

hooks.json not loaded
Hook syntax error
Script path incorrect

Solutions:

Verify hooks are loaded:
```
/hooks
```
Should show the Stop hook listed.

Check hooks.json syntax:

cat hooks/hooks.json | python -m json.tool

cat hooks/hooks.json | jq .

Check script path: The path in hooks.json should be:

"command": "bash \"${CLAUDE_PROJECT_DIR}/scripts/ralph-loop.sh\""

Reinstall plugin:
```
claude /plugin install .
```

Problem: Hook script fails silently

Symptoms:

Hook runs but doesn't do anything
No error message but behavior is wrong

Causes:

Script errors being swallowed
Missing dependencies in script

Solutions:

Test script manually:
```
./scripts/ralph-loop.sh
echo $?
```
Check script has correct shebang: First line should be:
```
#!/bin/bash
```
Add debugging to script: Temporarily add set -x at the top to see what's happening.

Problem: Hook timeout

Symptoms:

Hook timed out after X seconds

Causes:

Script takes too long
Script waiting for input
Infinite loop in script

Solutions:

Increase timeout in hooks.json:

{
  "type": "command",
  "command": "...",
  "timeout": 120
}

Make script faster:
- Run fewer checks
- Skip slow operations
- Cache results
Check for infinite loops: Review script logic for conditions that never complete.

5. Agent Problems

Problem: Agent not found

Symptoms:

Agent '@researcher' not found

Causes:

Agent file missing
Agent file has wrong format
Plugin not installed properly

Solutions:

Check agent file exists:
```
ls -la agents/researcher.md
```

Verify frontmatter format:

---
name: researcher
description: ...
tools: Read, Grep, Glob
model: haiku
---

Reinstall plugin:
```
claude /plugin install .
```

Problem: Agent has wrong tools

Symptoms:

Agent tries to use tools it shouldn't have
"Tool not available" errors

Causes:

Frontmatter tools list is incorrect
Claude is ignoring tool restrictions (shouldn't happen)

Solutions:

Check agent definition:
```
head -20 agents/researcher.md
```
Verify tools match intent:
- Read-only agents: tools: Read, Grep, Glob
- Write agents: tools: Read, Write, Edit, Grep, Glob
- Validation agents: tools: Bash, Read, Grep

Problem: Agent returns empty or no response

Symptoms:

Agent spawns but returns nothing
Task tool says "completed" but no output

Causes:

Agent prompt is too vague
Agent hit an error internally
Context too large

Solutions:

Be more specific in agent prompt: Instead of "review the code", try "review src/auth.js for security issues"
Check if project is too large: Use narrower scope for agent tasks.
Try with more capable model: Change agent's model from haiku to sonnet in the frontmatter.

6. Performance Problems

Problem: Claude Code is very slow

Symptoms:

Long delays between responses
Tool calls taking forever

Causes:

Large files being processed
Network latency
API rate limiting

Solutions:

Work with smaller scope:

Analyze only src/api/ instead of the entire project

Use faster models: Use Haiku for simple tasks.
Check your internet connection: Claude Code requires internet to work.
Check API status: Visit https://status.anthropic.com

Problem: Running out of context

Symptoms:

Claude "forgets" earlier conversation
"Context limit reached" errors
Summarization messages appearing

Causes:

Too many files read
Very long conversation
Large code chunks

Solutions:

Start a new session for new topics: Exit and restart Claude Code.
Be more targeted in requests: Don't ask to "read everything" - specify what you need.
Use agents for large tasks: Agents have their own context windows.

7. Platform-Specific Issues

Windows-Specific

Problem: Paths with spaces don't work

# This fails:
cd /c/Users/John Doe/Documents

# This works:
cd "/c/Users/John Doe/Documents"
# or
cd /c/Users/John\ Doe/Documents

Problem: Git Bash not finding Claude

Add to ~/.bashrc:

export PATH="$PATH:/c/Users/YOUR_NAME/AppData/Roaming/npm"

Mac-Specific

Problem: "Developer cannot be verified" warning

Go to System Preferences → Security & Privacy → General Click "Allow Anyway" for Claude Code.

Problem: zsh syntax issues

Add to ~/.zshrc:

alias claude='claude'
export PATH="$PATH:$(npm bin -g)"

Linux-Specific

Problem: Snap/Flatpak npm conflicts

Use system npm instead:

sudo apt install nodejs npm

8. Getting More Help

Before Asking for Help

Check this guide - Your problem might be listed above
Check the FAQ - See FAQ.md
Check Claude Code docs - https://docs.anthropic.com/claude-code
Reproduce the problem - Can you reliably trigger it?

Information to Gather

When asking for help, include:

Operating System:

# Windows
echo $OS

# Mac/Linux
uname -a

Claude Code version:
```
claude --version
```
Node/npm version:
```
node --version
npm --version
```
Exact error message (copy-paste, don't paraphrase)
Steps to reproduce (numbered list)
What you expected vs what happened

Where to Get Help

Claude Code Issues: https://github.com/anthropics/claude-code/issues
Anthropic Support: https://support.anthropic.com
Community Discord: (if available)

Quick Diagnostic Commands

Run these and include output when asking for help:

# Check Claude Code
claude --version

# Check plugin installation
claude /plugins

# Check hooks loaded
claude
/hooks

# Test a simple command
claude -p "Say hello" --print

Quick Fixes Checklist

When something isn't working, try these in order:

Are you using Git Bash (Windows) or Terminal (Mac/Linux)?
Is Claude Code installed? (claude --version)
Is the plugin installed? (/plugins shows agent-threads)
Are you in the right directory?
Do scripts have execute permission? (chmod +x scripts/*.sh)
Is your internet working?
Have you tried restarting Claude Code?
Have you tried reinstalling the plugin?

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Troubleshooting Guide

Table of Contents

1. Installation Problems

Problem: "Command not found: claude"

Problem: "Plugin not found" after installation

Problem: npm installation fails

2. Command Problems

Problem: Command shows "undefined" instead of arguments

Problem: "Tool not allowed" error

Problem: Command takes too long

3. Script Problems

Problem: "Permission denied" when running scripts

Problem: Scripts don't work on Windows

Problem: "jq: command not found"

Problem: Scripts produce wrong line endings

4. Hook Problems

Problem: Stop hook not triggering

Problem: Hook script fails silently

Problem: Hook timeout

5. Agent Problems

Problem: Agent not found

Problem: Agent has wrong tools

Problem: Agent returns empty or no response

6. Performance Problems

Problem: Claude Code is very slow

Problem: Running out of context

7. Platform-Specific Issues

Windows-Specific

Mac-Specific

Linux-Specific

8. Getting More Help

Before Asking for Help

Information to Gather

Where to Get Help

Quick Diagnostic Commands

Quick Fixes Checklist

Related Documentation

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

Troubleshooting Guide

Table of Contents

1. Installation Problems

Problem: "Command not found: claude"

Problem: "Plugin not found" after installation

Problem: npm installation fails

2. Command Problems

Problem: Command shows "undefined" instead of arguments

Problem: "Tool not allowed" error

Problem: Command takes too long

3. Script Problems

Problem: "Permission denied" when running scripts

Problem: Scripts don't work on Windows

Problem: "jq: command not found"

Problem: Scripts produce wrong line endings

4. Hook Problems

Problem: Stop hook not triggering

Problem: Hook script fails silently

Problem: Hook timeout

5. Agent Problems

Problem: Agent not found

Problem: Agent has wrong tools

Problem: Agent returns empty or no response

6. Performance Problems

Problem: Claude Code is very slow

Problem: Running out of context

7. Platform-Specific Issues

Windows-Specific

Mac-Specific

Linux-Specific

8. Getting More Help

Before Asking for Help

Information to Gather

Where to Get Help

Quick Diagnostic Commands

Quick Fixes Checklist

Related Documentation