Background Daemon

Classic senior-engineer-style reviews running asynchronously in the background.

WHAT THE DAEMON DOES

The daemon runs classic (senior-engineer-style) reviews alongside your coding agent. Instead of blocking the agent (like the stop hook), it reviews asynchronously in the background — independent of the rules review system.

Results are surfaced as soft guidance — the agent sees findings but isn't blocked. This is useful for long-running agent sessions where blocking on every change would be too disruptive.

ARCHITECTURE

The daemon runs as an HTTP server on localhost backed by a SQLite database and a worker pool. The stop hook posts diffs to the daemon instead of running reviews inline.

Workers pick up jobs and spawn AI agents for review. Results are stored in SQLite and retrievable by the hook client.

1sag daemon start    # Start the daemon
2sag daemon stop     # Stop the daemon
3sag daemon status   # Check if the daemon is running

HOW IT WORKS

3.1When the stop hook fires, it posts the current diff to the daemon's HTTP API.

3.2The daemon deduplicates by diff hash — if an identical diff was already reviewed, it returns cached results.

3.3New jobs are queued in SQLite with atomic job claiming (prevents duplicate processing).

3.4A worker claims the job and spawns an AI agent (Claude, Codex, or Gemini CLI) with read-only tools.

3.5The agent reviews the diff against matched rules and returns findings.

3.6Results are stored and the hook client polls for completion.

AGENT INVOCATION

The daemon spawns the detected agent CLI (Claude Code, Codex, or Gemini) as a subprocess. The agent is given read-only access — it can read files but cannot modify them.

The review prompt includes the diff, matched rules, and codebase context. Results are parsed and stored as structured findings.

RULES REVIEW VS DAEMON

The rules review and daemon are independent systems that can run together.

	Rules review	Background daemon
What it checks	Your rules in `.saguaro/rules/`	General code quality — bugs, security, regressions
Hook behavior	Synchronous — blocks agent on violations	Async — findings arrive next turn as guidance
When to use	You have specific team conventions to enforce	You want a background second pair of eyes

CONFIGURATION

The daemon is configured through .saguaro/config.yaml.

.saguaro/config.yaml

1# Background reviews (classic)
2daemon:
3  enabled: true