Skip to content

Commit b9ddd42

Browse files
committed
modify the readme to make it update
1 parent 21c376f commit b9ddd42

File tree

5 files changed

+572
-200
lines changed

5 files changed

+572
-200
lines changed

README.md

Lines changed: 67 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,39 @@
1+
<div align="center">
2+
13
# Sleepless Agent
24

3-
A 24/7 AI assistant daemon that continuously works on tasks via Slack. Uses Claude Code CLI via Python Agent SDK to process both random thoughts and serious jobs automatically with isolated workspaces.
4-
5-
## About
6-
7-
- Maintained by Context Machine Lab
8-
- Ships as `sleepless-agent` on PyPI (`pip install sleepless-agent`)
9-
- Automates task intake, execution, and reporting via Slack + Claude integration
10-
- Designed for continuous operation with isolated workspaces and automated git hygiene
11-
12-
## Full Precedure
13-
14-
1. Command arrives via CLI (sle think -p project "..." or sle think "...") or Slack (/think --project=project ... or /think ...)
15-
2. TaskQueue stores it in SQLite database with status PENDING
16-
3. Daemon polls every 5 seconds, calling _process_tasks()
17-
4. SmartScheduler decides if task can execute:
18-
- Checks budget (time-based quotas: 90% night, 10% day)
19-
- Checks available parallel slots
20-
- Prioritizes SERIOUS tasks (with -p/--project) over THOUGHT tasks (without -p)
21-
- Returns list of tasks to execute
22-
5. Daemon executes via _execute_task():
23-
- Marks task as IN_PROGRESS
24-
- Creates isolated workspace
25-
- Calls ClaudeCodeExecutor
26-
6. ClaudeCodeExecutor runs the task:
27-
- Builds enhanced prompt based on task type/priority
28-
- Calls Claude SDK with streaming
29-
- Tracks file modifications and commands
30-
- Returns results with metrics
31-
7. Daemon completes the flow:
32-
- Commits to git (for SERIOUS tasks)
33-
- Stores results in database
34-
- Marks as COMPLETED or FAILED
35-
- Sends Slack notification
36-
37-
38-
## Features
5+
**A 24/7 AgentOS that works while you sleep**
6+
7+
[![Documentation](https://img.shields.io/badge/Documentation-007ACC?style=for-the-badge&logo=markdown&logoColor=white)](https://context-machine-lab.github.io/sleepless-agent/)
8+
[![DeepWiki](https://img.shields.io/badge/DeepWiki-582C83?style=for-the-badge&logo=wikipedia&logoColor=white)](https://deepwiki.com/context-machine-lab/sleepless-agent)
9+
[![WeChat](https://img.shields.io/badge/WeChat-07C160?style=for-the-badge&logo=wechat&logoColor=white)](./assets/wechat.jpg)
10+
[![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/74my3Wkn)
11+
12+
</div>
13+
14+
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.
15+
16+
17+
## ✨ Features
3918

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

49-
## Prerequisites
28+
## ⚙️ Prerequisites
5029

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

57-
## Quick Start
36+
## 🚀 Quick Start
5837

5938
### 1. Install
6039

@@ -86,8 +65,7 @@ Visit https://api.slack.com/apps and create a new app:
8665

8766
**Create Slash Commands**
8867
Settings > Slash Commands > Create New Command:
89-
- `/task` - Add serious task
90-
- `/think` - Capture random thought
68+
- `/think` - Capture thought or task (use `-p project-name` for serious tasks)
9169
- `/check` - Check queue status
9270
- `/cancel` - Cancel task or project
9371
- `/report` - Show reports or task details
@@ -119,11 +97,7 @@ Set:
11997
### 4. Run
12098

12199
```bash
122-
# Terminal 1: Start the daemon
123100
sle daemon
124-
125-
# Terminal 2 (optional): Monitor logs
126-
tail -f workspace/data/agent.log
127101
```
128102

129103
You should see startup logs similar to:
@@ -133,48 +107,33 @@ You should see startup logs similar to:
133107
```
134108
Logs are rendered with Rich for readability; set `SLEEPLESS_LOG_LEVEL=DEBUG` to increase verbosity.
135109

136-
### Logging
137-
138-
Rich console output is powered by [Rich](https://rich.readthedocs.io/) and now mirrors the structured events that feed our JSON logs. Every console line maps to a canonical `event` (for example `task.phase.done`, `scheduler.dispatch`, `usage.snapshot`) so you can skim the terminal or process the data programmatically.
139-
140-
Structured copies of each log line are written to JSONL files under `workspace/.logs` by default (override with `SLEEPLESS_LOG_DIR`). These files preserve context such as `task_id`, `phase`, `usage_percent`, and timing deltas, making it easy to build dashboards or run ad-hoc analysis later.
141110

142-
Set `SLEEPLESS_LOG_LEVEL` to tune verbosity; `DEBUG` includes low-level worker/evaluator metrics while `INFO` keeps to lifecycle milestones.
143-
144-
145-
## Slack Commands
111+
## 💬 Slack Commands
146112

147113
All Slack commands align with the CLI commands for consistency:
148114

149115
### 📋 Task Management
150116

151117
| Command | Purpose | Example |
152118
|---------|---------|---------|
153-
| `/task` | Add serious task | `/task Add OAuth2 support` |
154-
| `/task` | With project | `/task Add OAuth2 support --project=backend` |
155119
| `/think` | Capture random thought | `/think Explore async ideas` |
120+
| `/think -p <project>` | Add serious task to project | `/think Add OAuth2 support -p backend` |
156121
| `/check` | Show system status | `/check` |
157122
| `/cancel` | Cancel task or project | `/cancel 5` or `/cancel my-app` |
158123

159124
### 📊 Reporting & Trash
160125

161126
| Command | Purpose | Example |
162127
|---------|---------|---------|
163-
| `/report` | Today's report | `/report` |
164-
| `/report` | Task details | `/report 42` |
165-
| `/report` | Date report | `/report 2025-10-22` |
166-
| `/report` | Project report | `/report my-app` |
167-
| `/report` | List all reports | `/report --list` |
168-
| `/trash` | List trash | `/trash list` |
169-
| `/trash` | Restore project | `/trash restore my-app` |
170-
| `/trash` | Empty trash | `/trash empty` |
128+
| `/report` | Today's report, task details, date/project report, or list all | `/report`, `/report 42`, `/report 2025-10-22`, `/report my-app`, `/report --list` |
129+
| `/trash` | List, restore, or empty trash | `/trash list`, `/trash restore my-app`, `/trash empty` |
171130

172-
## Command Line Interface
131+
## ⌨️ Command Line Interface
173132

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

176135
```bash
177-
python -m sleepless_agent.interfaces.cli task "Ship release checklist"
136+
python -m sleepless_agent.interfaces.cli think "Ship release checklist" -p my-app
178137
# or, after installing the package:
179138
sle check
180139
```
@@ -183,20 +142,20 @@ The CLI mirrors the Slack slash commands:
183142

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

193152
Override storage locations when needed:
194153

195154
```bash
196-
sle --db-path ./tmp/tasks.db --results-path ./tmp/results status
155+
sle --db-path ./tmp/tasks.db --results-path ./tmp/results check
197156
```
198157

199-
## Architecture
158+
## 🏗️ Architecture
200159

201160
```
202161
Slack Bot
@@ -222,7 +181,7 @@ Result Manager (Storage + Git)
222181
- **git_manager.py**: Git automation (commits, PRs)
223182
- **monitor.py**: Health checks and metrics
224183

225-
## File Structure
184+
## 📁 File Structure
226185

227186
```
228187
sleepless-agent/
@@ -254,79 +213,63 @@ sleepless-agent/
254213
└── docs/ # Additional documentation
255214
```
256215

257-
## Configuration
216+
## ⚙️ Configuration
258217

259218
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.
260219

261-
### Pro Plan Usage Management
220+
### Usage Management
262221

263-
The agent automatically monitors your Claude Code Pro plan usage and prevents task overruns with an **85% usage pause threshold**. This ensures you never accidentally exhaust your message limit.
222+
The agent automatically monitors Claude Code usage and intelligently manages task execution based on configurable thresholds.
264223

265224
**How it works:**
266225

267-
1. **Usage Monitoring** - Every task checks your Pro plan usage via `claude /usage` command
268-
2. **Pause Threshold (85%)** - When usage reaches 85%, task generation automatically stops
269-
3. **Resume on Reset** - Tasks resume after your 5-hour window resets
270-
4. **Time-based Quotas** - Budget is split: 90% for night (8 PM - 8 AM), 10% for day (8 AM - 8 PM)
226+
1. **Usage Monitoring** - Every task checks usage via `claude /usage` command
227+
2. **Time-based Thresholds** - Different thresholds for day and night operations
228+
3. **Smart Scheduling** - Automatically pauses task generation when threshold is reached
229+
4. **Automatic Resume** - Tasks resume when usage resets
271230

272-
**Example flow:**
273-
```
274-
- Start of window: 0/40 messages (0% - all green)
275-
- Mid-window: 28/40 messages (70% - status OK, tasks continue)
276-
- Threshold reached: 34/40 messages (85% - tasks pause, logs warning)
277-
- Window resets: 0/40 messages (resets at 18:59:00, tasks resume)
278-
```
231+
**Time-Based Configuration (configurable in `config.yaml`):**
232+
- **Nighttime (1 AM - 9 AM by default):** 96% threshold - agent works aggressively while you sleep
233+
- **Daytime (9 AM - 1 AM by default):** 95% threshold - preserves capacity for your manual usage
234+
- Configure via: `claude_code.threshold_day`, `claude_code.threshold_night`
235+
- Time ranges via: `claude_code.night_start_hour`, `claude_code.night_end_hour`
279236

280237
**Visibility:**
281-
- Dashboard: Shows `Pro Usage: X% / Y% limit` in `sle check` (Y = 20% daytime, 80% nighttime)
282-
- Logs: Each usage check logs Pro plan usage with time-based threshold
283-
- Config: Adjustable via `claude_code.threshold_day` and `claude_code.threshold_night` in `config.yaml`
284-
285-
**Time-Based Thresholds:**
286-
- **Daytime (8 AM - 8 PM):** Pause at 20% (saves quota for your manual usage)
287-
- **Nighttime (8 PM - 8 AM):** Pause at 80% (agent works aggressively while you sleep)
288-
- Time ranges are configurable via `claude_code.night_start_hour` and `claude_code.night_end_hour` in `config.yaml`
238+
- Dashboard: Shows usage percentage in `sle check`
239+
- Logs: Each usage check logs current usage with applicable threshold
240+
- Config: All thresholds and time ranges adjustable in `config.yaml`
241+
242+
**Behavior at threshold:**
289243
- ⏸️ New task generation pauses at threshold
290244
- ✅ Running tasks complete normally
291245
- 📋 Pending tasks wait in queue
292-
- ⏱️ Grace period: +1 minute after reset to avoid edge cases
246+
- ⏱️ Automatic resume when usage resets
293247

294-
**Note:** Pro plan usage monitoring is mandatory and always enabled.
295-
296-
## Environment Variables
248+
## 🔧 Environment Variables
297249

298250
```bash
299251
# Required
300252
SLACK_BOT_TOKEN=xoxb-...
301253
SLACK_APP_TOKEN=xapp-...
302-
303-
# Optional
304-
AGENT_WORKSPACE=./workspace
305-
AGENT_DB_PATH=./workspace/data/tasks.db
306-
AGENT_RESULTS_PATH=./workspace/data/results
307-
GIT_USER_NAME=Sleepless Agent
308-
309-
SLEEPLESS_LOG_LEVEL=INFO
310-
SLEEPLESS_LOG_DIR=workspace/.logs
311254
```
312255

313-
## Task Types
256+
## 📝 Task Types
314257

315258
The agent intelligently processes different task types:
316259

317-
1. **Thoughts** - Auto-commits to `thought-ideas` branch
260+
1. **Random Thoughts** - Auto-commits to `thought-ideas` branch
318261
```
319262
/think Research async patterns in Rust
320263
/think What's the best way to implement caching?
321264
```
322265

323-
2. **Serious Jobs** - Creates feature branch and PR, requires review
266+
2. **Serious Tasks** - Creates feature branch and PR, requires review (use `-p` flag)
324267
```
325-
/task Add authentication to user service
326-
/task Refactor payment processing module
268+
/think Add authentication to user service -p backend
269+
/think Refactor payment processing module -p payments
327270
```
328271

329-
## Development
272+
## 🛠️ Development
330273

331274
### Add New Task Type
332275

@@ -352,7 +295,7 @@ pytest
352295
SLEEPLESS_LOG_LEVEL=DEBUG python -m sleepless_agent.daemon
353296
```
354297

355-
## Monitoring
298+
## 📊 Monitoring
356299

357300
### Real-time Logs
358301
```bash
@@ -375,7 +318,7 @@ tail -100 workspace/data/metrics.jsonl | jq .
375318
/report --list # Available reports
376319
```
377320

378-
## Deployment
321+
## 🚢 Deployment
379322

380323
### Linux (systemd)
381324
```bash
@@ -389,7 +332,7 @@ make install-launchd
389332
launchctl list | grep sleepless
390333
```
391334

392-
## Example Workflows
335+
## 💡 Example Workflows
393336

394337
### Daily Brainstorm
395338
```
@@ -401,18 +344,18 @@ launchctl list | grep sleepless
401344

402345
### Production Fix
403346
```
404-
/task Fix authentication bug in login endpoint
347+
/think Fix authentication bug in login endpoint -p backend
405348
/report <id> # Get the PR link
406349
# Review and merge PR
407350
```
408351

409352
### Code Audit
410353
```
411-
/task Security audit of user service
412-
/task Performance analysis of payment module
354+
/think Security audit of user service -p backend
355+
/think Performance analysis of payment module -p payments
413356
```
414357

415-
## Troubleshooting
358+
## 🔍 Troubleshooting
416359

417360
| Issue | Solution |
418361
|-------|----------|
@@ -423,36 +366,28 @@ launchctl list | grep sleepless
423366
| Out of credits | Wait for 5-hour window refresh. Review scheduler logs: `tail -f workspace/data/agent.log | grep credit` |
424367
| Database locked | Close other connections, try: `rm workspace/data/tasks.db && python -m sleepless_agent.daemon` |
425368

426-
## Performance Tips
369+
## Performance Tips
427370

428371
1. **Use thoughts to fill idle time** - Maximizes usage
429-
2. **Batch serious jobs** - Reduces context switching
372+
2. **Batch serious tasks** - Reduces context switching
430373
3. **Monitor credits** - Watch scheduler logs for window resets
431374
4. **Review git history** - Check `thought-ideas` branch regularly
432375
5. **Check metrics** - Run `sle check` to track performance
433376

434-
## Security Notes
377+
## 🔒 Security Notes
435378

436379
- Secrets are validated before git commits
437380
- Python syntax checked before commits
438381
- Directory traversal prevented in file operations
439382
- .env file never committed to git
440383
- Workspace changes validated before applying
441384

442-
## Releases
385+
## 📦 Releases
443386

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

448-
## Additional Documentation
449-
450-
For more detailed information, see the docs/ folder:
451-
452-
- **[GETTING_STARTED.md](docs/GETTING_STARTED.md)** - Detailed setup guide and architecture overview
453-
- **[QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md)** - Command reference and quick tips
454-
- **[CLAUDE_CODE_REDESIGN.md](docs/CLAUDE_CODE_REDESIGN.md)** - Technical design document for Claude Code migration
455-
456-
## License
391+
## 📄 License
457392

458393
Released under the [MIT License](LICENSE)

0 commit comments

Comments
 (0)