The autonomous layer for AI coding agents.
Sugar manages your task queue, runs 24/7, and ships working code while you focus on what matters.
Sugar adds autonomy and persistence to your AI coding workflow. Instead of one-off interactions:
- Continuous execution - Runs 24/7, working through your task queue
- Agent-agnostic - Works with Claude Code, OpenCode, Aider, or any AI CLI
- Delegate and forget - Hand off tasks from any session
- Builds features - Takes specs, implements, tests, commits working code
- Fixes bugs - Reads error logs, investigates, implements fixes
- GitHub integration - Creates PRs, updates issues, tracks progress
You plan the work. Sugar executes it.
Works with: Claude Code | OpenCode | Aider | Goose | Any CLI-based AI agent
Recommended: pipx (install once, use everywhere)
pipx install sugaraiThis gives you a global sugar command that works in any project. Each project gets its own isolated config and database in a .sugar/ folder.
Upgrade / Uninstall:
pipx upgrade sugarai # Upgrade to latest version
pipx uninstall sugarai # Remove completelyOther installation methods
pip (requires venv activation each session)
pip install sugaraiuv (fast alternative to pip)
uv pip install sugaraiWith GitHub integration:
pipx install 'sugarai[github]'Sugar is project-local - each project has its own isolated task queue and config.
# Navigate to your project
cd ~/dev/my-app
# Initialize Sugar (creates .sugar/ folder)
sugar init
# This creates:
# - .sugar/sugar.db (task queue database)
# - .sugar/config.yaml (project settings)
# - .sugar/prompts/ (custom prompts)
# Add tasks to the queue
sugar add "Fix authentication timeout" --type bug_fix --urgent
sugar add "Add user profile settings" --type feature
# Start the autonomous loop
sugar runSugar will:
- Pick up tasks from the queue
- Execute them using your configured AI agent
- Run tests and verify changes
- Commit working code
- Move to the next task
It keeps going until the queue is empty (or you stop it).
Delegate from Claude Code:
/sugar-task "Fix login timeout" --type bug_fix --urgent
Sugar picks it up and works on it while you keep coding.
Global Installation (pipx)
└── sugar CLI (~/.local/bin/sugar)
Project A Project B
~/dev/frontend-app/ ~/dev/backend-api/
├── .sugar/ ├── .sugar/
│ ├── sugar.db │ ├── sugar.db
│ ├── config.yaml │ ├── config.yaml
│ └── prompts/ │ └── prompts/
├── src/ ├── main.py
└── tests/ └── requirements.txt
Running `sugar` uses the .sugar/ folder in your current directory
One global CLI, many isolated projects. Like git - one installation, per-project repositories.
No! Install Sugar once with pipx install sugarai and use it everywhere.
The sugar command is globally available, but it reads configuration from the .sugar/ folder in your current directory:
- Global CLI access: Run
sugarfrom anywhere without venv activation - Project-local state: Each project's tasks and config stay isolated
- No conflicts: Work on multiple projects simultaneously
Yes! Each project has its own isolated database.
# Terminal 1
cd ~/dev/frontend-app
sugar run
# Terminal 2 (simultaneously)
cd ~/dev/backend-api
sugar runThe two Sugar instances won't interfere with each other.
Sugar will show a friendly error:
❌ Not a Sugar project
Could not find: .sugar/config.yaml
Run 'sugar init' to initialize Sugar in this directory.
| Installation | Global access? | Requires venv? |
|---|---|---|
pip install sugarai |
Only in active venv | Yes |
pipx install sugarai |
Yes, always | No |
With pipx, Sugar's dependencies don't conflict with your project's dependencies.
Recommended .gitignore:
.sugar/sugar.db # Task queue is personal
.sugar/sugar.log # Logs contain local paths
.sugar/*.db-* # SQLite temp filesDO commit: .sugar/config.yaml and .sugar/prompts/ to share settings with your team.
Task Management
- Rich task context with priorities and metadata
- Custom task types for your workflow
- Queue management and filtering
Task Orchestration
- Auto-decomposes complex features into subtasks
- 4-stage workflow: Research → Planning → Implementation → Review
- Specialist agent routing (frontend, backend, QA, security, DevOps)
- Parallel execution with dependency management
Autonomous Execution
- Specialized task agents (UX, backend, QA, security, DevOps)
- Automatic retries on failures
- Quality checks and testing
GitHub Integration
- Reads issues, creates PRs
- Updates issue status automatically
- Commits with proper messages
Ralph Wiggum Integration
- Iterative execution for complex tasks
- Self-correcting loops until tests pass
- Prevents single-shot failures
Full docs: docs/ralph-wiggum.md
.sugar/config.yaml is auto-generated on sugar init. Key settings:
sugar:
dry_run: false # Set to true for testing
loop_interval: 300 # 5 minutes between cycles
max_concurrent_work: 3 # Parallel task execution
claude:
enable_agents: true # Use specialized Claude agents
discovery:
github:
enabled: true
repo: "user/repository"
error_logs:
enabled: true
paths: ["logs/errors/"]Sugar has native Claude Code integration. Delegate work directly from your Claude sessions.
/plugin install roboticforce/sugar
Inside a Claude Code session:
You: "I'm working on auth but need to fix these test failures.
Can you handle the tests while I finish?"
Claude: "I'll create a Sugar task for the test fixes."
/sugar-task "Fix authentication test failures" --type test --urgent
Available Slash Commands:
/sugar-task- Create tasks with rich context/sugar-status- Check queue and progress/sugar-run- Start autonomous mode
Sugar provides an MCP server for Goose, Claude Desktop, and other MCP clients.
Using with Goose:
goose configure
# Select "Add Extension" → "Command-line Extension"
# Name: sugar
# Command: npx -y sugarai-mcpUsing with Claude Desktop:
{
"mcpServers": {
"sugar": {
"command": "npx",
"args": ["-y", "sugarai-mcp"],
"env": {
"SUGAR_PROJECT_ROOT": "/path/to/your/project"
}
}
}
}Task Orchestration
sugar add "Add OAuth authentication" --type feature --orchestrate
# Sugar will:
# 1. RESEARCH - Search best practices, analyze codebase
# 2. PLAN - Create implementation plan with subtasks
# 3. IMPLEMENT - Route subtasks to specialists in parallel
# 4. REVIEW - Code review and test verification
sugar orchestrate <task_id> --stagesRalph Wiggum (iterative execution)
sugar add "Implement rate limiting" --ralph --max-iterations 10
# Iterates until tests pass, not just until code is writtenCustom Task Types
sugar task-type add deployment --name "Deployment" --emoji "🚀"
sugar add "Deploy to staging" --type deploymentComplex Tasks with Context
sugar add "User Dashboard" --json --description '{
"priority": 5,
"context": "Complete dashboard redesign",
"agent_assignments": {
"frontend_developer": "Implementation",
"qa_test_engineer": "Testing"
}
}'Sugar not finding Claude CLI?
# .sugar/config.yaml
claude:
command: "/full/path/to/claude"Tasks not executing?
cat .sugar/config.yaml | grep dry_run # Check dry_run is false
tail -f .sugar/sugar.log # Monitor logs
sugar run --once # Test single cycleMore help:
- Python 3.11+
- An AI coding agent CLI:
- Claude Code (default)
- OpenCode
- Aider
- Or any CLI-based AI coding tool
Contributions welcome! See CONTRIBUTING.md.
git clone https://github.com/roboticforce/sugar.git
cd sugar
uv pip install -e ".[dev,test,github]"
pytest tests/ -vDual License: AGPL-3.0 + Commercial
- Open Source (AGPL-3.0): Free for open source and personal use
- Commercial License: For proprietary use - sugar.roboticforce.io/licensing
Sugar v3.4 - The autonomous layer for AI coding agents
⚠️ Sugar is provided "AS IS" without warranty. Review all AI-generated code before use.