# Salidium documentation Salidium turns a Claude Code or Codex run into a report you can check. It runs on your machine, and every statement on a report says how it is known. Source: https://salidium.com/docs ## 1. Install One command, and the three files it asks to change. Source: https://salidium.com/docs/install Salidium needs Node 24 or newer. There is nothing else to install first. ```sh npx salidium ``` On first run it looks for Claude Code and Codex, prints the files it wants to change, and asks once. Answer anything but yes and nothing is written. ### 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 `.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 the running daemon, it stops and restarts it. - In a terminal that is not interactive it prints the address instead of opening a browser, and without `--yes` it changes nothing at all. ## 2. Opening the page What to do when the page asks for a token instead of showing you anything. Source: https://salidium.com/docs/the-page Salidium runs on your machine and nowhere else, so the page has to prove it is you before the daemon will talk to it. That is what the token is, and `salidium open` is how you get one. ![The Salidium page asking for a token, with the command salidium open beside a field for pasting one.](https://salidium.com/docs/gate-light-dce69376.png) There are two ways past it, and the first is the one to use. - **Run `salidium open`**: It opens this page with the token already attached. The page offers the command with a button that copies it. - **Paste a token**: The field takes the token itself, or the whole URL carrying it after `#token=`. The token is regenerated every time the daemon starts, so a tab you left open from before a restart signs itself out and says so. This is not an expiry you can extend. It is how a restart stops being something an old tab can keep talking to. ### When the daemon stops answering The page keeps whatever it already has and says what the connection is doing, beside the session list and again in the toolbar above a report. A page that has stopped receiving events but still looks live is the one thing it must not be. - **Connecting**: Opening the connection. This is what start-up looks like. - **Reconnecting**: Contact was lost and Salidium is retrying. Nothing is needed from you. - **Disconnected**: Nothing is arriving, and the daemon may have stopped. Open a session while the daemon is gone and the page says so in full, names `salidium` as the command that starts it again, and offers to try the request once more. ### Light or dark The control at the right of the toolbar above a report cycles three states: match the system, light, and dark. The choice is kept in this browser and applies to every page. ## 3. Sessions Which of your runs need you, which are still going, and which are done. Source: https://salidium.com/docs/sessions Every run your agents make becomes a session. The list puts the ones that need you at the top, because that is the question you open it with. ![The Salidium session list, grouped into Needs you, Working and Recent, with a find field above it, and the beginning of a report beside it.](https://salidium.com/docs/sessions-light-c358889d.png) - **Needs you**: A waiting agent, or a running or recently stopped session with something open in Needs you. These head the panel. - **Working**: Still running, and not already above. - **Recent**: Everything else, newest activity first. - **Nothing recorded**: Sessions that started and ended without running a turn. Folded away by default. ### The mark on a row Every row carries one. The question mark above the list keys the four a running agent produces; the fifth is what a row says when nothing was recorded at all. - **Working**: The agent is running. - **Waiting for you**: It has asked for something and stopped. - **Idle**: Running, but nothing is happening. - **Ended**: Finished. - **Unknown**: No status was recorded. A row can also carry a count of things to review. While the session is running that reads as needing you now; once it has stopped it reads as flagged during the session. Open a row and you get its [report](https://salidium.com/docs/report.md). ### Finding one The field above the list searches the whole store by name, repository and id, not only the sessions on screen. Salidium says how many it searched and how many it is showing, because the panel is a window onto a larger store rather than all of it. ## 4. Reading a report Whether the checks passed, what is still open, and what is waiting on you. Source: https://salidium.com/docs/report A session opens as a report, and the report is built to answer one question first: can you leave this alone, or does it need you? Everything else is underneath that answer. ![The top of a Salidium report: the session title, its tags, and the verdict reading 4 files changed, unverified.](https://salidium.com/docs/masthead-light-19b898be.png) ### The verdict One line, chosen in a fixed order of priority, and it is the first thing Salidium is willing to say about the run. - The run is waiting on you. - A check failed and nothing has passed since. - The agent is still working, and on what. - Files changed, and nothing has verified them. - The last check passed, and which. - How many things need you, or how many files changed, when there is nothing else to say. The verdict says how it was reached as well as what it is, so a line worked out rather than read from output says so. Open it and you get the checks it was read from, and [Evidence](https://salidium.com/docs/evidence.md) has the rest of the working. ### Verified Salidium recognises test, build, typecheck and lint runners by the command that was run, then reads the output. - **Passed**: The output said so, the exit code said so, or both. Where only one of them was available the row says which. - **Failed**: The run reported failures, or exited non-zero. - **Partial**: The output claimed a pass and the exit code disagreed. This is about the two disagreeing, not about how much the run covered. - **Unknown**: Nothing recognisable came back, or the run has not finished. A command name is not proof. What the output said outranks what the command looked like, and a run that is not the latest of its kind is flagged as such. ### Scope is not outcome A run narrowed to a path or a filter is recorded as partial scope, separately from whether it passed. A partial-scope pass never clears unverified, and neither does a lint pass on its own. A check that ran is not a check that covered the work. ### Left - Plan steps still pending or in progress. - Checks Salidium saw fail, with no later passing run. - Up to five things the agent said in its last turn were still outstanding. Only the second of those is Salidium's own observation. The first is the agent's task list and is marked as planned; the third is the agent's word for it and is marked as reported. [How we know](https://salidium.com/docs/provenance.md) is what tells them apart on the page. ### Needs you Each entry names the rule that raised it, and says how many times it fired when it fired more than once. - **A waiting prompt**: The agent asked for permission, for input, or a question. - **A failed check**: A run failed and nothing has passed since. - **A failed turn**: The turn itself ended in error. - **A destructive command**: `rm -rf`, a force push, a hard reset, a discarding checkout, `--no-verify` and four others. - **A push**: Work left the machine. - **Unverified changes**: Files changed with no passing check behind them. - **A claim without evidence**: The agent said checks passed when none ran. ## 5. Evidence The working behind the verdict, when you want to check it yourself. Source: https://salidium.com/docs/evidence The verdict is short because it has to be. When you want to see what it was read from, Evidence has the working, as four separate questions rather than one long scroll. ![The Evidence panel in Salidium, showing coverage of changed files against passing checks.](https://salidium.com/docs/evidence-light-8f006b86.png) - **Coverage**: How many changed files have had a passing check since they were last edited, as a grid you can open a file from. The first hundred and twenty are drawn and the rest are counted. - **Checks**: Every run of every method, oldest first, with the ones Salidium worked out drawn hollow. - **Changed**: The files that moved, ranked by lines, with the twenty largest drawn and a count of the rest. - **What happened**: The run in order, turn by turn, with what each turn did. A turn that handed work to subagents lists them underneath it, each with what it came back with. A filled square means that one file has had a passing check since it was last edited. It does not mean the project is green, and Coverage says so on the page rather than letting the picture imply it. Anything in any of the four views opens its [record](https://salidium.com/docs/records.md). > A turn that edited files and ran no check is marked as having nothing check those edits. An absence is a fact about the run, so it is drawn rather than left out. ## 6. Rewind, History and Quantities Seeing what a report said an hour ago, what changed since, and how much of it there is. Source: https://salidium.com/docs/rewind A report shows a session as it stands. These three answer the questions that are about time rather than about now. ### Rewind Rewind puts a scrubber at the foot of the session. Drag it and the page becomes the session as it stood at that moment, with everything later hidden. ![The Salidium rewind scrubber under a report, with marks for checks and commits along the track.](https://salidium.com/docs/rewind-light-afae774c.png) The track is one step per change, not per minute. A mark is a check or a commit, red where a check failed, and marks too close to draw apart are merged into one that takes the worst outcome in it. ### History History lists every change Salidium derived, oldest first, each with the kind of change it was and how it is known. It is a log, so it sits at the bottom where the newest entry is. Open it as a table across the page and it gains a How we know column. ![The Salidium history table, listing each change with when it happened, its kind, what changed, and a How we know column.](https://salidium.com/docs/history-light-bb6204b9.png) The filter narrows it to any of seven kinds: status, what changed, why, how, checks, left to do, needs review. When you come back to a session that moved while you were away, Salidium offers the changes since you last had it open, and History opens scoped to them. ### Quantities Measured totals beside the session, and only the ones that were observed. ![The Salidium quantities rail, showing changes, activity, model usage and the latest check.](https://salidium.com/docs/quantities-light-36a25eaf.png) - **Changes**: Files, added, removed. - **Activity**: Duration, commits, turns. - **Model**: Responses, input, output, cache read, cache write. - **Latest check**: The method, the outcome, the time. - **Data handling**: Credential-shaped strings redacted, records that could not be read, context compactions. > No figure appears in currency. That would be Salidium's arithmetic over a price table it does not carry, and on a subscription no amount is charged. ## 7. Records The original line your agent wrote, behind any statement on the page. Source: https://salidium.com/docs/records Nothing on a report is asserted without something behind it. The word `record` beside a statement opens what that is: the line in the file your agent wrote, where there is one, and always what Salidium stored. ![The Salidium record drawer, showing what Salidium stored beside the original line from the agent's own file.](https://salidium.com/docs/record-light-6c10ae0a.png) - **Salidium event**: What Salidium derived and stored. - **Provider record**: The original line from the agent's own file, with its path and line number. - **How we know**: When it happened, which lane it belongs to, its turn, what was redacted, its id. The arrow keys step to the record before and after this one in stored order, and the drawer will save both halves as a JSON file. Every [keyboard shortcut](https://salidium.com/docs/keyboard.md) is listed together. A provider line is not always there to show. The commonest reason is that there is none: an event that arrived by hook, or one Salidium derived, has no line in anyone's file. Beyond that the content may have been suppressed as sensitive, the file may be gone, or the record may have moved or changed since it was read. Salidium says which applies rather than showing whatever now occupies the line. ## 8. How we know Whether Salidium saw a thing happen, or is repeating what the agent said about it. Source: https://salidium.com/docs/provenance Your agent says the tests passed. Did Salidium watch them pass, or is it passing on a sentence the agent wrote? Every line of a report answers that, and these are the five answers it can give. - **Observed**: Recorded by a runtime or by Salidium: a diff, an exit code, a commit. Never written by a model. - **Reported**: The agent's words, or yours. Relayed and attributed, never promoted to observed by parsing them. - **Derived**: Salidium's own deterministic working. Where a named rule decided it, that rule's id is carried with it. - **Planned**: Items from the agent's task list, which are intent rather than fact. - **Explained**: The optional written explanation, and only ever that. This is the word on the page: the badge reads `explained`. > Observed is the default and prints nothing. Only the exceptions are labelled, because a badge on every line would say the same thing everywhere and so say nothing. ### When it cannot tell Where the record does not establish something, Salidium says so rather than filling the gap. - An exit code that was never observed stays unknown. It does not become zero. - A duration it cannot compute prints unknown. - Token counts it never saw are left out, not shown as nought. - A session with nothing in it is grouped as nothing recorded rather than described. ## 9. Explanations The one part of a report a model writes, and how to turn it off. Source: https://salidium.com/docs/explanations Most of a report is what Salidium observed. One part of it is prose, and prose has to be written by something. Salidium hands your own installed Claude or Codex CLI a short, redacted summary of the session and lets it write that part. It is labelled wherever it appears, it is the only thing that leaves the daemon, and you can switch it off without losing anything else on the page. ### When it runs - **Off**: The page Salidium derives, and nothing else. No model is ever called. - **When a session ends**: One explanation each, written once a session has finished or gone quiet. - **While it works**: A fresh explanation at every turn end. This is the default. The control is in the session list, under the sliders. `SALIDIUM_EXPLAINER=off` switches it off in the daemon's environment and outranks whatever is chosen here, and the control says so when it is set. ### What it is given - The last prompt. - Up to forty of the agent's statements. - Fifteen file names, shortened to their last two segments. - The last six check results. ### What it cannot do - It runs with its tools switched off, in a directory of its own. - Its own run never appears as a session in your list. - What comes back is validated against a schema before it can appear anywhere. - It cannot change Verified, Left or Needs you. ### When there is not one The panel says which of these applies rather than leaving a gap, and in every case the observed and derived parts of the report are unaffected. - **Explanations are off**: Nothing was sent to any agent. - **No compatible command**: No Claude or Codex CLI that Salidium can run was found, so nothing was sent. - **Asked, and nothing usable came back**: The agent answered but the answer did not validate, and the next turn tries again. - **Not yet**: One is written when the agent finishes its next turn. > Turn it off and every observed and derived part of the page stays exactly as it is. Nothing else on a report depends on it, and [How we know](https://salidium.com/docs/provenance.md) is what labels it wherever it appears. ## 10. What stays on your machine What Salidium keeps, where it keeps it, and what it runs in your repository. Source: https://salidium.com/docs/local The daemon, the event store, the report and the interface never leave your machine. There is no account, no telemetry and no hosted service. - State lives in `~/.salidium`, or wherever `SALIDIUM_HOME` points. [Environment](https://salidium.com/docs/environment.md) lists the rest. - The daemon listens only on `127.0.0.1`, by default on port `47822`. - Every request for your data carries a token, regenerated each time it starts. - The directories it creates are readable only by you, and it repairs their permissions on every start. ### Your repository When a turn ends, when a session starts, and after the agent commits, for a live session inside a git repository, Salidium runs four read-only commands to record where the work sat. - `git rev-parse --show-toplevel` - `git rev-parse HEAD` - `git rev-parse --abbrev-ref HEAD` - `git status --porcelain=v2 --untracked-files=normal` Nothing is written, and `SALIDIUM_NO_GIT=1` switches it off. ### Redaction Credential-shaped strings are redacted, and files on paths that hold credentials have their contents withheld. Both happen when an event is ingested rather than when it is shown. So what Salidium suppresses is suppressed everywhere: in what it shows you, and in the packet an [explanation](https://salidium.com/docs/explanations.md) is written from. > How much was redacted is counted, and the count is in Quantities under data handling. ## 11. Keyboard Every shortcut in the page. Source: https://salidium.com/docs/keyboard - **`[`**: Show or hide the session list. - **`h`**: Show or hide History. - **`l`**: Back to live, while a past moment is being shown. - **`←` `→`**: The record before or after this one, while a record is open. - **`Esc`**: Close the record, a panel, a popover, or the session list on a narrow window. - **`Tab`**: Move within whatever is open, and no further. > Shortcuts are ignored while you are typing in a field, and while a modifier key is held, so they never take a keystroke meant for the search box. ## 12. CLI The commands, and which of them need the daemon stopped. Source: https://salidium.com/docs/cli - **`salidium`**: Start it and open the page. This is what `npx salidium` runs. - **`salidium open`**: Open the page with the current token attached. - **`salidium status`**: Show the daemon and connection state. - **`salidium doctor`**: Check the local setup and report problems. - **`salidium show`**: Print a session as a report in the terminal. - **`salidium restart`**: Restart it and reopen the page. - **`salidium stop`**: Stop the local daemon. - **`salidium install-hooks`**: Connect an agent, or reconnect one. - **`salidium uninstall-hooks`**: Disconnect it again. - **`salidium reingest`**: Queue session files to be re-read on the next daemon start. One session, or `--all`, then `salidium restart`. - **`salidium retention`**: Show or set how long sessions are kept. - **`salidium pin`**: Exempt a session from automatic retention. - **`salidium unpin`**: Remove that exemption. - **`salidium forget`**: Delete one session for good. Requires `--yes`. - **`salidium audit-claims`**: Measure the claim classifier against every session in your store. > `reingest`, `retention`, `pin`, `unpin` and `forget` will not write while Salidium is running. Stop it first; offline maintenance does not rewrite a store under a running daemon. ## 13. Environment The variables the daemon reads. Source: https://salidium.com/docs/environment - **`SALIDIUM_HOME`**: Where state lives. Defaults to `~/.salidium`. - **`SALIDIUM_PORT`**: The loopback port. Defaults to `47822`. - **`SALIDIUM_HISTORY_DAYS`**: How far back to import session files. Defaults to `7`. Must be a whole number, and the daemon refuses to start on anything else. - **`SALIDIUM_EXPLAINER`**: `auto`, `claude`, `codex` or `off`. Chooses the backend, and only `off` outranks the setting in the page. - **`SALIDIUM_EXPLAIN_MODEL`**: A model id for the explainer, instead of its default. - **`SALIDIUM_NO_GIT`**: Set to `1` to stop the git snapshots. - **`SALIDIUM_LOG`**: `silent`, `info` or `debug`. Defaults to `info`. - **`SALIDIUM_LOG_FILE`**: Where the structured log is written. The CLI sets it when it starts the daemon. - **`SALIDIUM_EXPLAIN`**: Set to `0` to switch explanations off. The older spelling of `SALIDIUM_EXPLAINER=off`. - **`CLAUDE_CONFIG_DIR`**: Where Claude Code keeps its settings. Defaults to `~/.claude`. - **`CODEX_HOME`**: Where Codex keeps its state. Defaults to `~/.codex`. ## 14. Limits Where Salidium stops, and what to do about it. Source: https://salidium.com/docs/limits - **Native Windows**: No hook relay: it needs a POSIX shell and curl. Salidium still reads the session files your agents write, so history and live tailing work. What is lost is the sub-second hook notification. - **Recognised checks**: Only a fixed list of test, build, typecheck and lint runners counts as a check. A watch-mode run and a backgrounded run never do. - **A session read once**: It is not read again, however much the adapter improves, because its cursor still matches. `salidium reingest --all` then `salidium restart` is what recovers it. - **Retention**: Sessions are kept forever unless you set a policy. Working, waiting and pinned sessions are never removed by one. - **Ingest problems**: An unreadable transcript record is counted in Quantities under data handling. A dropped hook payload is not: it reaches the daemon log and nothing else. > `salidium doctor` is the first thing to run when something is wrong. It checks the setup and prints what it finds rather than a score. The rest of the commands are under [CLI](https://salidium.com/docs/cli.md).