daemon

claude-daemon

A Claude Code plugin that turns a persistent session into a 24/7 daemon. It iterates on tasks (ralph-loop style), processes a task queue, and idles when there's nothing to do.

Run Claude in tmux, SSH in to give commands, or remotely append tasks to a queue file.

How It Works

/daemon-start "task" --project PATH
    |
    v
[Claude works on task iteratively]
    |
    v  (outputs <promise>TASK_COMPLETE</promise>)
    |
    v
[Check queue.jsonl]
    |
    +---> Next task found → start it
    |
    +---> Queue empty → idle at prompt (no tokens burned)

The core mechanism is a stop hook: when Claude finishes a turn and tries to exit, the hook intercepts and either re-feeds the prompt (iterate), picks up the next queued task, or allows exit (idle).

Installation

Option 1: Clone to local marketplace

# Clone into Claude Code's local plugin marketplace
mkdir -p ~/.claude/plugins/marketplaces/local/plugins
git clone https://github.com/yihan2099/claude-daemon.git \
  ~/.claude/plugins/marketplaces/local/plugins/daemon

# Enable the plugin in settings
# Add to ~/.claude/settings.json under "enabledPlugins":
#   "daemon@local": true

Option 2: Clone anywhere and symlink

git clone https://github.com/yihan2099/claude-daemon.git ~/dev/claude-daemon

ln -s ~/dev/claude-daemon \
  ~/.claude/plugins/marketplaces/local/plugins/daemon

# Enable in settings as above

Then restart Claude Code to pick up the plugin.

Usage

Start a task

/daemon-start "improve test coverage to 80%" --project ~/dev/myapp --max-iterations 30

Claude works iteratively. When done, it outputs <promise>TASK_COMPLETE</promise>, the daemon logs the completed task and picks up the next one from the queue.

Queue tasks

From within Claude:

/daemon-queue "fix all eslint errors" --project ~/dev/myapp

Or remotely via SSH (append JSON to the queue file):

echo '{"task":"add rate limiting","project":"/Users/you/dev/myapp"}' \
  >> ~/.claude/daemon/queue.jsonl

Check status

/daemon-status

Shows: active task, iteration count, queue contents, completed task history.

Stop the daemon

/daemon-stop

Removes state and returns to the interactive prompt.

Typical Setup (tmux)

# Start a persistent session
tmux new -s claude-daemon
cd ~/dev
claude

# Give it work
/daemon-start "refactor auth module" --project ~/dev/myapp

# Detach: Ctrl-B, D
# Claude keeps working

# Later, SSH in and add more tasks
ssh mybox
echo '{"task":"fix CI","project":"/Users/me/dev/myapp"}' >> ~/.claude/daemon/queue.jsonl

# Or attach and interact directly
tmux attach -t claude-daemon

Commands

Command	Description
/daemon-start "task" --project PATH	Start working on a task
/daemon-stop	Stop the active daemon
/daemon-status	Show status, queue, and history
/daemon-queue "task" --project PATH	Add a task to the queue

Options

• --project PATH (required) — project directory to cd into
• --max-iterations N (default: 30) — max iterations per task

State Files

Runtime state lives at ~/.claude/daemon/:

~/.claude/daemon/
  state.json      # Current active task
  queue.jsonl     # Pending tasks (one JSON object per line)
  history.jsonl   # Completed tasks log

queue.jsonl is append-only, making it safe to write to remotely.

Plugin Structure

.claude-plugin/
  plugin.json           # Plugin metadata
commands/
  daemon-start.md       # /daemon-start command
  daemon-stop.md        # /daemon-stop command
  daemon-status.md      # /daemon-status command
  daemon-queue.md       # /daemon-queue command
hooks/
  hooks.json            # Stop hook registration
  daemon-stop-hook.sh   # The loop/queue engine
scripts/
  setup-daemon.sh       # Initialize daemon state
  add-to-queue.sh       # Append task to queue
  show-status.sh        # Display status

License

MIT