Version:
← All Docs

Quick Start Guide

Get Sugar up and running in your project in just a few minutes.

Prerequisites

Before installing Sugar, make sure you have:

  • Python 3.11 or higher
  • Anthropic API key (set as ANTHROPIC_API_KEY environment variable)
  • Git (for project management)

Installation

pipx install sugarai

pipx installs Sugar globally—no venv activation needed. Alternative: pip install sugarai

Basic Usage

1. Initialize Sugar in Your Project

Navigate to your project directory and initialize Sugar:

cd /path/to/your/project
sugar init

This creates a .sugar/ directory with configuration and database.

2. Enable MCP Features in Claude Code (Recommended)

To get the most out of Sugar, add the MCP server to Claude Code:

claude mcp add sugar -- sugar mcp memory

This gives Claude Code access to your project's memory - decisions, preferences, error patterns, and more.

3. Add Your First Task

Add tasks to the queue with priorities and types:

# Add a feature task
sugar add "Implement user authentication" --type feature --priority 4

# Add an urgent bug fix
sugar add "Fix memory leak in auth module" --type bug_fix --urgent

# Add a test task
sugar add "Add unit tests for payments" --type test --priority 3

4. Check Status

# View system status
sugar status

# List all tasks
sugar list

# View specific task details
sugar view TASK_ID

5. Run Sugar

# Test run (safe mode - no actual changes)
sugar run --dry-run --once

# Start continuous autonomous development
sugar run

Sugar will pick up tasks from the queue and execute them autonomously using the Claude Agent SDK.

Configuration

Edit .sugar/config.yaml to customize Sugar for your project:

sugar:
  # Core settings
  dry_run: true  # Set to false when ready for real execution
  loop_interval: 300  # 5 minutes between cycles
  max_concurrent_work: 3

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

    # Quality gates for security
    quality_gates:
      enabled: true
      protected_files:
        - ".env"
        - "*.pem"
      blocked_commands:
        - "sudo"

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

    code_quality:
      enabled: true
      source_dirs: ["src", "lib", "app"]
Safety First: Sugar starts in dry-run mode by default. Set dry_run: false when ready for autonomous operation.

What's New in V3

Sugar 3.0 introduces the Claude Agent SDK for improved performance:

  • Direct API calls - No subprocess overhead
  • Quality gates - Pre/post hook security enforcement
  • Full observability - Track every tool use and file modification
  • Streaming responses - Real-time progress updates

See the Agent SDK documentation for details.

Tips

  • Start Small: Begin with --dry-run --once to see what Sugar would do
  • Monitor Logs: Check .sugar/sugar.log for detailed activity
  • Project Isolation: Each project gets its own Sugar instance
  • Quality Gates: Configure protected files to prevent accidental changes to sensitive files

Next Steps