Troubleshooting

Common issues and solutions for Sugar users.

AI Agent CLI Not Found

Problem: Sugar reports the AI agent CLI is not found during initialization.

Solutions:

Install an AI Agent CLI:

# Claude Code (default)
npm install -g @anthropic-ai/claude-code

# Or OpenCode, Aider, etc.

Check PATH:

which claude  # or opencode, aider
echo $PATH

Manual Configuration: Edit .sugar/config.yaml:

sugar:
  claude:
    command: "/full/path/to/your-agent-cli"

Common CLI Locations:

/usr/local/bin/claude
/opt/homebrew/bin/claude (macOS with Homebrew)
~/.local/bin/

No Work Discovered

Problem: Sugar doesn't find any tasks to work on.

Solutions:

Check Discovery Paths:

ls -la logs/errors/
mkdir -p logs/errors/

Enable Discovery Sources:

sugar:
  discovery:
    error_logs:
      enabled: true
      paths: ["logs/errors/"]
    code_quality:
      enabled: true

Validate Configuration:
```
sugar run --validate
```

Tasks Not Executing

Problem: Tasks remain pending and never execute.

Solutions:

Check Dry Run Mode:

sugar:
  dry_run: false  # Must be false for real execution

Monitor Logs:
```
tail -f .sugar/sugar.log
```

Test Single Task:

sugar add "test task" --type feature
sugar run --once --dry-run

Permission Errors

Problem: Sugar can't write to directories or access files.

# Check permissions
ls -la .sugar/
chmod 755 .sugar/
chmod 644 .sugar/config.yaml

# Verify write access
touch .sugar/test_file
rm .sugar/test_file

Database Errors

Problem: SQLite database errors or corruption.

# Check database
ls -la .sugar/sugar.db
file .sugar/sugar.db

# Reset database (backup first!)
cp .sugar/sugar.db .sugar/sugar.db.backup
rm .sugar/sugar.db
sugar status  # Will recreate database

High Memory/CPU Usage

Problem: Sugar consumes too many resources.

sugar:
  max_concurrent_work: 1      # Reduce from 3
  loop_interval: 600          # 10 minutes instead of 5

  discovery:
    code_quality:
      max_files_per_scan: 25  # Reduce from 50

Running Sugar Inside an AI Agent Session

Problem: User tries to run Sugar from within an AI agent session (Claude Code, etc.).

Issue: This creates recursive execution that can cause context confusion and resource conflicts.

Solution: Run Sugar outside of AI agent sessions:

# Correct: Run in regular terminal
cd /path/to/your/project
sugar init
sugar run

# Architecture:
# ✅ Terminal → Sugar → AI Agent CLI (for tasks)
# ❌ AI Agent → Sugar → AI Agent CLI (recursive)

Diagnostic Commands

# Check status
sugar status
sugar list

# Validate configuration
sugar run --validate

# Test discovery (safe mode)
sugar run --dry-run --once

# Check logs
tail -f .sugar/sugar.log

# Database inspection
sqlite3 .sugar/sugar.db
.tables
SELECT * FROM work_items;
.quit

Performance Optimization

For Large Projects

sugar:
  discovery:
    code_quality:
      max_files_per_scan: 25
      excluded_dirs: [
        "node_modules", "venv", "dist", "build",
        "coverage", "docs", "examples", ".git"
      ]

For Slow Systems

sugar:
  loop_interval: 900        # 15 minutes
  max_concurrent_work: 1

  claude:
    timeout: 3600           # Allow longer execution

Safety Features

Sugar has built-in safety measures:

Dry run by default - No changes until you set dry_run: false
Path exclusions - Won't modify system directories
Timeout protection - Tasks have maximum execution time
Retry limits - Failed tasks won't retry infinitely

Emergency Stop

# Stop running Sugar
pkill -f "sugar run"

# Or use Ctrl+C in the terminal running Sugar

Debug Mode

export SUGAR_LOG_LEVEL=DEBUG
sugar run --dry-run --once

Or edit .sugar/config.yaml:

sugar:
  logging:
    level: "DEBUG"

Getting Help

If you can't resolve the issue:

Search Issues: Check GitHub Issues
Create Issue: Include Sugar version, OS, Python version, config file, and logs
Contact: [email protected]