Metadata-Version: 2.4
Name: sleepless-agent
Version: 0.1.2
Summary: 24/7 AI agent that maximizes Claude usage via Slack interface
Author: Sleepless Agent Maintainers
License: MIT License
        
        Copyright (c) 2024 Context Machine Lab
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/context-machine-lab/sleepless-agent
Project-URL: Repository, https://github.com/context-machine-lab/sleepless-agent
Keywords: ai,automation,agents,slack,anthropic
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Office/Business
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic
Requires-Dist: slack-sdk
Requires-Dist: sqlalchemy
Requires-Dist: python-dotenv
Requires-Dist: PyYAML
Requires-Dist: gitpython
Requires-Dist: aiosqlite
Requires-Dist: loguru
Requires-Dist: rich
Requires-Dist: structlog
Requires-Dist: psutil
Requires-Dist: claude-agent-sdk
Requires-Dist: requests
Dynamic: license-file

<div align="center">

# Sleepless Agent

**A 24/7 AgentOS that works while you sleep**

[![Documentation](https://img.shields.io/badge/Documentation-007ACC?style=for-the-badge&logo=markdown&logoColor=white)](https://context-machine-lab.github.io/sleepless-agent/)
[![DeepWiki](https://img.shields.io/badge/DeepWiki-582C83?style=for-the-badge&logo=wikipedia&logoColor=white)](https://deepwiki.com/context-machine-lab/sleepless-agent)
[![WeChat](https://img.shields.io/badge/WeChat-07C160?style=for-the-badge&logo=wechat&logoColor=white)](./assets/wechat.jpg)
[![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/74my3Wkn)

</div>

Have Claude Code Pro but not using it at night? Transform it into an AgentOS that handles your ideas and tasks while you sleep. This is a 24/7 AI assistant daemon powered by Claude Code CLI and Python Agent SDK that processes both random thoughts and serious tasks via Slack with isolated workspaces.

## 📰 News

- **[2025-10-26]** 🎉 Initial release v0.1.0 - Full AgentOS with multi-agent workflow support
- **[2025-10-25]** 🚀 Added task auto-generation with configurable strategies
- **[2025-10-24]** 🔧 Integrated Git management with automatic PR creation
- **[2025-10-23]** 📊 Implemented isolated workspaces for parallel task execution
- **[2025-10-22]** 💡 Added Claude Code Python Agent SDK integration

## 🎬 Demo

<div align="center">
  <img src="assets/cli.png" alt="Sleepless Agent CLI Demo" width="800">
  <p><em>Sleepless Agent CLI in action - managing tasks, checking status, and generating reports</em></p>
</div>

### Quick Example

```bash
# Start the daemon
$ sle daemon
2025-10-26 03:30:12 | INFO | Sleepless Agent starting...
2025-10-26 03:30:12 | INFO | Slack bot connected

# Submit a task via Slack
/think Implement OAuth2 authentication -p backend

# Check status
$ sle check
╭─────────────────── System Status ───────────────────╮
│ 🟢 Daemon: Running                                  │
│ 📊 Queue: 3 pending, 1 in_progress                  │
│ 💻 Usage: 45% (Day threshold: 95%)                  │
│ 🔄 Last task: "Implement OAuth2..." (in progress)   │
╰─────────────────────────────────────────────────────╯

# View results
$ sle report 42
Task #42: ✅ Completed
Branch: feature/backend-42
PR: https://github.com/user/repo/pull/123
```

## ✨ Features

- 🤖 **Continuous Operation**: Runs 24/7 daemon, always ready for new tasks
- 💬 **Slack Integration**: Submit tasks via Slack commands
- 🎯 **Hybrid Autonomy**: Auto-applies random thoughts, requires review for serious tasks
- ⚡ **Smart Scheduling**: Optimizes task execution based on priorities
- 📊 **Task Queue**: SQLite-backed persistent task management
- 🔌 **Claude Code SDK**: Uses Python Agent SDK to interface with Claude Code CLI
- 🏗️ **Isolated Workspaces**: Each task gets its own workspace for true parallelism
- 📝 **Result Storage**: All outputs saved with metadata for future reference

## ⚙️ Prerequisites

- Python 3.11+
- Slack workspace admin access
- Claude Code CLI installed (`npm install -g @anthropic-ai/claude-code`)
- Git (for auto-commits)
- gh CLI (optional, for PR automation)

## 🚀 Quick Start

### 1. Install

```bash
pip install sleepless-agent
```

Or for development:
```bash
git clone <repo>
cd sleepless-agent
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -e .
```

### 2. Setup Slack App

Visit https://api.slack.com/apps and create a new app:

**Basic Information**
- Choose "From scratch"
- Name: "Sleepless Agent"
- Pick your workspace

**Enable Socket Mode**
- Settings > Socket Mode > Toggle ON
- Generate app token (starts with `xapp-`)

**Create Slash Commands**
Settings > Slash Commands > Create New Command:
- `/think` - Capture thought or task (use `-p project-name` for serious tasks)
- `/check` - Check queue status
- `/cancel` - Cancel task or project
- `/report` - Show reports or task details
- `/trash` - Manage trash (list, restore, empty)

**OAuth Scopes**
Features > OAuth & Permissions > Bot Token Scopes:
- `chat:write`
- `commands`
- `app_mentions:read`

**Install App**
- Install to workspace
- Get bot token (starts with `xoxb-`)

### 3. Configure Environment

```bash
cp .env.example .env
nano .env  # Edit with your tokens
```

Set:
- `SLACK_BOT_TOKEN` - xoxb-... token
- `SLACK_APP_TOKEN` - xapp-... token

(Claude API key no longer needed - uses Claude Code CLI)

### 4. Run

```bash
sle daemon
```

You should see startup logs similar to:
```
2025-10-24 23:30:12 | INFO     | sleepless_agent.interfaces.bot.start:50 Slack bot started and listening for events
2025-10-24 23:30:12 | INFO     | sleepless_agent.runtime.daemon.run:178 Sleepless Agent starting...
```
Logs are rendered with Rich for readability; set `SLEEPLESS_LOG_LEVEL=DEBUG` to increase verbosity.


## 💬 Slack Commands

All Slack commands align with the CLI commands for consistency:

### 📋 Task Management

| Command | Purpose | Example |
|---------|---------|---------|
| `/think` | Capture random thought | `/think Explore async ideas` |
| `/think -p <project>` | Add serious task to project | `/think Add OAuth2 support -p backend` |
| `/check` | Show system status | `/check` |
| `/cancel` | Cancel task or project | `/cancel 5` or `/cancel my-app` |

### 📊 Reporting & Trash

| Command | Purpose | Example |
|---------|---------|---------|
| `/report` | Today's report, task details, date/project report, or list all | `/report`, `/report 42`, `/report 2025-10-22`, `/report my-app`, `/report --list` |
| `/trash` | List, restore, or empty trash | `/trash list`, `/trash restore my-app`, `/trash empty` |

## ⌨️ Command Line Interface

Install the project (or run within the repo) and use the bundled CLI:

```bash
python -m sleepless_agent.interfaces.cli think "Ship release checklist" -p my-app
# or, after installing the package:
sle check
```

The CLI mirrors the Slack slash commands:

| Command | Purpose | Example |
|---------|---------|---------|
| `think <description>` | Capture a random thought | `think "Explore async patterns"` |
| `think <description> -p <project>` | Queue a serious task to project | `think "Build onboarding flow" -p backend` |
| `check` | Show system health, queue, and performance metrics | `check` |
| `report [identifier]` | Show task details, daily reports, or project summaries (`--list` for all reports) | `report 7` |
| `cancel <identifier>` | Move a task or project to trash | `cancel 9` or `cancel my-app` |
| `trash [subcommand] [identifier]` | Manage trash (list, restore, empty) | `trash restore my-app` |

Override storage locations when needed:

```bash
sle --db-path ./tmp/tasks.db --results-path ./tmp/results check
```

## 🏗️ Architecture

```
Slack Bot
    ↓
Slack Commands → Task Queue (SQLite)
    ↓
Agent Daemon (Event Loop)
    ↓
Claude Executor (Claude Code CLI)
    ↓
Result Manager (Storage + Git)
```

### Components

- **daemon.py**: Main event loop, task orchestration
- **bot.py**: Slack interface, command parsing
- **task_queue.py**: Task CRUD, priority scheduling
- **claude_code_executor.py**: Python Agent SDK wrapper with isolated workspace management
- **results.py**: Result storage, file management
- **models.py**: SQLAlchemy models for Task, Result
- **config.yaml**: Configuration defaults
- **git_manager.py**: Git automation (commits, PRs)
- **monitor.py**: Health checks and metrics

## 📁 File Structure

```
sleepless-agent/
├── src/sleepless_agent/
│   ├── __init__.py
│   ├── daemon.py           # Main event loop
│   ├── bot.py              # Slack interface
│   ├── task_queue.py       # Task management
│   ├── claude_code_executor.py  # Claude CLI wrapper
│   ├── scheduler.py        # Smart scheduling
│   ├── git_manager.py      # Git automation
│   ├── monitor.py          # Health & metrics
│   ├── models.py           # Database models
│   ├── results.py          # Result storage
│   └── config.yaml         # Config defaults
├── workspace/              # All persistent data and task workspaces
│   ├── data/               # Persistent storage
│   │   ├── tasks.db        # SQLite database
│   │   ├── results/        # Task output files
│   │   ├── reports/        # Daily markdown reports
│   │   ├── agent.log       # Application logs
│   │   └── metrics.jsonl   # Performance metrics
│   ├── tasks/              # Task workspaces (task_1/, task_2/, etc.)
│   ├── projects/           # Project workspaces
│   └── trash/              # Soft-deleted projects
├── .env                    # Secrets (not tracked)
├── pyproject.toml          # Python package metadata & dependencies
├── README.md              # This file
└── docs/                  # Additional documentation
```

## ⚙️ Configuration

Runtime settings come from environment variables loaded via `.env` (see `.env.example`). Update those values or export them in your shell to tune agent behavior.

### Usage Management

The agent automatically monitors Claude Code usage and intelligently manages task execution based on configurable thresholds.

**How it works:**

1. **Usage Monitoring** - Every task checks usage via `claude /usage` command
2. **Time-based Thresholds** - Different thresholds for day and night operations
3. **Smart Scheduling** - Automatically pauses task generation when threshold is reached
4. **Automatic Resume** - Tasks resume when usage resets

**Time-Based Configuration (configurable in `config.yaml`):**
- **Nighttime (1 AM - 9 AM by default):** 96% threshold - agent works aggressively while you sleep
- **Daytime (9 AM - 1 AM by default):** 95% threshold - preserves capacity for your manual usage
- Configure via: `claude_code.threshold_day`, `claude_code.threshold_night`
- Time ranges via: `claude_code.night_start_hour`, `claude_code.night_end_hour`

**Visibility:**
- Dashboard: Shows usage percentage in `sle check`
- Logs: Each usage check logs current usage with applicable threshold
- Config: All thresholds and time ranges adjustable in `config.yaml`

**Behavior at threshold:**
- ⏸️ New task generation pauses at threshold
- ✅ Running tasks complete normally
- 📋 Pending tasks wait in queue
- ⏱️ Automatic resume when usage resets

### Git Management

The agent integrates deeply with Git for automatic version control and collaboration:

**Remote Repository Configuration (`config.yaml`):**
- `git.use_remote_repo`: Enable/disable remote repository integration
- `git.remote_repo_url`: Your remote repository URL (e.g., `git@github.com:username/repo.git`)
- `git.auto_create_repo`: Automatically create repository if it doesn't exist

**Git Workflow:**
- **Random Thoughts**: Auto-commits to `thought-ideas` branch
- **Serious Tasks (-p flag)**: Creates feature branches (`feature/<project>-<task_id>`) and opens PRs
- **Automatic Commits**: Each task completion triggers a commit with descriptive messages
- **PR Creation**: Serious tasks automatically create pull requests for review

**Important:** Update `git.remote_repo_url` in `config.yaml` before running the agent!

### Multi-Agent Workflow

The agent employs a sophisticated multi-agent architecture for complex task processing:

**Agent Types (`config.yaml`):**
- **Planner Agent**: Analyzes tasks and creates execution plans (max 3 turns by default)
- **Worker Agent**: Executes the planned tasks (max 3 turns by default)
- **Evaluator Agent**: Reviews and validates completed work (max 3 turns by default)

**Configuration:**
```yaml
multi_agent_workflow:
  planner:
    enabled: true
    max_turns: 3
  worker:
    enabled: true
    max_turns: 3
  evaluator:
    enabled: true
    max_turns: 3
```

Each agent can be independently enabled/disabled and configured with different turn limits to control execution depth.

### Task Auto-Generation

The agent can automatically generate tasks to keep itself productive during idle time:

**Generation Strategies (`config.yaml`):**
- **refine_focused (45% weight)**: Focuses on completing or improving existing work
- **balanced (35% weight)**: Mix of refinements and new tasks based on workspace state
- **new_friendly (20% weight)**: Prioritizes creating innovative new projects

**Task Types:**
- **[NEW]**: Creates a new task in an isolated workspace (`workspace/tasks/<task_id>/`)
- **[REFINE:#<id>]**: Improves specific existing task (reuses task workspace)
- **[REFINE]**: General refinement of workspace projects

**Workspace Constraints:**
- Each task executes in its own isolated directory
- Tasks only access their workspace and `workspace/shared/`
- System directories (`workspace/data/`) are protected
- REFINE tasks reuse existing workspaces for continuity


## 🔧 Environment Variables

```bash
# Required
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
```

**Note:** Most configuration is done via `config.yaml`. Environment variables are primarily for secrets and deployment-specific settings.

## 📝 Task Types

The agent intelligently processes different task types:

1. **Random Thoughts** - Auto-commits to `thought-ideas` branch
   ```
   /think Research async patterns in Rust
   /think What's the best way to implement caching?
   ```

2. **Serious Tasks** - Creates feature branch and PR, requires review (use `-p` flag)
   ```
   /think -p backend Add authentication to user service
   /think -p payments Refactor payment processing module
   ```

## 📊 Monitoring

### Slack Commands
```
/check    # System status and performance stats
/report --list  # Available reports
```

## 🚢 Deployment

### Linux (systemd)
```bash
make install-service
sudo systemctl start sleepless-agent
```

### macOS (launchd)
```bash
make install-launchd
launchctl list | grep sleepless
```

## 💡 Example Workflows

### Daily Brainstorm
```
/think Research new Rust async libraries
/think Compare Python web frameworks
/think Ideas for improving API performance
/check
```

### Production Fix
```
/think Fix authentication bug in login endpoint -p backend
/report <id>     # Get the PR link
# Review and merge PR
```

### Code Audit
```
/think Security audit of user service -p backend
/think Performance analysis of payment module -p payments
```

## ⚡ Performance Tips

1. **Use thoughts to fill idle time** - Maximizes usage
2. **Batch serious tasks** - Reduces context switching
3. **Monitor usage** - Watch scheduler logs for usage patterns
4. **Review git history** - Check `thought-ideas` branch regularly
5. **Check metrics** - Run `sle check` to track performance

## 📦 Releases

- Latest stable: **0.1.0** – published on [PyPI](https://pypi.org/project/sleepless-agent/0.1.0/)
- Install or upgrade with `pip install -U sleepless-agent`
- Release notes tracked via GitHub Releases (tag `v0.1.0` onward)

## 📚 Documentation

For more detailed information and guides:

- **[Full Documentation](https://context-machine-lab.github.io/sleepless-agent/)** - Complete documentation site
- **[DeepWiki](https://deepwiki.com/context-machine-lab/sleepless-agent)** - Interactive knowledge base
- **[Installation Guide](docs/installation.md)** - Detailed setup instructions
- **[Quick Start](docs/quickstart.md)** - Get up and running quickly
- **[FAQ](docs/faq.md)** - Frequently asked questions
- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions

## 🗺️ Roadmap

- [ ] **Advanced Scheduling** - Priority queue with time-based and dependency scheduling
- [ ] **Daily Report** - Daily report of the agent's work

## 🙏 Acknowledgements

We are deeply grateful to the open-source community and the projects that make Sleepless Agent possible:

- **[Claude Code CLI](https://github.com/anthropics/claude-code)** - For providing the powerful foundation for AI-assisted development and the Python Agent SDK that enables seamless integration
- **[Slack Bolt](https://github.com/slackapi/bolt-python)** - For reliable real-time messaging and command handling that powers our Slack integration
- **[SQLAlchemy](https://www.sqlalchemy.org/)** - For robust data persistence and elegant ORM that manages our task queue
- **[Rich](https://github.com/Textualize/rich)** - For beautiful terminal rendering that makes logs and outputs visually appealing
- **[GitPython](https://github.com/gitpython-developers/GitPython)** - For comprehensive Git operations that enable our automated version control workflows

## 🤝 Contributing

We welcome contributions! Sleepless Agent is designed to be a community resource for 24/7 AI development automation.

Please see our [Contributing Guidelines](CONTRIBUTING.md) for:
- Development setup and environment configuration
- Code style and testing requirements
- How to submit pull requests
- Community guidelines and code of conduct

Feel free to:
- 🐛 [Report bugs](https://github.com/context-machine-lab/sleepless-agent/issues/new?labels=bug)
- 💡 [Suggest features](https://github.com/context-machine-lab/sleepless-agent/issues/new?labels=enhancement)
- 💬 [Ask questions](https://github.com/context-machine-lab/sleepless-agent/discussions)
- 🔧 [Submit pull requests](https://github.com/context-machine-lab/sleepless-agent/pulls)

## 📖 Citation

If you use Sleepless Agent in your research or projects, please cite:

```bibtex
@software{sleepless_agent_2025,
  title = {Sleepless Agent: A 24/7 AgentOS for Continuous Development},
  author = {Zhimeng Guo, Hangfan Zhang, Siyuan Xu, Huaisheng Zhu, Teng Xiao, Minhao Cheng},
  year = {2025},
  publisher = {GitHub},
  journal = {GitHub repository},
  url = {https://github.com/context-machine-lab/sleepless-agent}
}
```

## 📄 License

Released under the [MIT License](LICENSE)
