✨ Features

• 🤖 Continuous Operation: Runs 24/7 daemon, always ready for new tasks
• 💬 Slack Integration: Submit tasks via Slack commands
• 💭 Interactive Chat Mode: Real-time conversational sessions with Claude in Slack threads
• 🎯 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+
• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
• Git (for auto-commits)
• gh CLI (optional, for PR automation)
• Slack workspace admin access (optional — the sle CLI works without Slack)

💡 Slack is optional. You can run all sle CLI commands without configuring Slack. Slack integration adds a convenient real-time interface for submitting tasks and checking status, but every feature is also available via the CLI.

🚀 Quick Start

1. Install

pip install sleepless-agent

Or for development:

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

⚠️ Windows / WSL tip: After pip install, the sle command might not be found if Python's Scripts directory is not on your PATH. See Troubleshooting: sle not found below.

2. Authenticate Claude Code (Required)

# Install the Claude Code CLI (requires Node.js)
npm install -g @anthropic-ai/claude-code

# Log in once (opens a browser)
claude login

# Verify
claude --version

3. (Optional) Start without Slack

Slack integration is not required. You can use the sle CLI directly:

# Start the daemon (no Slack needed)
sle daemon

# Queue a task
sle think "Research async Python patterns"

# Check status
sle check

If you want Slack integration, continue with the setup below.

4. 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)
• /chat - Start interactive chat mode with Claude
• /check - Check queue status
• /usage - Show Claude Code Pro plan usage
• /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
• channels:history (for chat mode)
• groups:history (for chat mode in private channels)
• reactions:write (for chat mode indicators)

Event Subscriptions (for Chat Mode) Features > Event Subscriptions > Enable Events > Subscribe to bot events:

• message.channels
• message.groups

Install App

• Install to workspace
• Get bot token (starts with xoxb-)

5. Configure Environment

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)

6. Run

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.

🖥️ Windows / WSL: sle Command Not Found

If sle is not recognised after pip install on Windows or WSL, the Python Scripts directory is likely not on your PATH.

Windows (PowerShell / CMD)

# Find where pip installed the script
python -m site --user-scripts

# Add that directory to PATH permanently (PowerShell)
$scriptsDir = python -m site --user-scripts
[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;$scriptsDir", "User")

# Or run sle directly with python -m
python -m sleepless_agent.interfaces.cli --help

WSL (Ubuntu / Debian)

# Add the local bin directory to PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify
sle --version

System-wide pip install (not recommended)

If you used sudo pip install, the script will be in /usr/local/bin which is normally already in PATH. However, prefer using a virtual environment or pip install --user.

Virtual environment (recommended)

Using a virtual environment avoids PATH issues on all platforms:

python -m venv venv
# Windows:
venv\Scripts\activate
# macOS / Linux / WSL:
source venv/bin/activate

pip install sleepless-agent
sle --version  # always works inside the venv

💬 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 | | /usage | Show Claude Code Pro usage | /usage | | /cancel | Cancel task or project | /cancel 5 or /cancel my-app |

💭 Interactive Chat Mode

Start a real-time conversation with Claude in a dedicated Slack thread:

| Command | Purpose | Example | |---------|---------|---------| | /chat <project> | Start chat mode for a project | /chat my-backend | | /chat end | End current chat session | /chat end | | /chat status | Check active session status | /chat status | | /chat help | Show chat mode help | /chat help |

Chat Mode Features:

• 🧵 Dedicated thread for each session
• 💬 Full conversation history maintained
• 🔄 Real-time processing indicator
• 📁 Claude can read/write/edit files in project workspace
• ⏱️ Auto-timeout after 30 minutes of inactivity
• Type exit in thread to end session

💡 Note: When you run /chat <project>, a new thread is created. All your prompts must be sent inside this thread - Claude only responds to messages within the chat thread, not in the main channel.

📊 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:

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 | |---------|---------|-