# Sugar - AI-Powered Autonomous Development System
**An intelligent autonomous development assistant that works 24/7 to improve your codebase using Claude AI.**
Sugar is a lightweight autonomous development system specifically designed for Claude Code CLI integration that can be installed as a library in any project. It continuously discovers work from GitHub issues, error logs, and code quality analysis, then automatically implements fixes and improvements using Claude's advanced reasoning capabilities.
## ✨ What Makes Sugar Special
- 🤖 **Truly Autonomous**: Runs 24/7 discovering and fixing issues without human intervention
- 🧠 **Advanced Agent Integration**: Intelligently selects optimal Claude agents for each task type
- 🚀 **Dynamic Agent Discovery**: Works with **any** Claude agents you have configured locally
- 🔍 **Smart Discovery**: Automatically finds work from GitHub issues, error logs, and code analysis
- 🎯 **Project-Focused**: Each project gets isolated Sugar instance with custom configuration
- 🔧 **Battle-Tested**: Handles real development workflows with git, GitHub, testing, and deployment
- 📊 **Quality Tracking**: Monitors agent performance with detailed analytics and confidence scoring
- 📈 **Learning System**: Adapts and improves based on success/failure patterns
## 🚀 Quick Start
### Prerequisites
**Required:** Sugar requires Claude Code CLI to be installed and accessible.
1. **Install Claude Code CLI** (if not already installed):
- Visit [Claude Code CLI documentation](https://docs.anthropic.com/en/docs/claude-code) for installation instructions
- Or install via npm: `npm install -g @anthropic-ai/claude-code-cli`
- Verify installation: `claude --version`
2. **Ensure Claude CLI is in your PATH** or note its location for configuration
⚠️ **Important:** Sugar is designed to run **outside** of Claude Code sessions. Run Sugar directly in your terminal/shell, not within a Claude Code session. Sugar will call Claude Code CLI as needed to execute tasks.
### Installation
**Install from PyPI (recommended):**
```bash
pip install sugarai
```
> ⚠️ **IMPORTANT DISCLAIMER**: By installing and using Sugar, you agree to the [Terms of Service and Disclaimer](TERMS.md). Sugar is provided "AS IS" without warranty. Users are solely responsible for reviewing AI-generated code and ensuring appropriate safeguards. Sugar is not affiliated with or endorsed by Anthropic, Inc. "Claude" and "Claude Code" are trademarks of Anthropic, Inc.
**Or install from source for latest development version:**
```bash
# Method 1: Clone and install (recommended for development)
git clone https://github.com/cdnsteve/sugar.git
cd sugar
pip install -e .
# Method 2: Direct from Git (SSH) - Always use main branch
pip install -e git+ssh://git@github.com/cdnsteve/sugar.git@main#egg=sugar
```
📖 **Detailed setup instructions:** [Local Development Setup](docs/dev/local-development.md)
### Initialize in Your Project
```bash
cd /path/to/your/project
sugar init
```
**Note:** Sugar will auto-detect your Claude CLI installation. If it's not in your PATH, you can specify the location in `.sugar/config.yaml` after initialization.
### Add Some Work
```bash
sugar add "Implement user authentication" --type feature --priority 4
sugar add "Fix memory leak in auth module" --type bug_fix --urgent
sugar add "Add unit tests for payments" --type test --priority 3
```
### Get Help Anytime
```bash
# Comprehensive help and quick reference
sugar help
# Command-specific help
sugar add --help
sugar run --help
```
### Start Autonomous Development
```bash
# Test with dry run first
sugar run --dry-run --once
# Start 24/7 autonomous operation
sugar run
```
## 🎯 What Sugar Does
Sugar operates in **two modes**:
### 🤖 Autonomous Discovery
Sugar continuously:
- 🔍 **Discovers work** from error logs, feedback, and GitHub issues
- 📊 **Analyzes code quality** and identifies improvements
- 🧪 **Detects missing tests** and coverage gaps
- ⚡ **Executes tasks** using Claude Code CLI with full context
- 🌿 **Creates branches & PRs** or commits directly to main (configurable)
- 💬 **Updates GitHub issues** with detailed progress and completion status
- 🧠 **Learns and adapts** from results to improve future performance
- 🔄 **Repeats autonomously** 24/7 without human intervention
### 👤 Manual Task Management
You can also directly add tasks:
- 📝 **Add specific tasks** via `sugar add "task description"`
- 🎯 **Set priorities** and task types (bug_fix, feature, test, etc.)
- 📋 **Manage work queue** with full CLI control
- 🔄 **Combined workflow** - manual tasks + autonomous discovery
## 📁 Clean Project Structure
Sugar keeps everything contained in `.sugar/` directory - no clutter in your project root!
```
your-project/
├── src/ # Your project source
├── .sugar/ # Sugar-specific files (isolated)
│ ├── config.yaml # Project-specific config
│ ├── sugar.db # Project-specific database
│ ├── sugar.log # Project-specific logs
│ └── context.json # Claude context
├── .gitignore # Just add: .sugar/
└── logs/errors/ # Your error logs (monitored)
```
**Simple .gitignore:** Just add `.sugar/` to your `.gitignore` - that's it!
📖 [Complete .gitignore template](docs/user/gitignore-template.md)
## 🔧 Configuration
Auto-generated `.sugar/config.yaml` with sensible defaults:
```yaml
sugar:
# Core Loop Settings
loop_interval: 300 # 5 minutes between cycles
max_concurrent_work: 3 # Execute multiple tasks per cycle
dry_run: true # Start in safe mode - change to false when ready
# Claude Code Integration
claude:
command: "/path/to/claude" # Auto-detected Claude CLI path
timeout: 1800 # 30 minutes max per task
context_file: ".sugar/context.json"
# Agent Integration (v1.2.0+)
use_structured_requests: true # Enable structured JSON communication
enable_agents: true # Enable Claude agent mode selection
agent_fallback: true # Fall back to basic Claude if agent fails
agent_selection: # Map work types to specific agents
bug_fix: "tech-lead" # Strategic analysis for bug fixes
feature: "general-purpose" # General development for features
refactor: "code-reviewer" # Code review expertise for refactoring
test: "general-purpose" # General development for tests
documentation: "general-purpose" # General development for docs
# available_agents: [] # Optional: specify which agents are available
# If empty, Sugar accepts any agent name
# Work Discovery
discovery:
error_logs:
enabled: true
paths: ["logs/errors/", "logs/feedback/", ".sugar/logs/"]
patterns: ["*.json", "*.log"]
max_age_hours: 24
github:
enabled: false # Set to true and configure to enable
repo: "" # e.g., "user/repository"
issue_labels: [] # No filtering - work on ALL open issues
workflow:
auto_close_issues: true
git_workflow: "direct_commit" # direct_commit|pull_request
code_quality:
enabled: true
root_path: "."
file_extensions: [".py", ".js", ".ts", ".jsx", ".tsx"]
excluded_dirs: ["node_modules", ".git", "__pycache__", "venv", ".venv", ".sugar"]
max_files_per_scan: 50
test_coverage:
enabled: true
root_path: "."
source_dirs: ["src", "lib", "app", "api", "server"]
test_dirs: ["tests", "test", "__tests__", "spec"]
# Storage
storage:
database: ".sugar/sugar.db" # Project-specific database
backup_interval: 3600 # 1 hour
# Safety
safety:
max_retries: 3
excluded_paths:
- "/System"
- "/usr/bin"
- "/etc"
- ".sugar"
# Logging
logging:
level: "INFO"
file: ".sugar/sugar.log" # Project-specific logs
```
## 🤖 Claude Agent Integration
**Sugar v1.2.0+ includes advanced Claude agent integration with dynamic agent discovery!**
Sugar intelligently selects the best Claude agent for each task based on work characteristics, and supports **any agents you have configured locally** - not just built-in ones.
### 🎯 Intelligent Agent Selection
Sugar automatically analyzes your work items and selects the optimal agent:
```bash
# High-priority security bug → tech-lead agent
sugar add --type bug_fix --priority 5 --title "Critical auth vulnerability"
# Code refactoring → code-reviewer agent
sugar add --type refactor --title "Clean up legacy payment code"
# Social media content → social-media-growth-strategist agent
sugar add --type documentation --title "Create LinkedIn content for developer audience"
# Standard feature → general-purpose agent
sugar add --type feature --title "Add user profile settings"
```
### 🔧 Agent Configuration
Configure agents in `.sugar/config.yaml`:
```yaml
claude:
# Structured Request System
use_structured_requests: true
# Agent Selection System
enable_agents: true # Enable agent mode selection
agent_fallback: true # Fall back to basic Claude if agent fails
# Map work types to specific agents (built-in or custom)
agent_selection:
bug_fix: "tech-lead" # Built-in agent
feature: "my-frontend-specialist" # Your custom agent
refactor: "code-reviewer" # Built-in agent
test: "general-purpose" # Built-in agent
documentation: "technical-writer" # Your custom agent
# Dynamic Agent Discovery - specify your available agents
available_agents: [
"tech-lead", # Built-in agents
"code-reviewer",
"general-purpose",
"my-frontend-specialist", # Your custom agents
"technical-writer",
"database-expert",
"security-specialist"
]
# If available_agents is empty/unspecified, Sugar accepts any agent name
```
### 🌟 Built-in Agent Types
Sugar includes intelligent selection for these built-in agents:
| Agent | Best For | Keywords |
|-------|----------|----------|
| **tech-lead** | Strategic analysis, architecture, complex bugs, high-priority work | architecture, design, strategy, security, critical |
| **code-reviewer** | Code quality, refactoring, optimization, best practices | review, refactor, cleanup, optimize, code quality |
| **social-media-growth-strategist** | Content strategy, engagement, audience growth | social media, content, engagement, followers |
| **general-purpose** | Standard development work (features, tests, docs) | Default for most tasks |
| **statusline-setup** | Claude Code status line configuration | statusline, status line |
| **output-style-setup** | Claude Code output styling and themes | output style, styling, theme |
### 🚀 Custom Agent Support
**Sugar supports ANY agents you have configured locally!** Examples:
```yaml
claude:
agent_selection:
bug_fix: "my-security-expert" # Your custom security agent
feature: "frontend-guru" # Your custom frontend agent
refactor: "performance-wizard" # Your custom performance agent
database: "sql-specialist" # Your custom database agent
```
### 🧠 How Agent Selection Works
1. **User Configuration First**: Checks your `agent_selection` mapping
2. **Keyword Analysis**: Uses intelligent keyword matching as fallback
3. **Availability Validation**: Ensures selected agent is in your `available_agents` list
4. **Graceful Fallback**: Falls back to available alternatives if needed
5. **Quality Assessment**: Tracks agent performance with 0.0-1.0 quality scores
### 📊 Agent Performance Tracking
Sugar provides detailed analytics for agent performance:
```bash
# View work with timing and agent information
sugar list
# 📋 20 Tasks (16 pending ⏳, 2 completed ✅, 1 active ⚡, 1 failed ❌):
# ⏱️ 45.2s | 🕐 2m 15s | 🤖 tech-lead | Critical auth fix
sugar view TASK_ID
# Shows: agent used, quality score, confidence level, execution time
```
### 🔄 Fallback Strategy
Sugar uses a robust multi-layer fallback system:
1. **Selected Agent** (from configuration or keyword analysis)
2. **Basic Claude** (if agent fails)
3. **Legacy Mode** (if structured requests fail)
This ensures your work **never fails** due to agent issues.
### ⚙️ Migration from v1.1.x
Existing Sugar installations automatically get agent support with **zero breaking changes**:
- All existing configurations continue working unchanged
- Agents are **opt-in** - set `enable_agents: false` to disable
- Without agent configuration, Sugar uses intelligent defaults
## 📋 Command Reference
### Task Management
```bash
# Add tasks with different types and priorities
sugar add "Task title" [--type TYPE] [--priority 1-5] [--urgent] [--description DESC]
# Types: bug_fix, feature, test, refactor, documentation
# Priority: 1 (low) to 5 (urgent)
# List tasks
sugar list [--status STATUS] [--type TYPE] [--limit N]
# View specific task details
sugar view TASK_ID
# Update existing task
sugar update TASK_ID [--title TITLE] [--description DESC] [--priority 1-5] [--type TYPE] [--status STATUS]
# Remove task
sugar remove TASK_ID
# Check system status
sugar status
```
### System Operation
```bash
# Initialize Sugar in current directory
sugar init [--project-dir PATH]
# Run autonomous loop
sugar run [--dry-run] [--once] [--validate]
# Validate configuration
sugar run --validate
```
## 🔄 Multi-Project Usage
Run Sugar across multiple projects simultaneously:
```bash
# Project A
cd /path/to/project-a
sugar init && sugar run &
# Project B
cd /path/to/project-b
sugar init && sugar run &
# Project C
cd /path/to/project-c
sugar init && sugar run &
```
Each project operates independently with isolated:
- Configuration and database
- Work queues and execution
- Discovery and learning
## 🛡️ Safety Features
- **Dry run mode** - Simulates execution without making changes (default)
- **Path exclusions** - Prevents system file modifications
- **Project isolation** - Uses `.sugar/` directory to avoid conflicts
- **Timeout handling** - Prevents runaway processes
- **Auto-detection** - Finds Claude CLI automatically
- **Graceful shutdown** - Handles interrupts cleanly
## 💾 Storage & Context
Sugar maintains project-specific data isolation:
- **Project Database**: `.sugar/sugar.db` stores all task data, execution history, and learning
- **Context Management**: `.sugar/context.json` preserves Claude Code session context
- **Automated Backups**: Regular database backups with configurable intervals
- **Isolated Logs**: Project-specific logging in `.sugar/sugar.log`
Each Sugar instance is completely isolated - you can run multiple projects simultaneously without interference.
## 🔍 Work Input Methods
Sugar accepts work from **multiple sources**:
### 📝 Manual CLI Input
Direct task management via command line:
```bash
sugar add "Implement user registration" --type feature --priority 4
sugar add "Fix authentication bug" --type bug_fix --urgent
sugar add "Add API tests" --type test --priority 3
```
### 🤖 Autonomous Discovery
Sugar automatically finds work from:
### Error Logs
Monitors specified directories for error files:
```yaml
discovery:
error_logs:
paths: ["logs/errors/", "app/logs/"]
patterns: ["*.json", "*.log"]
```
### Code Quality Analysis
Scans source code for improvements:
```yaml
discovery:
code_quality:
file_extensions: [".py", ".js", ".ts"]
excluded_dirs: ["node_modules", "venv"]
```
### Test Coverage Analysis
Identifies missing tests:
```yaml
discovery:
test_coverage:
source_dirs: ["src", "lib"]
test_dirs: ["tests", "spec"]
```
### GitHub Integration (Optional)
Monitors repository issues and PRs:
```yaml
discovery:
github:
enabled: true
repo: "owner/repository"
token: "ghp_your_token"
```
## 📊 Monitoring
### Per-Project Monitoring
Each project has its own isolated Sugar instance. Commands are project-specific:
```bash
# Check status for current project
sugar status
# Monitor logs for current project
tail -f .sugar/sugar.log
# List recent work for current project (shows status summary)
sugar list --status completed --limit 10
# Background operation for current project
nohup sugar run > sugar-autonomous.log 2>&1 &
```
### Multi-Project Monitoring
To monitor Sugar across multiple projects, you need to check each project directory:
```bash
# Example script to check all projects
for project in ~/projects/*; do
if [ -d "$project/.sugar" ]; then
echo "📂 Project: $(basename $project)"
cd "$project"
sugar status | grep -E "(Total Tasks|Pending|Active|Completed)"
echo
fi
done
```
## 🎛️ Advanced Usage
### Custom Error Integration
Configure Sugar to monitor your application's error logs:
```yaml
discovery:
error_logs:
paths:
- "logs/errors/"
- "monitoring/alerts/"
- "var/log/myapp/"
```
### Team Workflow
1. Each developer runs Sugar locally
2. Share configuration templates (without tokens)
3. Different priorities for different team members
4. GitHub integration prevents duplicate work
### Production Deployment
- Test thoroughly in staging environments
- Monitor resource usage and performance
- Set appropriate concurrency and timeout limits
- Ensure rollback procedures are in place
## 🚨 Troubleshooting
### Common Issues
**Claude CLI not found:**
```bash
# First, check if Claude CLI is installed
claude --version
# If not installed, install it:
npm install -g @anthropic-ai/claude-code-cli
# If installed but not found by Sugar, edit .sugar/config.yaml:
claude:
command: "/full/path/to/claude" # Specify exact path
```
**No work discovered:**
```bash
# Check paths exist
ls -la logs/errors/
# Validate configuration
sugar run --validate
# Test with sample error
echo '{"error": "test"}' > logs/errors/test.json
```
**Tasks not executing:**
```bash
# Check dry_run setting
cat .sugar/config.yaml | grep dry_run
# Monitor logs
tail -f .sugar/sugar.log
# Test single cycle
sugar run --once
```
## 📚 Documentation
- **[Complete Documentation Hub](docs/README.md)** - All Sugar documentation
- **[Quick Start Guide](docs/user/quick-start.md)** - Get up and running in 5 minutes
- **[Local Development Setup](docs/dev/local-development.md)** - Install and test Sugar locally (before PyPI)
- **[GitHub Integration](docs/user/github-integration.md)** - Connect Sugar to GitHub issues and PRs
- **[Installation Guide](docs/user/installation-guide.md)** - Comprehensive installation and usage
- **[CLI Reference](docs/user/cli-reference.md)** - Complete command reference
- **[Contributing Guide](docs/dev/contributing.md)** - How to contribute to Sugar
## 🎯 Use Cases
### Individual Developer
- Continuous bug fixing from error logs
- Automated test creation for uncovered code
- Documentation updates when code changes
- Code quality improvements during idle time
### Development Team
- Shared work discovery across team projects
- Automated issue processing from GitHub
- Continuous integration of feedback loops
- 24/7 development progress across multiple repos
### Product Teams
- Autonomous handling of user feedback
- Automated response to monitoring alerts
- Continuous improvement of code quality metrics
- Proactive maintenance and technical debt reduction
## 🔮 Roadmap
- ✅ **Phase 1**: Core loop, error discovery, basic execution
- ✅ **Phase 2**: Smart discovery (GitHub, code quality, test coverage)
- ✅ **Phase 3**: Learning and adaptation system
- 🚧 **Phase 4**: PyPI package distribution
- 📋 **Phase 5**: Enhanced integrations (Slack, Jira, monitoring systems)
- 📋 **Phase 6**: Team coordination and conflict resolution
## 🤝 Contributing
1. Test changes with `--dry-run` and `--once`
2. Validate configuration with `--validate`
3. Check logs in `.sugar/sugar.log`
4. Follow existing code patterns
5. Update documentation for new features
## ⚖️ Legal and Disclaimers
### Terms of Service
By using Sugar, you agree to our [Terms of Service and Disclaimer](TERMS.md), which includes:
- **No Warranty**: Software provided "AS IS" without warranties of any kind
- **Limitation of Liability**: No responsibility for code damage, data loss, or system issues
- **User Responsibility**: Users must review all AI-generated code before use
- **Security**: Never use on production systems without proper testing and safeguards
### Trademark Notice
Sugar is an independent third-party tool. "Claude," "Claude Code," and related marks are trademarks of Anthropic, Inc. Sugar is not affiliated with, endorsed by, or sponsored by Anthropic, Inc.
### Risk Acknowledgment
- AI-generated code may contain errors or security vulnerabilities
- Always review and test generated code in safe environments
- Maintain proper backups of your projects
- Use appropriate security measures for your development environment
## 📄 License
MIT License with additional disclaimers - see [LICENSE](LICENSE) and [TERMS.md](TERMS.md) for complete details.
---
**Sugar v1.7.2** - Built for Claude Code CLI autonomous development across any project or codebase.
*Transform any project into an autonomous development environment with just `sugar init`.*
Raw data
{
"_id": null,
"home_page": null,
"name": "sugarai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "claude, autonomous, development, ai, automation",
"author": null,
"author_email": "Steven Leggett <contact@roboticforce.io>",
"download_url": "https://files.pythonhosted.org/packages/67/0d/697b6a508d1334e5ce4f1291974b78244e8ebfc6a4f6408a66ff7e233d5d/sugarai-1.7.2.tar.gz",
"platform": null,
"description": "# Sugar - AI-Powered Autonomous Development System\n\n**An intelligent autonomous development assistant that works 24/7 to improve your codebase using Claude AI.**\n\nSugar is a lightweight autonomous development system specifically designed for Claude Code CLI integration that can be installed as a library in any project. It continuously discovers work from GitHub issues, error logs, and code quality analysis, then automatically implements fixes and improvements using Claude's advanced reasoning capabilities.\n\n## \u2728 What Makes Sugar Special\n\n- \ud83e\udd16 **Truly Autonomous**: Runs 24/7 discovering and fixing issues without human intervention\n- \ud83e\udde0 **Advanced Agent Integration**: Intelligently selects optimal Claude agents for each task type\n- \ud83d\ude80 **Dynamic Agent Discovery**: Works with **any** Claude agents you have configured locally\n- \ud83d\udd0d **Smart Discovery**: Automatically finds work from GitHub issues, error logs, and code analysis\n- \ud83c\udfaf **Project-Focused**: Each project gets isolated Sugar instance with custom configuration\n- \ud83d\udd27 **Battle-Tested**: Handles real development workflows with git, GitHub, testing, and deployment\n- \ud83d\udcca **Quality Tracking**: Monitors agent performance with detailed analytics and confidence scoring\n- \ud83d\udcc8 **Learning System**: Adapts and improves based on success/failure patterns\n\n## \ud83d\ude80 Quick Start\n\n### Prerequisites\n\n**Required:** Sugar requires Claude Code CLI to be installed and accessible.\n\n1. **Install Claude Code CLI** (if not already installed):\n - Visit [Claude Code CLI documentation](https://docs.anthropic.com/en/docs/claude-code) for installation instructions\n - Or install via npm: `npm install -g @anthropic-ai/claude-code-cli`\n - Verify installation: `claude --version`\n\n2. **Ensure Claude CLI is in your PATH** or note its location for configuration\n\n\u26a0\ufe0f **Important:** Sugar is designed to run **outside** of Claude Code sessions. Run Sugar directly in your terminal/shell, not within a Claude Code session. Sugar will call Claude Code CLI as needed to execute tasks.\n\n### Installation\n\n**Install from PyPI (recommended):**\n\n```bash\npip install sugarai\n```\n\n> \u26a0\ufe0f **IMPORTANT DISCLAIMER**: By installing and using Sugar, you agree to the [Terms of Service and Disclaimer](TERMS.md). Sugar is provided \"AS IS\" without warranty. Users are solely responsible for reviewing AI-generated code and ensuring appropriate safeguards. Sugar is not affiliated with or endorsed by Anthropic, Inc. \"Claude\" and \"Claude Code\" are trademarks of Anthropic, Inc.\n\n**Or install from source for latest development version:**\n\n```bash\n# Method 1: Clone and install (recommended for development)\ngit clone https://github.com/cdnsteve/sugar.git\ncd sugar\npip install -e .\n\n# Method 2: Direct from Git (SSH) - Always use main branch\npip install -e git+ssh://git@github.com/cdnsteve/sugar.git@main#egg=sugar\n```\n\n\ud83d\udcd6 **Detailed setup instructions:** [Local Development Setup](docs/dev/local-development.md)\n\n### Initialize in Your Project\n\n```bash\ncd /path/to/your/project\nsugar init\n```\n\n**Note:** Sugar will auto-detect your Claude CLI installation. If it's not in your PATH, you can specify the location in `.sugar/config.yaml` after initialization.\n\n### Add Some Work\n\n```bash\nsugar add \"Implement user authentication\" --type feature --priority 4\nsugar add \"Fix memory leak in auth module\" --type bug_fix --urgent\nsugar add \"Add unit tests for payments\" --type test --priority 3\n```\n\n### Get Help Anytime\n\n```bash\n# Comprehensive help and quick reference\nsugar help\n\n# Command-specific help\nsugar add --help\nsugar run --help\n```\n\n### Start Autonomous Development\n\n```bash\n# Test with dry run first\nsugar run --dry-run --once\n\n# Start 24/7 autonomous operation\nsugar run\n```\n\n## \ud83c\udfaf What Sugar Does\n\nSugar operates in **two modes**:\n\n### \ud83e\udd16 Autonomous Discovery\nSugar continuously:\n- \ud83d\udd0d **Discovers work** from error logs, feedback, and GitHub issues\n- \ud83d\udcca **Analyzes code quality** and identifies improvements \n- \ud83e\uddea **Detects missing tests** and coverage gaps\n- \u26a1 **Executes tasks** using Claude Code CLI with full context\n- \ud83c\udf3f **Creates branches & PRs** or commits directly to main (configurable)\n- \ud83d\udcac **Updates GitHub issues** with detailed progress and completion status\n- \ud83e\udde0 **Learns and adapts** from results to improve future performance\n- \ud83d\udd04 **Repeats autonomously** 24/7 without human intervention\n\n### \ud83d\udc64 Manual Task Management\nYou can also directly add tasks:\n- \ud83d\udcdd **Add specific tasks** via `sugar add \"task description\"`\n- \ud83c\udfaf **Set priorities** and task types (bug_fix, feature, test, etc.)\n- \ud83d\udccb **Manage work queue** with full CLI control\n- \ud83d\udd04 **Combined workflow** - manual tasks + autonomous discovery\n\n## \ud83d\udcc1 Clean Project Structure \n\nSugar keeps everything contained in `.sugar/` directory - no clutter in your project root!\n\n```\nyour-project/\n\u251c\u2500\u2500 src/ # Your project source\n\u251c\u2500\u2500 .sugar/ # Sugar-specific files (isolated)\n\u2502 \u251c\u2500\u2500 config.yaml # Project-specific config\n\u2502 \u251c\u2500\u2500 sugar.db # Project-specific database\n\u2502 \u251c\u2500\u2500 sugar.log # Project-specific logs\n\u2502 \u2514\u2500\u2500 context.json # Claude context\n\u251c\u2500\u2500 .gitignore # Just add: .sugar/\n\u2514\u2500\u2500 logs/errors/ # Your error logs (monitored)\n```\n\n**Simple .gitignore:** Just add `.sugar/` to your `.gitignore` - that's it! \n\ud83d\udcd6 [Complete .gitignore template](docs/user/gitignore-template.md)\n\n## \ud83d\udd27 Configuration\n\nAuto-generated `.sugar/config.yaml` with sensible defaults:\n\n```yaml\nsugar:\n # Core Loop Settings\n loop_interval: 300 # 5 minutes between cycles\n max_concurrent_work: 3 # Execute multiple tasks per cycle\n dry_run: true # Start in safe mode - change to false when ready\n \n # Claude Code Integration\n claude:\n command: \"/path/to/claude\" # Auto-detected Claude CLI path\n timeout: 1800 # 30 minutes max per task\n context_file: \".sugar/context.json\"\n \n # Agent Integration (v1.2.0+)\n use_structured_requests: true # Enable structured JSON communication\n enable_agents: true # Enable Claude agent mode selection\n agent_fallback: true # Fall back to basic Claude if agent fails\n agent_selection: # Map work types to specific agents\n bug_fix: \"tech-lead\" # Strategic analysis for bug fixes\n feature: \"general-purpose\" # General development for features\n refactor: \"code-reviewer\" # Code review expertise for refactoring\n test: \"general-purpose\" # General development for tests\n documentation: \"general-purpose\" # General development for docs\n # available_agents: [] # Optional: specify which agents are available\n # If empty, Sugar accepts any agent name\n \n # Work Discovery\n discovery:\n error_logs:\n enabled: true\n paths: [\"logs/errors/\", \"logs/feedback/\", \".sugar/logs/\"]\n patterns: [\"*.json\", \"*.log\"]\n max_age_hours: 24\n \n github:\n enabled: false # Set to true and configure to enable\n repo: \"\" # e.g., \"user/repository\"\n issue_labels: [] # No filtering - work on ALL open issues\n workflow:\n auto_close_issues: true\n git_workflow: \"direct_commit\" # direct_commit|pull_request\n \n code_quality:\n enabled: true\n root_path: \".\"\n file_extensions: [\".py\", \".js\", \".ts\", \".jsx\", \".tsx\"]\n excluded_dirs: [\"node_modules\", \".git\", \"__pycache__\", \"venv\", \".venv\", \".sugar\"]\n max_files_per_scan: 50\n \n test_coverage:\n enabled: true\n root_path: \".\"\n source_dirs: [\"src\", \"lib\", \"app\", \"api\", \"server\"]\n test_dirs: [\"tests\", \"test\", \"__tests__\", \"spec\"]\n \n # Storage\n storage:\n database: \".sugar/sugar.db\" # Project-specific database\n backup_interval: 3600 # 1 hour\n \n # Safety\n safety:\n max_retries: 3\n excluded_paths:\n - \"/System\"\n - \"/usr/bin\"\n - \"/etc\"\n - \".sugar\"\n \n # Logging\n logging:\n level: \"INFO\"\n file: \".sugar/sugar.log\" # Project-specific logs\n```\n\n## \ud83e\udd16 Claude Agent Integration\n\n**Sugar v1.2.0+ includes advanced Claude agent integration with dynamic agent discovery!**\n\nSugar intelligently selects the best Claude agent for each task based on work characteristics, and supports **any agents you have configured locally** - not just built-in ones.\n\n### \ud83c\udfaf Intelligent Agent Selection\n\nSugar automatically analyzes your work items and selects the optimal agent:\n\n```bash\n# High-priority security bug \u2192 tech-lead agent\nsugar add --type bug_fix --priority 5 --title \"Critical auth vulnerability\"\n\n# Code refactoring \u2192 code-reviewer agent \nsugar add --type refactor --title \"Clean up legacy payment code\"\n\n# Social media content \u2192 social-media-growth-strategist agent\nsugar add --type documentation --title \"Create LinkedIn content for developer audience\"\n\n# Standard feature \u2192 general-purpose agent\nsugar add --type feature --title \"Add user profile settings\"\n```\n\n### \ud83d\udd27 Agent Configuration\n\nConfigure agents in `.sugar/config.yaml`:\n\n```yaml\nclaude:\n # Structured Request System\n use_structured_requests: true\n \n # Agent Selection System\n enable_agents: true # Enable agent mode selection\n agent_fallback: true # Fall back to basic Claude if agent fails\n \n # Map work types to specific agents (built-in or custom)\n agent_selection:\n bug_fix: \"tech-lead\" # Built-in agent\n feature: \"my-frontend-specialist\" # Your custom agent\n refactor: \"code-reviewer\" # Built-in agent \n test: \"general-purpose\" # Built-in agent\n documentation: \"technical-writer\" # Your custom agent\n \n # Dynamic Agent Discovery - specify your available agents\n available_agents: [\n \"tech-lead\", # Built-in agents\n \"code-reviewer\", \n \"general-purpose\",\n \"my-frontend-specialist\", # Your custom agents\n \"technical-writer\",\n \"database-expert\",\n \"security-specialist\"\n ]\n \n # If available_agents is empty/unspecified, Sugar accepts any agent name\n```\n\n### \ud83c\udf1f Built-in Agent Types\n\nSugar includes intelligent selection for these built-in agents:\n\n| Agent | Best For | Keywords |\n|-------|----------|----------|\n| **tech-lead** | Strategic analysis, architecture, complex bugs, high-priority work | architecture, design, strategy, security, critical |\n| **code-reviewer** | Code quality, refactoring, optimization, best practices | review, refactor, cleanup, optimize, code quality |\n| **social-media-growth-strategist** | Content strategy, engagement, audience growth | social media, content, engagement, followers |\n| **general-purpose** | Standard development work (features, tests, docs) | Default for most tasks |\n| **statusline-setup** | Claude Code status line configuration | statusline, status line |\n| **output-style-setup** | Claude Code output styling and themes | output style, styling, theme |\n\n### \ud83d\ude80 Custom Agent Support\n\n**Sugar supports ANY agents you have configured locally!** Examples:\n\n```yaml\nclaude:\n agent_selection:\n bug_fix: \"my-security-expert\" # Your custom security agent\n feature: \"frontend-guru\" # Your custom frontend agent\n refactor: \"performance-wizard\" # Your custom performance agent\n database: \"sql-specialist\" # Your custom database agent\n```\n\n### \ud83e\udde0 How Agent Selection Works\n\n1. **User Configuration First**: Checks your `agent_selection` mapping\n2. **Keyword Analysis**: Uses intelligent keyword matching as fallback\n3. **Availability Validation**: Ensures selected agent is in your `available_agents` list \n4. **Graceful Fallback**: Falls back to available alternatives if needed\n5. **Quality Assessment**: Tracks agent performance with 0.0-1.0 quality scores\n\n### \ud83d\udcca Agent Performance Tracking\n\nSugar provides detailed analytics for agent performance:\n\n```bash\n# View work with timing and agent information\nsugar list\n# \ud83d\udccb 20 Tasks (16 pending \u23f3, 2 completed \u2705, 1 active \u26a1, 1 failed \u274c):\n# \u23f1\ufe0f 45.2s | \ud83d\udd50 2m 15s | \ud83e\udd16 tech-lead | Critical auth fix\n\nsugar view TASK_ID\n# Shows: agent used, quality score, confidence level, execution time\n```\n\n### \ud83d\udd04 Fallback Strategy\n\nSugar uses a robust multi-layer fallback system:\n\n1. **Selected Agent** (from configuration or keyword analysis)\n2. **Basic Claude** (if agent fails) \n3. **Legacy Mode** (if structured requests fail)\n\nThis ensures your work **never fails** due to agent issues.\n\n### \u2699\ufe0f Migration from v1.1.x\n\nExisting Sugar installations automatically get agent support with **zero breaking changes**:\n\n- All existing configurations continue working unchanged\n- Agents are **opt-in** - set `enable_agents: false` to disable\n- Without agent configuration, Sugar uses intelligent defaults\n\n## \ud83d\udccb Command Reference\n\n### Task Management\n```bash\n# Add tasks with different types and priorities\nsugar add \"Task title\" [--type TYPE] [--priority 1-5] [--urgent] [--description DESC]\n\n# Types: bug_fix, feature, test, refactor, documentation\n# Priority: 1 (low) to 5 (urgent)\n\n# List tasks\nsugar list [--status STATUS] [--type TYPE] [--limit N]\n\n# View specific task details\nsugar view TASK_ID\n\n# Update existing task\nsugar update TASK_ID [--title TITLE] [--description DESC] [--priority 1-5] [--type TYPE] [--status STATUS]\n\n# Remove task\nsugar remove TASK_ID\n\n# Check system status\nsugar status\n```\n\n### System Operation\n```bash\n# Initialize Sugar in current directory\nsugar init [--project-dir PATH]\n\n# Run autonomous loop\nsugar run [--dry-run] [--once] [--validate]\n\n# Validate configuration\nsugar run --validate\n```\n\n## \ud83d\udd04 Multi-Project Usage\n\nRun Sugar across multiple projects simultaneously:\n\n```bash\n# Project A\ncd /path/to/project-a\nsugar init && sugar run &\n\n# Project B \ncd /path/to/project-b\nsugar init && sugar run &\n\n# Project C\ncd /path/to/project-c\nsugar init && sugar run &\n```\n\nEach project operates independently with isolated:\n- Configuration and database\n- Work queues and execution\n- Discovery and learning\n\n## \ud83d\udee1\ufe0f Safety Features\n\n- **Dry run mode** - Simulates execution without making changes (default)\n- **Path exclusions** - Prevents system file modifications \n- **Project isolation** - Uses `.sugar/` directory to avoid conflicts\n- **Timeout handling** - Prevents runaway processes\n- **Auto-detection** - Finds Claude CLI automatically\n- **Graceful shutdown** - Handles interrupts cleanly\n\n## \ud83d\udcbe Storage & Context\n\nSugar maintains project-specific data isolation:\n\n- **Project Database**: `.sugar/sugar.db` stores all task data, execution history, and learning\n- **Context Management**: `.sugar/context.json` preserves Claude Code session context\n- **Automated Backups**: Regular database backups with configurable intervals\n- **Isolated Logs**: Project-specific logging in `.sugar/sugar.log`\n\nEach Sugar instance is completely isolated - you can run multiple projects simultaneously without interference.\n\n## \ud83d\udd0d Work Input Methods\n\nSugar accepts work from **multiple sources**:\n\n### \ud83d\udcdd Manual CLI Input\nDirect task management via command line:\n```bash\nsugar add \"Implement user registration\" --type feature --priority 4\nsugar add \"Fix authentication bug\" --type bug_fix --urgent\nsugar add \"Add API tests\" --type test --priority 3\n```\n\n### \ud83e\udd16 Autonomous Discovery\nSugar automatically finds work from:\n\n### Error Logs\nMonitors specified directories for error files:\n```yaml\ndiscovery:\n error_logs:\n paths: [\"logs/errors/\", \"app/logs/\"]\n patterns: [\"*.json\", \"*.log\"]\n```\n\n### Code Quality Analysis\nScans source code for improvements:\n```yaml\ndiscovery:\n code_quality:\n file_extensions: [\".py\", \".js\", \".ts\"]\n excluded_dirs: [\"node_modules\", \"venv\"]\n```\n\n### Test Coverage Analysis\nIdentifies missing tests:\n```yaml\ndiscovery:\n test_coverage:\n source_dirs: [\"src\", \"lib\"]\n test_dirs: [\"tests\", \"spec\"]\n```\n\n### GitHub Integration (Optional)\nMonitors repository issues and PRs:\n```yaml\ndiscovery:\n github:\n enabled: true\n repo: \"owner/repository\"\n token: \"ghp_your_token\"\n```\n\n## \ud83d\udcca Monitoring\n\n### Per-Project Monitoring\n\nEach project has its own isolated Sugar instance. Commands are project-specific:\n\n```bash\n# Check status for current project\nsugar status\n\n# Monitor logs for current project\ntail -f .sugar/sugar.log\n\n# List recent work for current project (shows status summary)\nsugar list --status completed --limit 10\n\n# Background operation for current project\nnohup sugar run > sugar-autonomous.log 2>&1 &\n```\n\n### Multi-Project Monitoring\n\nTo monitor Sugar across multiple projects, you need to check each project directory:\n\n```bash\n# Example script to check all projects\nfor project in ~/projects/*; do\n if [ -d \"$project/.sugar\" ]; then\n echo \"\ud83d\udcc2 Project: $(basename $project)\"\n cd \"$project\"\n sugar status | grep -E \"(Total Tasks|Pending|Active|Completed)\"\n echo\n fi\ndone\n```\n\n## \ud83c\udf9b\ufe0f Advanced Usage\n\n### Custom Error Integration\n\nConfigure Sugar to monitor your application's error logs:\n\n```yaml\ndiscovery:\n error_logs:\n paths:\n - \"logs/errors/\"\n - \"monitoring/alerts/\"\n - \"var/log/myapp/\"\n```\n\n### Team Workflow\n\n1. Each developer runs Sugar locally\n2. Share configuration templates (without tokens)\n3. Different priorities for different team members\n4. GitHub integration prevents duplicate work\n\n### Production Deployment\n\n- Test thoroughly in staging environments\n- Monitor resource usage and performance\n- Set appropriate concurrency and timeout limits\n- Ensure rollback procedures are in place\n\n## \ud83d\udea8 Troubleshooting\n\n### Common Issues\n\n**Claude CLI not found:**\n```bash\n# First, check if Claude CLI is installed\nclaude --version\n\n# If not installed, install it:\nnpm install -g @anthropic-ai/claude-code-cli\n\n# If installed but not found by Sugar, edit .sugar/config.yaml:\nclaude:\n command: \"/full/path/to/claude\" # Specify exact path\n```\n\n**No work discovered:**\n```bash\n# Check paths exist\nls -la logs/errors/\n\n# Validate configuration \nsugar run --validate\n\n# Test with sample error\necho '{\"error\": \"test\"}' > logs/errors/test.json\n```\n\n**Tasks not executing:**\n```bash\n# Check dry_run setting\ncat .sugar/config.yaml | grep dry_run\n\n# Monitor logs\ntail -f .sugar/sugar.log\n\n# Test single cycle\nsugar run --once\n```\n\n## \ud83d\udcda Documentation\n\n- **[Complete Documentation Hub](docs/README.md)** - All Sugar documentation\n- **[Quick Start Guide](docs/user/quick-start.md)** - Get up and running in 5 minutes\n- **[Local Development Setup](docs/dev/local-development.md)** - Install and test Sugar locally (before PyPI)\n- **[GitHub Integration](docs/user/github-integration.md)** - Connect Sugar to GitHub issues and PRs\n- **[Installation Guide](docs/user/installation-guide.md)** - Comprehensive installation and usage\n- **[CLI Reference](docs/user/cli-reference.md)** - Complete command reference \n- **[Contributing Guide](docs/dev/contributing.md)** - How to contribute to Sugar\n\n## \ud83c\udfaf Use Cases\n\n### Individual Developer\n- Continuous bug fixing from error logs\n- Automated test creation for uncovered code\n- Documentation updates when code changes\n- Code quality improvements during idle time\n\n### Development Team\n- Shared work discovery across team projects\n- Automated issue processing from GitHub\n- Continuous integration of feedback loops\n- 24/7 development progress across multiple repos\n\n### Product Teams\n- Autonomous handling of user feedback\n- Automated response to monitoring alerts\n- Continuous improvement of code quality metrics\n- Proactive maintenance and technical debt reduction\n\n## \ud83d\udd2e Roadmap\n\n- \u2705 **Phase 1**: Core loop, error discovery, basic execution\n- \u2705 **Phase 2**: Smart discovery (GitHub, code quality, test coverage) \n- \u2705 **Phase 3**: Learning and adaptation system\n- \ud83d\udea7 **Phase 4**: PyPI package distribution\n- \ud83d\udccb **Phase 5**: Enhanced integrations (Slack, Jira, monitoring systems)\n- \ud83d\udccb **Phase 6**: Team coordination and conflict resolution\n\n## \ud83e\udd1d Contributing\n\n1. Test changes with `--dry-run` and `--once`\n2. Validate configuration with `--validate`\n3. Check logs in `.sugar/sugar.log`\n4. Follow existing code patterns\n5. Update documentation for new features\n\n## \u2696\ufe0f Legal and Disclaimers\n\n### Terms of Service\nBy using Sugar, you agree to our [Terms of Service and Disclaimer](TERMS.md), which includes:\n- **No Warranty**: Software provided \"AS IS\" without warranties of any kind\n- **Limitation of Liability**: No responsibility for code damage, data loss, or system issues\n- **User Responsibility**: Users must review all AI-generated code before use\n- **Security**: Never use on production systems without proper testing and safeguards\n\n### Trademark Notice\nSugar is an independent third-party tool. \"Claude,\" \"Claude Code,\" and related marks are trademarks of Anthropic, Inc. Sugar is not affiliated with, endorsed by, or sponsored by Anthropic, Inc.\n\n### Risk Acknowledgment\n- AI-generated code may contain errors or security vulnerabilities\n- Always review and test generated code in safe environments\n- Maintain proper backups of your projects\n- Use appropriate security measures for your development environment\n\n## \ud83d\udcc4 License\n\nMIT License with additional disclaimers - see [LICENSE](LICENSE) and [TERMS.md](TERMS.md) for complete details.\n\n---\n\n**Sugar v1.7.2** - Built for Claude Code CLI autonomous development across any project or codebase.\n\n*Transform any project into an autonomous development environment with just `sugar init`.*\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Sugar - AI-powered autonomous development system for Claude Code CLI",
"version": "1.7.2",
"project_urls": {
"Bug Tracker": "https://github.com/cdnsteve/sugar/issues",
"Documentation": "https://docs.roboticforce.io/sugar",
"Homepage": "https://github.com/cdnsteve/sugar",
"Repository": "https://github.com/cdnsteve/sugar"
},
"split_keywords": [
"claude",
" autonomous",
" development",
" ai",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6836e5a285c6e59686a3d9b0e80375176c479f222b3dfb57640cdb85ef79fae2",
"md5": "c150fd1d7a1057884db2f8712d953bc3",
"sha256": "0a422a9b2c3b801d6d3f1219c3348bdd4ce5103ee0d9a96f8126802de7f5c731"
},
"downloads": -1,
"filename": "sugarai-1.7.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c150fd1d7a1057884db2f8712d953bc3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 89901,
"upload_time": "2025-08-25T17:39:51",
"upload_time_iso_8601": "2025-08-25T17:39:51.222477Z",
"url": "https://files.pythonhosted.org/packages/68/36/e5a285c6e59686a3d9b0e80375176c479f222b3dfb57640cdb85ef79fae2/sugarai-1.7.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "670d697b6a508d1334e5ce4f1291974b78244e8ebfc6a4f6408a66ff7e233d5d",
"md5": "74a0b1c99d2f2db14eb0aa1db35e94ef",
"sha256": "e84d340bd5d20ffc95f5a74407d44e7968efd29fd021d89623edc55897b405ae"
},
"downloads": -1,
"filename": "sugarai-1.7.2.tar.gz",
"has_sig": false,
"md5_digest": "74a0b1c99d2f2db14eb0aa1db35e94ef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 96675,
"upload_time": "2025-08-25T17:39:52",
"upload_time_iso_8601": "2025-08-25T17:39:52.522196Z",
"url": "https://files.pythonhosted.org/packages/67/0d/697b6a508d1334e5ce4f1291974b78244e8ebfc6a4f6408a66ff7e233d5d/sugarai-1.7.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-25 17:39:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cdnsteve",
"github_project": "sugar",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiosqlite",
"specs": [
[
">=",
"0.19.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "watchdog",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "gitpython",
"specs": [
[
">=",
"3.1.40"
]
]
},
{
"name": "structlog",
"specs": [
[
">=",
"23.0.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.1.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
}
],
"lcname": "sugarai"
}
JSON
