Advanced
05 / 05
Beyond the six environment variables in the Configuration table, three more knobs cover install-time host selection and operational toggles. They're rarely needed for an ordinary install against the public service, but they're what you reach for when self-hosting, mirroring artefacts, or debugging the agent integration.
| Variable | Read by | What it does |
|---|---|---|
SCIRIX_RELEASES | install scripts | Base URL for release artefacts (the binary archives + checksums.txt). Default https://cli.scirix.fi/releases. Distinct from SCIRIX_API_BASE — this is where the binary is downloaded from, not the API it talks to. |
SCIRIX_NO_UPDATE_CHECK | the binary, every invocation | Any non-empty value disables the background "new version available" check. For CI runners and locked-down hosts. |
SCIRIX_PREPROMPT_DEBUG | the binary, scirix preprompt | Any non-empty value surfaces the agent preprompt-hook diagnostics to stderr. Errors exit 0 so the prompt proceeds. No namespace emits nothing; a successful empty result emits a one-line status="empty" marker with the reason; fetch failures after namespace resolution emit a small status="unavailable" context marker. Failures also go to the state dir's preprompt.log. Enable this to diagnose missing context. |
Installing from a non-default host
SCIRIX_RELEASES is read by install.sh / install.ps1, so export it
in the same shell that runs the one-liner to pull the binary from a dev
or mirrored deployment instead of the public CDN:
curl -fsSL https://cli.dev.scirix.fi/install.sh \
| SCIRIX_RELEASES=https://cli.dev.scirix.fi/releases sh
$env:SCIRIX_RELEASES = "https://cli.dev.scirix.fi/releases"
irm https://cli.dev.scirix.fi/install.ps1 | iex
SCIRIX_RELEASES affects only the install scripts. The binary's own
scirix update always targets the compiled-in public release host, so a
CLI installed from a mirror will still self-update from
cli.scirix.fi — pin versions manually (scirix update --version …),
or set SCIRIX_NO_UPDATE_CHECK=1 to leave update management to whatever
provisioned the host.
Pointing a self-hosted install at its own API
Artefact host and API host are independent. A complete dev / self-hosted
setup pairs SCIRIX_RELEASES (install time) with SCIRIX_API_BASE +
SCIRIX_UI_BASE (use time). The most durable way to pin the API target
is a per-install config.json so every invocation resolves it without
re-exporting (see
API base resolution):
// ~/.scirix/config.json (Windows: %USERPROFILE%\.scirix\config.json)
{ "apiBase": "https://api.dev.scirix.fi", "uiBase": "https://ui.dev.scirix.fi" }
With that file in place, scirix auth login mints its token against the
dev realm and every later command follows. Prefer the env vars
(SCIRIX_API_BASE / SCIRIX_UI_BASE) for one-off or ephemeral shells,
and the per-tree .scirix-namespace apiBase when different folder
trees on one machine need different hosts.
Agent hook locations
scirix hooks install writes the preprompt hook into each agent's own
config surface. Where that lands, and anything the agent needs beyond
the install itself:
| Agent | Hook location | Notes |
|---|---|---|
| Claude Code | ~/.claude/settings.json | Merged entry under hooks.UserPromptSubmit; other keys untouched. |
| Codex | ~/.codex/hooks.json | Same merged shape as Claude Code. |
| Copilot | ~/.copilot/hooks/scirix.json | scirix-owned file serving VS Code, Visual Studio, and the Copilot CLI. The CLI's prompt event is notification-only, so injection works in the IDEs but not the CLI. |
| Gemini CLI | ~/.gemini/settings.json | Under Gemini's BeforeAgent event; injected via a JSON envelope (--format gemini). |
| Qwen Code | ~/.qwen/settings.json | UserPromptSubmit; JSON envelope (--format qwen). |
| Junie | ~/.junie/config.json | Hooks run in the Junie CLI; the IDE plugin loads the skill but not hooks. Flat JSON output (--format junie). |
| Kimi Code CLI | ~/.kimi-code/config.toml | A [[hooks]] entry edited in place — comments and other config are preserved byte-for-byte. |
| Kiro CLI / Kiro IDE | ~/.kiro/hooks/scirix.json | scirix-owned file in Kiro's v1 hook format, serving both the CLI (3.0+) and the IDE (1.0+). Carries UserPromptSubmit (context) and Stop (improvement uploads). $KIRO_HOME relocates ~/.kiro. Read at session start. |
| Kiro Crew | ~/.kiro/crew/hooks.json | One entry merged into Crew's script-hook list; other entries and keys untouched. Restart the Crew gateway after install, and usually pin a namespace: scirix hooks install --agent kirocrew --namespace <id> (a later flagless install keeps the pin). $KIROCREW_HOME relocates the data home. |
| Pi | ~/.pi/agent/extensions/scirix.ts | Generated TypeScript extension; user prompts + agent_settled. Agent root override: PI_CODING_AGENT_DIR. |
| OmO Native | ~/.omo/agent/extensions/scirix.ts | Generated TypeScript extension; prompt trigger (not preview) + agent_settled. OMO > SENPI > PI agent-dir overrides. |
| OpenCode | ~/.config/opencode/plugin/scirix.js | Generated plugin registering chat.message; auto-loaded, nothing to enable. |
| OpenClaw | ~/.openclaw/extensions/scirix/ | Generated plugin. Enable once (openclaw plugins enable scirix + gateway restart) and usually pin a namespace: scirix hooks install --agent openclaw --namespace <id>. |
| Hermes Agent | ~/.hermes/plugins/scirix/ | Generated plugin. Enable once (hermes plugins enable scirix) and usually pin a namespace, as for OpenClaw. |
| Grok Build | — | No hook — Grok's prompt event ignores hook output, so it gets the agent skill only. |
Re-running scirix hooks install is always safe: installs are
idempotent and self-healing (a stale binary path is rewritten in
place), and scirix hooks uninstall removes exactly what scirix wrote,
leaving foreign entries alone.
Pi and OmO Native
--agent pi selects Pi; --agent omo selects OmO Native.
omo-native aliases omo; omo-opencode and oh-my-opencode alias
opencode, not the Native extension. Autodetection uses the resolved
engine-state directory, never PATH or ambiguous ~/.omo/omo.jsonc.
Pi's root is PI_CODING_AGENT_DIR, else ~/.pi/agent, with leading tilde
expansion. OmO selects the first nonblank trimmed OMO_CODING_AGENT_DIR,
SENPI_CODING_AGENT_DIR, PI_CODING_AGENT_DIR, resolves it absolutely,
else uses ~/.omo/agent (HOME > USERPROFILE > OS home, even on Windows).
Use expanded absolute OmO paths. Set overrides consistently in the installer,
scirix and host environments. Both write extensions/scirix.ts; a shared
root keeps the first host's marked extension and refuses the other. Use
separate Pi and OmO roots. Foreign same-name artifacts are never overwritten.
Global skills/scirix links may share their bundled managed source.
Extensions load at startup; restart or use the host's /reload after changes.
Pi's --no-extensions disables discovery unless explicitly loaded using
--extension; --no-skills disables discovered skills. Respect OmO resource
controls and project trust too. Scirix never grants trust, enables disabled
resources, or overrides custom SDK resource loaders. Extensions execute with
the host's OS permissions: only load trusted code.
before_agent_start handles Pi user messages or OmO trigger: "prompt"
(excluding preview). It sends the original prompt and live
{cwd,session_id,transcript_path,leaf_id} to scirix preprompt --host pi|omo
on stdin in the actual workspace. Successful nonempty stdout becomes one
hidden model-visible custom context message; prompt/images/system prompt
are unchanged, with no new user message or continuation. agent_settled
sends fresh metadata to session-stop, including failed/aborted runs, with
no actionable return. It does not use intermediate turn_end or agent_end.
Ephemeral sessions can retrieve context but cannot upload a transcript.
Subprocesses use no shell, a 12-second ceiling and 256 KiB output caps;
foreground timeout/cancellation kills and reaps the child. The upload is
detached by the CLI, not awaited over the network.
Transcript branches and custom paths
Native JSONL v2/v3 transcripts are parent-ID trees. A string leaf_id
selects that exact active branch; null means an empty branch, and an
omitted leaf skips transcript context/uploads. Never use the file's last
entry as a guessed leaf. Recent context includes at most four prior
user/assistant turns (700 bytes each, 2000 total), excluding the persisted
current prompt. Uploads retain user/assistant text, allowlisted identifying
tool summaries and failed tool-result text, not successful outputs,
thinking, images, system/custom messages or compaction summaries. This is
raw conversational branch history, not the host's compacted model projection.
Broken trees and exceeded parser bounds produce no transcript data.
Only witnessed sessions are eligible, with the namespace improvements flag
positively enabled. The ledger preserves leaf/path metadata; branch/path
changes defeat mtime-only dedup. Crash sweeps use only the last witnessed
leaf, never unseen descendants or unrelated sessions. An explicit live
transcript_path always wins, including custom CLI/settings/SDK paths.
Fallback uses only a known full-ID filename suffix and verifies the header.
Pi honors PI_CODING_AGENT_SESSION_DIR; OmO selects OMO > SENPI > PI
*_CODING_AGENT_SESSION_DIR, then their agent-root sessions directories.
Invisible custom paths require the live event, not broader discovery.
OpenCode improvement uploads remain unsupported, including its OmO aliases.
An imported Claude invocation is skipped only for --host claude plus
hook_source: "opencode-plugin" when the resolved OpenCode plugin/ or
plugins/ has a marked scirix chat.message owner (scirix.js/.ts).
Without that owner existing Claude behavior remains; no foreign config is
rewritten.
Compatibility evidence
Baselines checked: Pi @earendil-works/pi-coding-agent 1.2.0,
Node >=22.19, and OmO Native omo-ai 5.1.33, Node >=24, pinned
@code-yeongyu/senpi 2026.10.13. Generated extensions were typechecked
against those declarations and exercised with executable stubs. Actual Pi loader + ExtensionRunner smoke passed eight trust/discovery
cases, but no paid/model run was performed. OmO runtime import was
blocked by missing pinned @earendil-works/chord 0.99.1; OmO evidence remains
typechecks and executable stubs, not live runtime proof. Older versions are
not asserted incompatible. Paid/model execution, full mode coverage and
Windows runtime still need host smoke.
Session-stop namespace resolution follows explicit --namespace >
SCIRIX_NS_ID > marker walk from the event's cwd. Host cwd metadata does
not override an explicit flag or environment namespace.