From 36e1c3debd448d39196c2289feb2e96f2ecd0f26 Mon Sep 17 00:00:00 2001 From: diogo464 Date: Mon, 23 Jun 2025 10:29:47 +0100 Subject: Improve README introduction and add root directory information MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rewrite opening section to be clearer and more direct - Better explain the tool's purpose for AI agents - Add root directory discovery details to "How It Works" section - Simplify content structure while maintaining essential information 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- README.md | 201 +++++++------------------------------------------------------- 1 file changed, 21 insertions(+), 180 deletions(-) diff --git a/README.md b/README.md index 53698ff..8bec765 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,19 @@ -# Demon - Background Process Manager +# demon - Background Process Manager -A lightweight, intuitive CLI tool for spawning, managing, and monitoring background processes on Linux systems. Perfect for development servers, long-running tasks, and automation workflows. +This tool helps AI agents control long-running processes and view their logs easily. For example, when running `npm run dev`, Claude often runs problematic commands like `npm run dev &` which makes it unable to see the logs or properly kill the process afterward. When it tries to run `npm run dev` again, the new instance binds to a different port and it ends up getting kind of lost. -## Features +Using demon with a justfile like this: +```Justfile +start: stop + demon run server -- npm run dev -- **Simple Process Management**: Start, stop, and monitor background processes with ease -- **Persistent Logging**: Automatic stdout/stderr capture to files -- **Real-time Monitoring**: Tail logs in real-time with file watching -- **Process Lifecycle**: Graceful termination with SIGTERM/SIGKILL fallback -- **Machine-readable Output**: Perfect for scripting and LLM agent integration -- **Zero Configuration**: Works out of the box, no setup required +stop: + demon stop server + +logs: + demon cat server +``` +allows Claude to check errors, manage the running server without getting stuck, and be more autonomous overall. ## Installation @@ -89,13 +93,13 @@ Follow log files in real-time (like `tail -f`). ```bash # Follow both stdout and stderr -demon tail web-server +demon tail -f web-server # Follow only stdout -demon tail web-server --stdout +demon tail -f web-server --stdout # Follow only stderr -demon tail web-server --stderr +demon tail =f web-server --stderr ``` ### `demon cat [--stdout] [--stderr]` @@ -130,178 +134,15 @@ Remove orphaned files from processes that are no longer running. demon clean ``` -### `demon llm` -Output comprehensive usage guide optimized for LLM consumption. - -```bash -demon llm -``` - -## Use Cases - -### Development Workflows -Perfect for managing development servers and build processes: - -```bash -# Start multiple development services -demon run api-server npm run dev -demon run frontend yarn start -demon run db-server docker run -p 5432:5432 postgres - -# Monitor everything -demon list -demon tail api-server --stderr # Watch for errors - -# Wait for a specific service to finish -demon wait api-server -``` - -### LLM Agent Integration -Designed for seamless automation and LLM agent workflows: - -```bash -# Agents can start long-running processes -demon run data-processor python process_large_dataset.py - -# Wait for the process to complete -demon wait data-processor --timeout 3600 # 1 hour timeout - -# Check status programmatically -if demon status data-processor | grep -q "RUNNING"; then - echo "Processing is still running" -fi - -# Get machine-readable process list -demon list --quiet | while IFS=: read id pid status; do - echo "Process $id ($pid) is $status" -done -``` - -### Background Tasks & Scripts -Ideal for CI/CD, backups, and system maintenance: - -```bash -# Database backup -demon run nightly-backup -- pg_dump mydb > backup.sql - -# Log file processing -demon run log-analyzer tail -f /var/log/app.log | grep ERROR - -# System monitoring -demon run monitor -- iostat -x 1 -``` - -### DevOps & System Administration -Manage services without complex init systems: - -```bash -# Application deployment -demon run app-server ./deploy.sh production - -# Health monitoring -demon run health-check -- while true; do curl -f http://localhost:8080/health || exit 1; sleep 30; done - -# Resource monitoring -demon run resource-monitor -- top -b -n1 | head -20 -``` - ## How It Works When you run `demon run web-server python -m http.server 8080`: -1. **Process Creation**: Spawns the process detached from your terminal -2. **File Management**: Creates three files: +1. **Root Directory Discovery**: Finds the git root directory and creates a `.demon` subdirectory for all daemon files (or uses `--root-dir` if specified, or `DEMON_ROOT_DIR` environment variable) +2. **Process Creation**: Spawns the process detached from your terminal +3. **File Management**: Creates three files in the root directory: - `web-server.pid` - Contains the process ID and command - `web-server.stdout` - Captures standard output - `web-server.stderr` - Captures error output -3. **Process Monitoring**: Tracks process lifecycle independently -4. **Log Management**: Files persist after process termination for inspection - -## LLM Agent Integration - -Demon is specifically designed to work seamlessly with LLM agents and automation tools: - -### Machine-Readable Output -```bash -# Get process status in parseable format -demon list --quiet -# Output: web-server:12345:RUNNING -# backup-job:12346:DEAD -``` - -### Scripting Examples -```bash -# Start service if not running -demon list --quiet | grep -q "web-server:" || demon run web-server python -m http.server - -# Wait for process to finish -demon wait backup-job --timeout 0 # Wait indefinitely - -# Get all running processes -demon list --quiet | grep ":RUNNING" | cut -d: -f1 -``` - -### Error Handling -```bash -# Check if process started successfully -if demon run api-server ./start-api.sh; then - echo "API server started successfully" - demon tail api-server & # Monitor in background -else - echo "Failed to start API server" - exit 1 -fi -``` - -## File Management - -### File Locations -All files are created in the current working directory: -- `.pid` - Process ID and command information -- `.stdout` - Standard output log -- `.stderr` - Standard error log - -### Cleanup -- Files persist after process termination for inspection -- Use `demon clean` to remove files from dead processes -- Consider adding `*.pid`, `*.stdout`, `*.stderr` to `.gitignore` - -### Log Rotation -- Demon doesn't handle log rotation internally -- For long-running processes, implement rotation in your application -- Or use external tools like `logrotate` - -## Advanced Usage - -### Process Management -```bash -# Graceful shutdown with custom timeout -demon stop long-running-task --timeout 60 - -# Force kill if process is stuck -demon stop stuck-process --timeout 1 -``` - -### Monitoring & Debugging -```bash -# Monitor multiple processes -for id in web-server api-server worker; do - demon tail $id --stderr & -done - -# Check resource usage -demon run monitor -- ps aux | grep my-app -demon cat monitor -``` - -### Integration with System Tools -```bash -# Use with systemd -demon run my-service systemctl --user start my-app - -# Use with Docker -demon run container -- docker run -d --name myapp nginx - -# Use with tmux/screen for complex setups -demon run dev-env -- tmux new-session -d 'npm run dev' -``` +4. **Process Monitoring**: Tracks process lifecycle independently +5. **Log Management**: Files persist after process termination for inspection -- cgit