Sleepless Agent

Sleepless Agent is an autonomous software development tool for Python that can continuously run in the background, executing tasks. It has hardware-adaptive local inference, stable continuous operation, and a robust fail-safe system that allows it to learn from failed approaches. It leverages Docker and Git for continuous integration and rollback capabilities.

Features

1. Hardware-Adaptive Resource Safeguard: Includes a pre-flight memory check and real-time monitoring to prevent system-wide crashes. It strictly enforces RAM/VRAM limits by shutting down the process if resource usage exceeds the configured thresholds, protecting your system's stability.
2. Stable Continuous Autonomous Operation: Runs continuously in the background 24/7.
3. Rollback & Anti-Pattern Learning: A robust fail-safe system that uses Docker and Git to revert to previous states and learn from failed approaches.
4. Auto-Resume Capability: Tasks are hashed and saved to a local SQLite database. You can safely interrupt the agent at any time, and it will automatically resume exactly where it left off on the next run.
5. Completely Offline Code Execution: To ensure maximum security, the Docker sandbox where the AI-generated code is executed is strictly isolated from the network. Third-party libraries are safely installed during a separate build phase using requirements.txt. The generated code cannot transmit data externally or download unwanted packages. (Note: The main agent script naturally retains network access, allowing you to seamlessly use Cloud LLM APIs if you prefer them over local models.)

Architecture

The workflow consists of six main components:

• Planner: Analyzes the task and determines the approach.
• Test Coder: Writes strict, failing tests (Red phase) based on micro-feature requirements.
• Test Reviewer: Verifies that the generated tests actually fail as expected, preventing dummy tests.
• Impl Coder: Writes the actual implementation logic to make the tests pass (Green phase).
• Impl Reviewer: Validates the implementation against the tests in the isolated Docker sandbox and checks AST constraints.
• Rollback: Reverts to previous states via Git if a step fails multiple times, extracting anti-patterns to avoid repeating mistakes.

Prerequisites

Before running Sleepless Agent, ensure your system meets the following requirements:

• Docker: Must be installed and the Docker daemon must be running. The agent uses Docker to safely execute and test generated code in an isolated sandbox.
• Git: Required for transaction management and rollback features.

Usage

1. Model Setup

Depending on your preferred backend, set up your LLM:

• llama.cpp (Local): Download your .gguf model files and place them in a directory (e.g., ./models/). If the model is split into multiple files, specify the first chunk (e.g., model-00001-of-00005.gguf) in your configuration.
• Ollama / Cloud APIs: Ensure the Ollama server is running (default port 11434), or have your API keys ready for cloud providers.

2. Configure config.toml

Create or modify config.toml in the root directory. Here's an example configuration for 'llama.cpp' backend:

[llm]
backend = "llama.cpp" # or "ollama", "openai", etc.
base_url = "http://localhost:11434/v1"
model = "openai/qwen2.5-coder"
api_key = "sk-dummy"

[llama_cpp]
model_path = "./models/qwen2.5-72b-instruct-q6_k-00001-of-00016.gguf" # Specify the path to your model file (or the first chunk if split).
server_port = 8080
context_size = 16384

[resource]
max_ram_gb = 16.0 # Specify the maximum RAM usage in GB. The smaller of this value and the available space on the system will apply.
max_vram_gb = 8.0 # Specify the maximum VRAM usage in GB. The smaller of this value and the available space on the system will apply.

[system]
max_retries = 3 # Number of retries before triggering a rollback.
allowed_extensions = [".py", ".md", ".txt", ".toml", ".json"]
recursion_limit = 1000 # Maximum recursion depth for task execution.

3. Install Dependencies

pip install -r requirements.txt

4. Write Your Task

Create a file named task.txt in the root directory and write your specific task description. Note: The agent generates a unique thread ID based on the contents of task.txt. If you want to start a completely new task, simply change the text inside task.txt.

5. Run Sleepless Agent

python main.py

Even if you stop the agent, its state is safely saved, so if you run python main.py again without modifying task.txt, the task will automatically resume.

Acknowledgements and Third-Party Libraries

This project is made possible thanks to the following incredible open-source libraries:

• langgraph - MIT License
• langchain-core - MIT License
• litellm - MIT License
• docker - Apache License 2.0
• GitPython - BSD 3-Clause License
• pydantic - MIT License
• psutil - BSD 3-Clause License
• llama-cpp-python - MIT License

License

This project is licensed under the MIT License - see the [LICENSE] file for details.

Limitations & Security Warnings

Please be aware of the following limitations and security considerations before running the agent:

• Single-Tenancy / Concurrency Limit: The agent operates within a single, shared workspace (/workspace). Running multiple instances of the agent concurrently is not supported and will lead to Git conflicts and corrupted states.
• Docker Bind Mount Risks: The agent mounts the host's workspace directory into the Docker container with read-write (rw) permissions. Because the container runs with root privileges by default, highly destructive code hallucinated by the LLM (e.g., deleting .git or the entire workspace) can affect the host directory.
• File Permissions (Linux Hosts): Files created by the Docker container may be owned by root on Linux host machines, which might require sudo to modify or delete manually.