Daemon mode

Long-running operation under launchd (macOS) or systemd user services (Linux). The daemon runs act-loop in the background, survives reboots, and writes logs to ~/.commitly/agent.log.

## why a daemon

act-loop is a continuous polling loop. Running it from a terminal works, but the loop dies when you close the shell. The daemon family wraps it in your OS-native service supervisor so it starts at login, restarts on crash, and stays out of your way.

## lifecycle

Four commands manage the whole lifecycle. They are thin wrappers over launchctl (macOS) and systemctl --user (Linux).

commandpurpose

start <path>

Generate the unit file, register it, start the loop.

stop

Unregister and stop. Logs are kept.

status

Print whether the loop is alive, with PID and unit state.

logs

Tail the last N lines of agent.log.

## starting the daemon

start is interactive — it asks which repo to target if you don't pass --repo. Pass --behavior to skip the per-task behavior prompt that the daemon itself can't answer (no TTY).

commitly-agent start ~/code/api \
  --repo myorg/api \
  --behavior docs

## behaviors

Three values for --behavior. They map to the constraint string the agent sends to the AI before each task.

behaviorwhat the AI is allowed to change

docs

JSDoc strings, parameter types, in-line comments. No logic changes. Safest. This is the default.

refactor

Structural cleanliness — flattening if/elses, extracting magic strings to constants, switch-with-early-returns. Behavior must not change.

ghost

Micro-optimizations — loops to functional maps, stricter scoping, object destructuring. Moderate risk.

## where things live

pathpurpose

~/Library/LaunchAgents/com.commitly.agent.plist

(macOS) plist generated by start, mode 0o600.

~/.config/systemd/user/commitly-agent.service

(Linux) systemd unit, mode 0o600.

~/.commitly/agent.lock

PID lock; prevents two loops running concurrently.

~/.commitly/agent.log

Stdout + stderr. Rotated to agent.log.prev on each start.

## checking status

$ commitly-agent status
✓ act-loop is running (PID 41822)
   systemd service: active

If you see Stale lock file found, the previous process exited ungracefully — status cleans it up for you, then run start again.

## reading logs

commitly-agent logs            # last 60 lines
commitly-agent logs -n 200     # last 200 lines

Or tail directly: tail -f ~/.commitly/agent.log.

## stopping

commitly-agent stop

Removes the unit-level registration. The on-disk plist or unit file is left in place so a subsequent start can re-load it without regenerating from scratch — though in practice start always rewrites them.

## resilience

The loop is engineered to survive bad weather. Errors back off exponentially with jitter, capped at five minutes. Network calls to the dashboard time out after sixty seconds. If the process is killed mid-task, the next start recovers cleanly and resumes from the queue — the dashboard's task table is the ground truth.