Skip to main content
Version: 2.5.0

daemon

the kasmos daemon (kasmos, as a user service) is a multi-repo background orchestrator that runs alongside your development environment. it watches registered repositories for agent lifecycle signals and automatically drives fsm transitions — spawning planners, coders, reviewers, and fixer agents without manual intervention.

what the daemon does​

at its core the daemon is a poll loop with four concerns, executed in this order on every tick:

  1. signal bridging — loop.BridgeFilesystemSignals scans <repo>/.kasmos/signals/ (and any shared worktrees under <repo>/.worktrees/) and inserts any newly written filesystem sentinel files as pending rows in the shared sqlite-backed signal gateway. this is a compatibility step so that tools or agents that still write sentinel files can be picked up automatically.
  2. signal claiming — the daemon atomically claims pending signals from the shared gateway (gateway.Claim(project, workerID)) so that concurrent or restarted instances never double-process the same signal.
  3. action dispatch — each claimed signal is fed through a per-repo loop.Processor which produces typed Action values (spawn coder, spawn reviewer, advance wave, etc.), then executes those actions via the TmuxSpawner.
  4. lifecycle advance — the daemon monitors running tmux sessions for completion, automatically pushes branches, transitions the fsm, and spawns the next agent role.

for agents, the primary way to emit signals is mcp signal_create, which writes directly to the shared gateway. kas signal emit is the operator and cli fallback. the filesystem bridge (step 1) exists for backward compatibility — do not rely on manually writing sentinel files in new workflows.

the daemon exposes a unix domain socket control api so kas daemon status, add, and remove can reach it without restart.

when do you need the daemon?​

interactive tui usage — you don't need the daemon. the tui drives agent spawn/kill directly.

headless / ci / server environments — the daemon is the primary driver. you register repos via kas daemon add or the config file, and it handles everything autonomously.

wave-based plans — wave advancement, elaboration, and multi-task concurrent execution all run through the daemon's action pipeline.

pr review automation — the optional pr monitor goroutine polls open pull requests for reviewer feedback and dispatches fixer agents automatically.

edge cases​

  • no daemon — signals emitted into the db (via kas signal emit) remain pending indefinitely. nothing processes them until the daemon starts.
  • startup recovery — on startup, the daemon calls taskfsm.RecoverInFlight to move any files left in processing/ back to the signals root, preventing permanent loss after a crash.
  • unavailable store — if the shared global task store (~/.config/kasmos/taskstore.db) cannot be opened when a repo is registered, that repo is registered with a nil store and nil gateway. the daemon logs a warning and skips it on each tick rather than crashing the whole poll cycle.
  • duplicate basenames — two repos with the same directory name (e.g. /work/foo and /archive/foo) cannot be registered simultaneously. the daemon rejects the second registration with an error.
  • architecture — core types and the event loop in detail
  • setup — launchd/systemd user services and Just recipes
  • signals — filesystem and db-backed signal paths
  • multi-repo — repo registration rules
  • pr monitor — automated pr review handling