DOCSEARCHbyAlgolia
Submit Docs

Ghost Background Process Manager

repository·main·Indexed 40 days ago

https://github.com/skanehira/ghost

A daemon-free background process manager for Unix systems (Linux, macOS, BSD) that uses a one-shot execution model with SQLite for state persistence. Ghost provides a CLI and TUI for running commands, monitoring logs, and managing task lifecycles. It also supports functioning as a Model Context Protocol (MCP) server for AI assistants.

Tokens
8K
Snippets
41
Records
54
Agent score
50%

What's inside Ghost

  1. Ghost System Requirements

    main

    To use Ghost, your environment must meet the following requirements:

    • Operating System: Unix-based system (Linux, macOS, or BSD).
    • Rust: Version 1.80+ (2024 edition) is required for building from source.
    • lsof (Optional): If lsof is available on your system, Ghost will use it for listening-port detection.

  2. How Ghost's daemon-free architecture works

    main
    Ghost uses a daemon-free, one-shot execution model. Unlike traditional process managers that require a persistent background daemon, Ghost executes each command as a standalone process. State is maintained persistently using a SQLite database (tasks.db) and file-based logging. This allows you to manage background tasks without needing a central service running constantly.

  3. Use the Ghost TUI (Terminal User Interface)

    main

    Run ghost without any subcommands to enter the interactive TUI. The TUI provides real-time task refreshing, integrated log viewing, and interactive management.

    Task List Keybindings:

    • j / k: Move selection
    • g / G: Jump to top/bottom
    • Enter: View task details (ports, environment)
    • l: Open logs for selected task
    • r: Rerun selected command
    • s: Send SIGTERM
    • Ctrl+K: Send SIGKILL
    • Tab: Switch filters (All / Running / Exited / Killed)
    • q: Quit

    Process Details View:

    • j / k: Scroll
    • Ctrl+D / Ctrl+U: Page down/up
    • Esc: Return to task list
    • q: Quit

    Log Viewer:

    • j / k: Scroll vertically
    • h / l: Scroll horizontally
    • g / G: Jump to top/bottom
    • Esc: Return to task list
    ghost

  4. Stop running tasks

    main

    Terminate background processes using ghost stop. By default, Ghost sends a SIGTERM for a graceful shutdown. To force an immediate termination, use the --force flag to send SIGKILL.

    # Gracefully stop (SIGTERM)
ghost stop e56ed5f8-44c8-4905-97aa-651164afd37e

# Force kill (SIGKILL)
ghost stop c3d4e5f6-g7h8-9012-cdef-345678901234 --force

  5. Inspect task logs and status

    main

    Monitor the output and lifecycle of background tasks using ghost log and ghost status.

    • ghost log <id>: Prints the log for a specific task ID.
    • ghost log -f <id>: Follows the log output in real time (use Ctrl+C to stop).
    • ghost status <id>: Reports the lifecycle state, timestamps, exit code (if finished), and log location.
    # Print a task's log
ghost log 9fe034eb-2ce7-4809-af10-2c99af15583d

# Follow output in real time
ghost log -f e56ed5f8-44c8-4905-97aa-651164afd37e

# Show details for a running task
ghost status e56ed5f8-44c8-4905-97aa-651164afd37e

  6. Install Ghost

    main

    You can install Ghost by either building it from source using Cargo or by downloading prebuilt binaries from the GitHub Releases page.

    Build from source

    Ensure you have Rust 1.80+ installed, then execute:

    git clone https://github.com/skanehira/ghost.git
cd ghost
cargo build --release

    The compiled binary will be located at target/release/ghost.

    git clone https://github.com/skanehira/ghost.git
cd ghost
cargo build --release

  7. Run commands in the background with `ghost run`

    main

    Use the ghost run command to execute processes in the background. Ghost will provide a task ID, PID, and the path to the log file upon successful execution.

    Common usage patterns include:

    • Running simple or long-lived commands.
    • Executing shell scripts.
    • Setting a specific working directory with --cwd.
    • Injecting environment variables with multiple --env flags.
    # Run a simple command
ghost run echo "Hello, World"

# Run a long-lived command
ghost run sleep 30

# Run a script
ghost run ./my_script.sh

# Run from a specific working directory
ghost run --cwd /path/to/project make build

# Inject environment variables
ghost run --env NODE_ENV=production --env PORT=3000 npm start

  8. Quick Start with Ghost

    main

    Ghost allows you to manage background processes via a CLI. Use the following commands to get started:

    • Run a command in the background: ghost run <command>
    • List managed tasks: ghost list
    • Inspect process output (live tailing): ghost log -f <task_id>
    • Open the Terminal UI (TUI) dashboard: ghost
    • Run as an MCP server: ghost mcp
    # Run a command in the background
ghost run echo "Hello, Ghost"

# List managed tasks
ghost list

# Inspect process output
ghost log -f <task_id>

# Run as a MCP server
ghost mcp

# Open the TUI dashboard
ghost

  9. List and filter managed tasks

    main

    View the history and current state of all processes managed by Ghost using the ghost list command. You can filter the output by the lifecycle status of the tasks.

    # Show every task
ghost list

# Filter by status
ghost list --status running

  11. Debug MCP server connection issues

    main

    When running Ghost in MCP server mode (ghost mcp), diagnostic logs are written to a specific file because the server uses stdio for communication, making standard console output unavailable.

    MCP Log Path:

    • Linux: ~/.local/share/ghost/logs/ghost.log
    • macOS: ~/Library/Application Support/ghost/logs/ghost.log

    Log Details:

    • Rotation: Size-based rotation at 5MB, keeping up to 5 historical files.
    • Events Logged: Server startup, initialization, transport/connection errors, and shutdown.

  12. Clean up finished tasks

    main

    Use ghost cleanup to remove task records from the database. This helps manage storage and history.

    Options:

    • --days N: Delete tasks older than N days (default is 30).
    • --all: Delete every finished task regardless of age.
    • --status <STATUS>: Restrict cleanup to specific statuses: exited, killed, unknown, or all.
    • --dry-run / -n: Preview which tasks would be deleted without actually performing the deletion.
    # Delete tasks older than 30 days
ghost cleanup

# Delete tasks older than 7 days
ghost cleanup --days 7

# Delete all finished tasks
ghost cleanup --all

# Preview deletions
ghost cleanup --dry-run