Skip to content

Quickstart Guide

Get Sleepless Agent running in 5 minutes! This guide covers the minimal setup needed to start processing tasks.

Prerequisites

Before starting, ensure you have:

  • ✅ Python 3.11+ installed
  • ✅ Node.js 16+ installed
  • ✅ Slack workspace access
  • ✅ Claude Code CLI installed

Step 1: Install Claude Code CLI

npm install -g @anthropic-ai/claude-code

Verify installation: 

claude --version

Step 2: Install Sleepless Agent

pip install sleepless-agent

Or from source: 

git clone https://github.com/context-machine-lab/sleepless-agent
cd sleepless-agent
pip install -e .

Step 3: Quick Slack Setup

  1. Visit https://api.slack.com/apps
  2. Click "Create New App" → "From scratch"
  3. Name it "Sleepless Agent" and select your workspace

Enable Socket Mode

  • Go to Settings → Socket Mode → Enable
  • Create an app-level token (name: "sleepless-token")
  • Save the xapp-... token

Add Slash Commands

Go to Features → Slash Commands and create: - /think - Submit tasks - /check - Check status - /chat - Interactive chat mode with Claude - /usage - Show Claude Code Pro plan usage

Set Bot Permissions

Features → OAuth & Permissions → Bot Token Scopes: - chat:write - commands - channels:history (for chat mode) - reactions:write (for chat mode)

Enable Events (for Chat Mode)

Features → Event Subscriptions → Enable Events → Subscribe to bot events: - message.channels - message.groups

Install to Workspace

  • Click "Install to Workspace"
  • Save the xoxb-... bot token

Step 4: Configure Environment

Create a .env file:

# Required Slack tokens
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here

# Optional: Custom workspace location
AGENT_WORKSPACE=./workspace

Step 5: Start the Agent

sle daemon

You should see: 

2025-10-24 23:30:12 | INFO | Sleepless Agent starting...
2025-10-24 23:30:12 | INFO | Slack bot started and listening for events

Step 6: Test Your Setup

In Slack, try these commands:

/think Research Python async patterns
/check

The agent should acknowledge your task and show the queue status.

Try Chat Mode

Start an interactive session with Claude:

/chat my-project

This creates a Slack thread where you can have a real-time conversation with Claude.

⚠️ Important: All messages to Claude must be sent inside the thread, not in the main channel. Claude will only respond to messages within the chat thread.

In the thread, try: 

Create a hello world Python script

To end the session, type exit in the thread or use /chat end.

What's Next?

Essential Configuration

  1. Set up Git integration for automated commits: 

    git config --global user.name "Sleepless Agent"
git config --global user.email "agent@sleepless.local"

  2. Configure Pro plan thresholds in config.yaml: 

    claude_code:
  threshold_day: 20.0    # Pause at 20% during day
  threshold_night: 80.0  # Pause at 80% at night

  3. Set working hours for optimal usage: 

    claude_code:
  night_start_hour: 20  # 8 PM
  night_end_hour: 8     # 8 AM

Common Issues

Agent not responding in Slack?

  • Verify Socket Mode is enabled
  • Check both tokens are correct in .env
  • Ensure the bot is in your channel

Tasks not executing?

  • Run claude --version to verify CLI installation
  • Check sle check for usage limits
  • Review logs: tail -f workspace/data/agent.log

Usage threshold reached?

  • Agent pauses at configured thresholds
  • Wait for 5-hour window reset
  • Adjust thresholds in config.yaml if needed

Getting Help

🎉 Congratulations! You now have a 24/7 AI agent working for you. Check out the tutorials to learn more advanced features.