Configuration

Essential configuration patterns and best practices for Sugar.

Configuration File

Sugar configuration lives in .sugar/config.yaml. This file is created when you run sugar init.

Basic Configuration

sugar:
  # Core settings
  dry_run: true              # Set to false for real execution
  loop_interval: 300         # Seconds between cycles (5 minutes)
  max_concurrent_work: 3     # Parallel task execution

  # Claude CLI
  claude:
    command: "claude"        # Path to Claude CLI (auto-detected)
    timeout: 1800            # 30 minutes max per task

  # Discovery settings
  discovery:
    error_logs:
      enabled: true
      paths: ["logs/errors/"]

    code_quality:
      enabled: true
      source_dirs: ["src", "lib", "app"]

    github:
      enabled: false
      repo: "owner/repository"

Global Directory Exclusions

Prevent Sugar from scanning directories that should be ignored (virtual environments, build artifacts, etc.):

sugar:
  discovery:
    # Global exclusions for all discovery modules
    global_excluded_dirs: [
      "node_modules", ".git", "__pycache__",
      "venv", ".venv", "env", ".env", "ENV",
      "build", "dist", ".tox", ".nox",
      "coverage", "htmlcov", ".pytest_cache",
      ".sugar", ".claude"
    ]

    code_quality:
      enabled: true
      excluded_dirs: [
        "node_modules", ".git", "__pycache__",
        "venv", ".venv", "env",
        "build", "dist", "coverage"
      ]

Project-Specific Configurations

Web Application

sugar:
  discovery:
    code_quality:
      excluded_dirs: [
        "node_modules", "venv", ".venv", "build", "dist",
        "static/vendor",      # Third-party CSS/JS
        "public/uploads",     # User uploads
        ".next",              # Next.js
        ".nuxt",              # Nuxt.js
      ]

Python Package

sugar:
  discovery:
    code_quality:
      excluded_dirs: [
        "venv", ".venv", "build", "dist",
        "*.egg-info",         # Package metadata
        ".eggs",              # Setuptools eggs
        "docs/_build",        # Sphinx builds
        ".tox", ".nox",       # Test environments
      ]

Monorepo

sugar:
  discovery:
    code_quality:
      excluded_dirs: [
        "node_modules", "venv", ".venv",
        "*/node_modules",     # Per-package dependencies
        "*/build",            # Per-package builds
        "*/dist",             # Per-package distributions
        ".yarn", ".pnpm-store"
      ]

Performance Optimization

For large projects, reduce scan scope:

sugar:
  discovery:
    code_quality:
      max_files_per_scan: 25    # Reduce from default 50
      excluded_dirs: [
        "examples", "samples", "demo", "playground",
        "docs", "documentation", ".github",
        "vendor", "third_party", "external"
      ]

    test_coverage:
      source_dirs: ["src"]      # Focus on core source only

Debug Mode

Enable debug logging to troubleshoot discovery issues:

sugar:
  logging:
    level: "DEBUG"
    file: ".sugar/sugar.log"

  discovery:
    code_quality:
      max_files_per_scan: 5     # Small batches for debugging

Then check logs:

grep -i "scanning\|discovered\|excluding" .sugar/sugar.log

Safety Settings

Sugar starts in dry-run mode by default for safety:

sugar:
  dry_run: true   # Shows what would be done without making changes

Set dry_run: false when you're ready for autonomous operation.

Exclusion Checklist

Make sure to exclude:

• Virtual environments: venv, .venv, env, .env
• Dependencies: node_modules, vendor
• Build artifacts: build, dist, target
• Test artifacts: .tox, .nox, coverage, htmlcov
• Caches: __pycache__, .pytest_cache, .mypy_cache
• VCS: .git, .svn
• Sugar/Claude: .sugar, .claude

Environment Variables

• SUGAR_CONFIG - Override default config file path
• SUGAR_LOG_LEVEL - Set logging level (DEBUG, INFO, WARNING, ERROR)