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

  # Agent SDK settings (V3)
  agent:
    model: claude-sonnet-4-20250514
    max_tokens: 8192
    permission_mode: acceptEdits
    timeout: 300

  # 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"

Agent SDK Configuration

Sugar 3.0 uses the Claude Agent SDK. Configure agent behavior:

sugar:
  agent:
    # Model selection
    model: claude-sonnet-4-20250514
    max_tokens: 8192

    # Permission modes:
    # - default: Ask for confirmation
    # - acceptEdits: Auto-accept file edits
    # - bypassPermissions: Full autonomy (use with caution)
    permission_mode: acceptEdits

    # Timeout per task (seconds)
    timeout: 300

    # Retry configuration
    max_retries: 3
    retry_base_delay: 1.0
    retry_max_delay: 30.0

    # Quality gates for security
    quality_gates:
      enabled: true
      protected_files:
        - ".env"
        - "*.pem"
        - "credentials.json"
      blocked_commands:
        - "rm -rf /"
        - "sudo"

    # MCP server integrations
    mcp_servers:
      filesystem:
        command: npx
        args: ["-y", "@anthropic/mcp-server-filesystem"]

Executor Selection

Choose between execution backends:

sugar:
  claude:
    # V3 default - Native SDK (recommended)
    executor: sdk

    # V2 - Legacy subprocess wrapper
    # executor: legacy
    # command: "claude"
    # timeout: 1800

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)