Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0022: Local-first, daemonless deployment

Note

Architecture decision: accepted.

Context and problem statement

Shiin intercepts agent actions on the developer’s machine. The v0.1 adapter runs as a Claude Code hook: a new process for each invocation, with no long-lived daemon. This must remain the zero-dependency path: no service, no network, no daemon, no telemetry. The daemon (v0.3) is an addition for approvals, not a requirement.

Decision drivers

  • The hook path must start fast, because it runs on every action.
  • No service should be required for basic authorization.
  • No data should leave the machine.

Considered options

  1. Daemonless hooks for v0.1, with an optional daemon added later for approvals.
  2. A daemon from v0.1 that all hooks connect to.
  3. A cloud service that all agents connect to.

Decision outcome

Chosen option: “Daemonless hooks for v0.1, optional daemon later”, because the daemonless path has lower latency and zero setup cost.

  • v0.1 runs a new shiin hook process for each host invocation.
  • The engine is pure and synchronous (ADR-0010), so a hook process can evaluate and exit.
  • The daemon (shiind) is introduced in v0.3 for approvals and the local API, but is optional.
  • The daemonless path remains supported after the daemon ships.

Consequences

  • Good, because the barrier to entry is zero: no daemon to start or configure.
  • Good, because each hook invocation is independent and fast.
  • Bad, because approvals in v0.1 use the host’s native prompt; the real approval protocol comes in v0.3.

Confirmation

  • The roadmap lists shiind and the approval protocol in v0.3.
  • The use cases for unattended CI (UC-07) require deterministic behavior without a daemon.

Pros and cons of the options

Daemonless first, daemon later

  • Good, because it has the lowest barrier to entry.
  • Bad, because approvals need the daemon or host prompts.

Daemon from v0.1

  • Good, because approvals are centralized.
  • Bad, because it adds latency and setup cost to the basic path.

Cloud service

  • Good, because it is always available.
  • Bad, because it contradicts the local-first principle (ADR-0007) and adds network dependency.

More information

The local API over the daemon is specified in ADR-0023. The deployment models page describes local-first and team-server options.