Version:
← All Docs

Installation Guide

Complete installation and setup instructions for Sugar.

Prerequisites

Before installing Sugar, ensure you have:

  • Python 3.11 or higher
  • An AI coding agent CLI - Claude Code (default), OpenCode, Aider, or similar
  • Git (for project management)

Install an AI Agent CLI

Sugar works with any CLI-based AI coding agent. Popular options:

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

# OpenCode
go install github.com/opencode-ai/opencode@latest

# Aider
pip install aider-chat

Install Sugar

Option 1: pipx (Recommended)

pipx installs Sugar globally so you can use it in any project without venv activation:

pipx install sugarai

This gives you a global sugar command that works in any project.

Option 2: pip

If you prefer traditional pip (requires venv activation each session):

pip install sugarai

# Or use uv (much faster)
uv pip install sugarai

Option 3: From Source

# Clone the repository
git clone https://github.com/roboticforce/sugar.git
cd sugar

# Install in development mode
pip install -e .

Verify Installation

# Check Sugar version
sugar --version

# Show help
sugar help

Initialize in Your Project

# Navigate to your project
cd /path/to/your/project

# Initialize Sugar
sugar init

This creates:

  • .sugar/ - Sugar configuration directory
  • .sugar/config.yaml - Configuration file
  • .sugar/sugar.db - SQLite task database
  • logs/errors/ - Error log monitoring directory

Configuration

Edit .sugar/config.yaml to customize Sugar:

sugar:
  dry_run: true              # Set to false when ready
  loop_interval: 300         # 5 minutes between cycles

  claude:
    command: "claude"        # Path to Claude CLI
    timeout: 1800            # 30 minutes max per task

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

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

Test Your Setup

# Validate configuration
sugar run --validate

# Run in safe mode (dry run)
sugar run --dry-run --once

# Check status
sugar status

Add to .gitignore

Add Sugar's data directory to your .gitignore:

# Sugar
.sugar/sugar.db
.sugar/sugar.log
.sugar/logs/

Keep .sugar/config.yaml in version control to share settings.

Updating Sugar

# If installed with pipx
pipx upgrade sugarai

# If installed with pip
pip install --upgrade sugarai

Uninstalling

# If installed with pipx
pipx uninstall sugarai

# If installed with pip
pip uninstall sugarai

# Remove project data (optional)
rm -rf .sugar/

Next Steps