@gtc6244/immediacy-daemon
v0.2.69
Published
Mac daemon — Conductor core: worktrees + headless Claude Code sessions behind a multiplexed WSS protocol.
Readme
@gtc6244/immediacy-daemon
The Conductor core for Immediacy — a daemon that runs wherever your code lives (your Mac, a VPS, or a spare box at home), owns git worktrees, and drives headless coding agents — Claude, Codex, OpenRouter (just about any model), and local Ollama models — behind a single multiplexed WebSocket protocol.
- 🌐 Landing page: https://GetImmediacy.com
- 📦 npm: https://www.npmjs.com/package/@gtc6244/immediacy-daemon
- 🛠 Source / issues: https://github.com/GTC6244/Immediacy (this package lives in
/daemon)
🖥 Looking for the macOS app? The native Immediacy app for macOS is available from https://GetImmediacy.com. It's in pre-beta right now, so expect rough edges and frequent updates. Bug reports and feedback are welcome on GitHub issues.
Overview
Immediacy lets you run parallel AI agents on the machine that holds your code and drive them from anywhere — an Android/iOS phone or tablet, a native macOS app, or a browser. Pick any model per workspace: Claude, Codex, OpenRouter (just about any hosted model), or a local Ollama model running on your own hardware — and run it in a coding workspace (git worktree + diff + terminal) or a plain chat (repo-less, free-form). So you can use any model at any time, including your own local models driven remotely from your phone. This package is the daemon that makes that possible.
It runs as a lightweight background service, installed with one CLI command on macOS, Linux, or a VPS (see Install below). Each task gets one git worktree + one headless agent session, isolated from the others, and every client speaks to the daemon over one WebSocket wire protocol. The work is device-fluid: because the daemon is the source of truth, you can start on one device and pick up on another, and a client can connect to several daemons at once to fan work across every machine you own. Remote access needs no inbound internet port — the daemon binds loopback locally and remote clients reach it through a Cloudflare edge that it dials out to.
Flutter / iOS app ⇄ (WSS) ⇄ Cloudflare edge ⇄ (cloudflared outbound) ⇄ daemon (Mac/VPS) → N × (git worktree + agent)
macOS app ⇄ (WS, loopback) ─────────────────────────────────────────────────┘The phone and the daemon never connect directly. The phone hits a public
Cloudflare URL; the daemon only holds an outbound tunnel open. On the same
machine, the macOS app and the bundled browser client talk to the daemon over
loopback (ws://127.0.0.1:11322) — no tunnel needed.
Features
- One worktree + one agent per task. The daemon forks a fresh
git worktreefor every workspace and runs an isolated agent session against it. Deleting a workspace removes the worktree — never the branch or the underlying repo. - Four model providers behind one interface:
- Claude (
claude-opus-4-8,claude-fable-5,claude-sonnet-5, …) via the Anthropic Agent SDK. - Codex (
gpt-5-codex,gpt-5, orCodex (account default)) via the OpenAIcodexCLI in headless, sandboxedexec --jsonmode. - OpenRouter — just about any model (Gemini, DeepSeek, Grok, Qwen, and any
slug from https://openrouter.ai/models). It rides the same Agent SDK
backend as Claude via OpenRouter's Anthropic-compatible endpoint, so all the
same guarantees hold — only billing changes. Needs
OPENROUTER_API_KEY. - Ollama — your own models, running locally. Serves whatever you've
ollama pulled from a local (or remote) Ollama — no API key, no billing, code never leaves the machine. Installed models are auto-discovered into the picker; setOLLAMA_BASE_URLfor a remote box. - A mock backend (
AGENT_MODE=mock) does real worktree writes and diffs with no API credits — ideal for testing.
- Claude (
- Coding workspaces and plain chats. A workspace is either a git worktree (coding: diff + terminal + PR) or a repo-less free-form chat (like the Claude/ChatGPT desktop apps). Every provider runs in both — use any model at any time, for shipping code or just conversation.
- Permission gating by default. Every tool call is deferred to the client
(
event.permission_request→permission.respond) and default-denies on timeout. The daemon never runs--dangerously-skip-permissions; Codex runs sandboxed (-s workspace-write,approval_policy=never) so edits stay inside the worktree. - Live streaming. Assistant messages, session events, tool-use events, git
diffs (
diff.get), and a real PTY terminal (node-pty) all stream over the socket. - End-to-end crypto + multi-device pairing. An optional NaCl box layer (
E2E=1) seals each socket to that device's own key, so a phone, tablet, and desktop pair independently. Pairing is trust-on-first-use behind Cloudflare Access, via a QR code — no shared secret beyond the Access token. - GitHub integration without leaking tokens. Workspace creation can pick from
your GitHub repos using the
ghCLI already authenticated on the daemon's machine — the token never touches the phone, the wire, or this source. - Bundled browser client. The daemon's HTTP server serves a dependency-free
web UI on the same port
cloudflareddials, so the Access login cookie authorizes the same-origin WebSocket. - One CLI, every target. Run in the foreground or install as a supervised
service — launchd on macOS, systemd (
--user) on Linux. Native deps ship prebuilds for macOS + Linux (glibc, arm64/x64), so no compiler toolchain is needed.
Install
npm i -g @gtc6244/immediacy-daemon # public package — no auth neededRequires Node.js ≥ 20, plus git and (for GitHub integration) the gh CLI on
PATH. On musl/Alpine there are no native prebuilds — use Docker (see below).
Run it
immediacy-daemon doctor # verify node / git / gh are present
immediacy-daemon install # write + start the background service
immediacy-daemon status # service state + /healthz probeOr run it in the foreground (Docker, ad-hoc):
immediacy-daemon startCLI commands
| Command | What it does |
|---|---|
| start | Run the daemon in the foreground (Ctrl-C to stop). |
| install [--print] | Install + start the supervised service (launchd/systemd). --print renders the unit without installing. |
| uninstall | Stop and remove the service. |
| restart | Restart the running service. |
| status | Show service state and probe http://127.0.0.1:<port>/healthz. |
| logs [-f] | Print (or -f to tail) the daemon's stdout/stderr logs. |
| doctor | Check node/git/gh on PATH and whether the daemon responds. |
| pair [--watch\|--json\|--no-qr] | Print a single-use pairing QR + JSON code from the running daemon, to scan or paste into the Mac/phone app. Run it on the daemon's box (e.g. over SSH). Codes expire in 60 s; --watch re-mints every 55 s. See DEPLOY.md. |
| update [--check] | Update to the latest npm release and restart the service (--check only reports if a newer version exists). |
| publish … | Phone installs (paid add-on): set-token (publish license, prompted), status, test, enable/disable, set-ios (App Store Connect key for registering iPhones), set-url, set-ttl, register-iphone, clear license\|ios\|url. Debug/development builds only. Talks to the running daemon over local-only routes. |
| devices list / devices admin <label\|key-prefix> [--revoke] | List paired devices; let one manage phone-install settings (the Mac app pairs as admin automatically). |
| help / version | Show help or version. |
The same self-update is reachable over the wire so a connected client can trigger
it: daemon.update.check reports the current/latest version and whether an update
is available, and daemon.update installs it (optionally a pinned version) via
npm install -g and restarts the supervised service to load the new code. Both
answer with daemon.update.result. Every client exposes this per daemon under
Settings → Daemon updates: Mac, phone/tablet/desktop, and web.
daemon.update has two guards. daemon.update.check applies the same ones and
reports canUpdate: false with an unsupportedReason, so clients show why rather
than an Update button that would be refused:
- Only the installed service from the global npm copy. The update has to land
on the running process. A daemon refuses unless it runs from the global npm
install and is the launchd/systemd service (
immediacy-daemon install). On macOS that meansXPC_SERVICE_NAMEmatches the service label; on Linux it means the process's cgroup is theimmediacy-daemon.serviceunit. This rules out:- Daemons the Mac app runs. The app sets
IMMEDIACY_SUPERVISOR=macos-appon each one, because they run from the app's shared install (~/.immediacy/daemon) or a checkout. Update them from the app's daemon settings. - Dev runs from a checkout and daemons started in the foreground. Run
immediacy-daemon updateon the host instead.
- Daemons the Mac app runs. The app sets
- Admin-only. Only an admin device can trigger it. The Mac app pairs as admin;
use
devices adminfor anything else. Phones and plain web sockets see the available version with that reason.
Options (also read from the environment):
| Flag | Env | Default | Meaning |
|---|---|---|---|
| --port <n> | DAEMON_PORT | 11322 | Local port to bind (the port cloudflared dials). |
| --host <addr> | DAEMON_HOST | 127.0.0.1 | Bind address (0.0.0.0 to expose on a LAN/emulator). |
| --agent-mode <m> | AGENT_MODE | claude | claude | mock. |
| --e2e | E2E=1 | off | Enable the NaCl box E2E layer (needs a paired peer). |
If another app already holds the port, install refuses (pass --force to
override), status/doctor say which process holds it, and a running daemon
logs the holder and exits with status 78 — systemd then stops restarting it
instead of looping. Pick another port with --port / DAEMON_PORT.
Cloudflare connection
Remote clients never talk to the daemon's machine directly. cloudflared dials
out from that machine (Mac or VPS) to the Cloudflare edge and holds the
connection open, so there's no inbound port, no port forwarding, and no VPN.
The daemon just binds a local WebSocket on 127.0.0.1:11322; Cloudflare Access does
authentication/authorization at the edge.
app ⇄ (WSS, public URL) ⇄ Cloudflare edge ⇄ (cloudflared outbound) ⇄ daemon (ws://127.0.0.1:11322)End state: the daemon is reachable at wss://your-subdomain.your-domain, gated by
Cloudflare Access, with a service token the app presents. The optional NaCl box
codec (E2E=1) keeps the message payload private even from the edge.
Quick setup:
brew install cloudflared
cloudflared tunnel login # pick your Cloudflare domain
cloudflared tunnel create immediacy # prints a tunnel UUID + creds path
cloudflared tunnel route dns immediacy conductor.example.com~/.cloudflared/config.yml:
tunnel: immediacy
credentials-file: /Users/YOU/.cloudflared/<UUID>.json
ingress:
- hostname: conductor.example.com
service: ws://127.0.0.1:11322 # WebSockets are on by default
- service: http_status:404 # required catch-allFull walkthrough — tunnel + Access + service tokens:
docs/cloudflare-setup.md.
Configuration & secrets
The daemon reads config from flags/environment and from ~/.immediacy/:
| What | Where | Notes |
|---|---|---|
| Port / host / agent mode | --port / --host / --agent-mode, or DAEMON_PORT / DAEMON_HOST / AGENT_MODE | Baked into the service unit at install time. |
| E2E crypto | --e2e / E2E=1 | NaCl box layer; needs a paired peer. |
| Provider API keys | ~/.immediacy/credentials.json (0600), or ANTHROPIC_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY | Stored key wins over env. Anthropic/OpenAI fall back to a cached CLI/SSO login if unset. |
| Ollama endpoint | OLLAMA_BASE_URL (default http://localhost:11434), optional OLLAMA_API_KEY | Local Ollama is keyless; the base URL points at a remote box if you don't run it on the daemon's machine. Installed models are auto-discovered. |
| NaCl keypair / paired peers | ~/.immediacy/keys.json, peers.json | Auto-created on first run. |
| Phone installs (Build & Install) | ~/.immediacy/publish.json (0600; publish license token, settings), ~/.immediacy/publish/asc.p8 (0600; App Store Connect key, used only to register iPhones), ~/.immediacy/artifacts.json (detected builds) | Set with immediacy-daemon publish … or the Mac app. Builds go through Immediacy's publish service; the daemon holds no storage credentials and agents get no signing keys. PUBLISH_BROKER_URL overrides the service URL (testing). |
The npm package is public, so its source is world-readable. Runtime secrets are never in the package — they live in
~/.immediacy/on each host. Never commit or bundle API keys, and don't bake them into a Docker image.
Docker (Linux fleet / Alpine)
For reproducible VPS fleets or musl/Alpine (no native prebuilds), a container is cleaner than global npm — run the daemon in the foreground:
FROM node:20-bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates \
&& rm -rf /var/lib/apt/lists/*
RUN npm i -g @gtc6244/immediacy-daemon
EXPOSE 11322
# Mount ~/.immediacy for persistent keys/credentials; pass keys via env or the mount.
CMD ["immediacy-daemon", "start", "--host", "0.0.0.0"]Keep Macs on native launchd (real PTYs, local filesystem access) rather than Docker.
Day-2 operations
immediacy-daemon status # is it up? is /healthz responding?
immediacy-daemon logs -f # tail stdout/err
immediacy-daemon restart # restart the service
immediacy-daemon uninstall # stop + remove the service
npm i -g @gtc6244/immediacy-daemon@latest # update to the latest published version
immediacy-daemon restartLogs: ~/Library/Logs/immediacy-daemon.{out,err}.log (macOS) or
~/.immediacy/daemon.{out,err}.log (Linux).
Full deploy & publish guide:
daemon/DEPLOY.md.
Links
- Landing page: https://GetImmediacy.com
- macOS app (pre-beta): download from https://GetImmediacy.com
- GitHub repo: https://github.com/GTC6244/Immediacy
- npm package: https://www.npmjs.com/package/@gtc6244/immediacy-daemon
- Architecture reference:
docs/ARCHITECTURE.md - Cloudflare setup:
docs/cloudflare-setup.md
