Install

Salidium needs Node 24 or newer. There is nothing else to install first.

On first run it looks for Claude Code and Codex, prints the files it wants to change, and asks before adding hooks. It then asks whether the optional written Why and How should make model calls. Local only is selected by default.

What it changes

~/.claude/settings.json

Claude Code hook entries.

~/.codex/hooks.json

Codex hook entries.

~/.salidium/hooks/relay.sh

The relay those hooks call, readable only by you.

Before each change to those settings files, the file is copied to <name>.salidium-backup, so that copy is the state immediately before the most recent change rather than the original. The relay is rewritten rather than backed up, because Salidium is the only thing that writes it. Only entries Salidium owns are added or replaced, and salidium uninstall-hooks takes them out again.

Codex trusts a hook by the hash of its definition, so a changed hook has to be shown to it once. Salidium says so when it happens: open /hooks in Codex and trust it.

What it reads

Salidium imports the last seven days of the session files your agents already write. Anything older is not read. SALIDIUM_HISTORY_DAYS changes that; the daemon reads it every time it starts, so set it and then run salidium restart if one is already running.

Running it again

• Run the same command later and it reopens whatever is already running.
• If the CLI is newer than an ordinary running daemon, it stops and restarts it. An enabled macOS always-on service uses a stable copied runtime instead; run salidium service install to update that copy.
• In a terminal that is not interactive it prints the address instead of opening a browser, and without --yes it changes no agent settings.

salidium stop stops the background service but keeps your saved explanation choice. To prevent model calls while keeping local reports live, run salidium explanations off. salidium status shows both the service and explanation state.

Without a browser window

The page is a control panel, not the daemon. Closing it does not stop collection. salidium open returns to it, and salidium status --watch monitors the daemon, queue, storage, and alerts in a terminal.

On macOS, salidium service install adds login startup, crash recovery, and a native menu-bar control. The menu shows health, PID, collection, queue, storage, alerts, and maintenance, and can open, start, stop, pause, resume, or drain the queue toward empty for a bounded interval. Queue and storage values are exact when safely observable and say unavailable rather than showing a partial value. A deliberate stop stays stopped; a crash is relaunched. salidium service disable turns both login items off, and salidium service uninstall removes their copied runtime while keeping reports and settings.

The macOS installer compiles its small native helper with Apple's Swift compiler. If it is unavailable, install Xcode Command Line Tools and retry. Native lock-screen notifications remain separately opt-in.

Upgrading from 0.3.0

Keep the same Salidium home. The first 0.4.0 daemon start upgrades the version 0.3.0 schema transactionally before it starts listening. It then prepares historical token usage in bounded background batches, so collection, status, stop, and the page remain responsive. Models & Usage says Preparing token history until the exact all-time ledger is ready.

Preparation records a durable cursor and resumes after a stop or crash. Retention, compaction, and storage optimization wait or refuse to run until it finishes. If always-on mode is installed, run salidium service install after upgrading the package so the copied runtime is updated before restart.