sugar

Sugar is an autonomous layer for AI coding agents that runs continuously, managing your task queue and coordinating AI actions to implement features, fix bugs, and interact with GitHub. It is agent-agnostic and designed to be memory-rich, enabling persistent context across sessions. You can integrate it with Claude Code, OpenCode, Aider, Goose, or any CLI-based AI agent via its MCP server interface. The Sugar workflow typically involves initializing a project-local .sugar directory, adding tasks to a queue, and running an autonomous loop that processes tasks, validates changes with tests, commits code, and advances the project state. Use the native Sugar commands to manage memory, recall decisions, and delegate tasks from Claude Code or other agents. OpenCode integration provides a one-command setup to enable MCP-based memory access and bidirectional communication, while Claude Code integration offers explicit CLI commands to grant memory access to your project. Sugar automatically injects relevant context into AI sessions for memory-enabled workflows.

Prerequisites:

• Python 3.8+ installed
• pip (or ensure pipx is installed)
• Optional: access to GitHub if you want the GitHub integration features

Install via pipx (recommended):

python3 -m pip install --user pipx
python3 -m pipx ensurepath
# Install Sugar CLI globally for use in any project
pipx install sugarai

Usage after installation:

# Global CLI available
sugar --help

# Initialize Sugar in a project (creates .sugar/ folder in the current directory)
sugar init

# Add tasks to the queue (example)
sugar add "Fix authentication timeout" --type bug_fix --urgent

# Run the autonomous loop
sugar run

Upgrade / Uninstall:

pipx upgrade sugarai    # Upgrade to latest version
pipx uninstall sugarai  # Remove completely

Alternative installation methods (optional):

# pip in a virtual environment (venv must be activated each session)
pip install sugarai

# uv (fast alternative to pip) installation
uv pip install sugarai

# With GitHub integration and memory features
pipx install 'sugarai[github]'
pipx install 'sugarai[memory]'
pipx install 'sugarai[all]'

Tips and common issues:

• Sugar is project-local: each project keeps its own .sugar directory with its queue and config. Use sugar init inside the project directory.
• If you run sugar outside a project folder, you’ll get a friendly error prompting you to initialize the project with sugar init.
• For memory and memory-injection features, consider enabling sugar memory or semantic search as needed (e.g., sugar recall, sugar remember). These features have dependencies around vector storage and semantic indexing.
• If you use Claude Code, you can grant memory access via claude mcp add sugar -- sugar mcp memory. OpenCode offers similar setup for memory injection and notifications.
• It’s recommended to ignore .sugar/sugar.db in version control, but commit .sugar/config.yaml and .sugar/prompts/ to share project settings.
• The mcp_config uses pipx to run the sugarai CLI. If you prefer a different installation path, you can adapt to uvx or another Python launcher as long as the CLI is accessible as a command named sugar.