Purpose
alive is a minimalist "wake loop" used to turn any LLM into an autonomous AI agent. Its core idea is: the AI wakes up every few minutes, remembers who it is, sees what has changed, takes action, and then goes back to sleep—cycling like breathing, running forever. The project emphasizes "one file," requires no framework, and has no dependencies beyond the Python standard library and your LLM SDK.
Main capabilities
In each loop, alive will: read the soul file (the AI's identity and instructions); read persistent memory (files the AI wrote in previous loops); collect new messages (pluggable sources such as email and Telegram); manage the context window (prioritizing loading the latest memory and issuing a warning when it fills up); send everything to the LLM; let the LLM decide what to do; after the AI executes, it goes back to sleep.
The project includes multiple empirical safeguards from real operation:
- Context budget loading: memory files are loaded newest-first; when total memory exceeds the context budget (60% of the window), older files are skipped and the AI is warned, preventing "memory bloat from eating up the context window."
- Communication adapter circuit breaker: after an adapter fails 3 times in a row, it is automatically skipped until the process restarts, avoiding a bad integration wasting every loop.
- Exponential backoff retries: a single failed LLM call will not crash the entire loop.
- Session logs: every session is recorded, making it easy to understand what the AI did.
- Emergency stop: supports a kill phrase and kill flag.
The built-in web dashboard has zero dependencies and zero setup, and can be accessed via http://localhost:7600 Access and display: real-time status (running, sleeping, hibernating, killed), memory files (name, size, token count), the last 10 sessions (duration, tokens, pass/fail), configuration (provider, model, adapter, soul file status), and metrics (total sessions, success rate, average duration, total runtime). The dashboard auto-refreshes every 10 seconds, and there is also a /api/status JSON API for programmatic monitoring.
Usage
Soul file: soul.md is the most important file; it defines what the AI should do (or should not do) and how it should behave. The project provides templates in examples/, such as soul-developer.md (an autonomous developer that monitors a repository and fixes bugs), soul-researcher.md (a research agent that explores topics and writes reports), and soul-aurora.md (the author's real soul file). The AI can modify its own soul file; this is intentional by design.
Memory: the memory/ directory is the AI's persistent brain. Between two awakenings, the AI has no memory unless it writes content here. Recommended practices include: maintaining a session log (memory/session-log.md), tracking active goals (memory/goals.md), recording lessons learned (memory/lessons.md), and compressing old entries to save context window space. The AI learns how to use memory through experience.
Communication: place executable scripts in comms/ that output a JSON array. The project includes Telegram and Email example adapters, and you can also write your own adapters for Slack, Discord, webhook, RSS, etc.
Command-line options:
--demo: run a simulated wake loop and demonstrate all features (no API key required)--check: validate the configuration without calling the LLM (verify settings before consuming tokens)--once: run a single wake loop and then exit (convenient for testing)--dashboard: also start the Web dashboard alongside the wake loop--dashboard-only: run only the dashboard, not the wake loop--dashboard-port N: set the dashboard port (default 7600)
Control files and signals:
.wake-interval: write a number (seconds) to change the AI's wake frequency.wake-now: touch this file to wake the AI immediately (consumed on wake).sleep-until: write an ISO 8601 timestamp to sleep until that time.killed: touch this file to stop the loop, and delete it to resume- ALIVE_KILL_PHRASE: set in .env; when any message contains that phrase, the AI stops immediately
Provider: set ALIVE_LLM_PROVIDER in .env. Using Claude Code as the provider gives the AI native file access, bash execution, web search, and other Claude Code tools with no additional setup. Using Ollama allows a fully autonomous AI to run on your own hardware at zero API cost: install Ollama, pull a model (ollama pull llama3.1), and set ALIVE_LLM_PROVIDER=ollama in .env. All settings are done through .env or environment variables.
Monitoring and Logging: metrics.jsonl records session metrics (duration, token usage, success/failure); logs/sessions/ saves the complete output of each session.
Use Cases
Suitable for developers who want to build a continuously autonomous AI agent with minimal dependencies and code, for example letting AI autonomously monitor repositories and fix bugs, continuously research a topic and produce reports, or serve as the infrastructure for a personal autonomous AI. The project emphasizes that "complexity is the enemy of autonomy," arguing that an agent buried under framework code is not autonomous but constrained; a simple wake-up loop plus a soul file and memory folder is freedom.
Limitations
The material explicitly states: no dependencies other than the Python standard library and your LLM SDK; regarding charges, pricing, platform compatibility scope, etc., no further explanation is given in the material and none is currently provided. The project includes 29 tests, covering core functions such as token estimation, wake-up intervals, kill phrase detection, sleep-until, memory reading, context construction, session continuity, SIGTERM handling, and metrics logging. The author recommends using systemd for deployment in production environments.
