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.

VariableRead byWhat it does
SCIRIX_RELEASESinstall scriptsBase 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_CHECKthe binary, every invocationAny non-empty value disables the background "new version available" check. For CI runners and locked-down hosts.
SCIRIX_PREPROMPT_DEBUGthe binary, scirix prepromptAny 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:

AgentHook locationNotes
Claude Code~/.claude/settings.jsonMerged entry under hooks.UserPromptSubmit; other keys untouched.
Codex~/.codex/hooks.jsonSame merged shape as Claude Code.
Copilot~/.copilot/hooks/scirix.jsonscirix-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.jsonUnder Gemini's BeforeAgent event; injected via a JSON envelope (--format gemini).
Qwen Code~/.qwen/settings.jsonUserPromptSubmit; JSON envelope (--format qwen).
Junie~/.junie/config.jsonHooks 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.tomlA [[hooks]] entry edited in place — comments and other config are preserved byte-for-byte.
Kiro CLI / Kiro IDE~/.kiro/hooks/scirix.jsonscirix-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.jsonOne 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.tsGenerated TypeScript extension; user prompts + agent_settled. Agent root override: PI_CODING_AGENT_DIR.
OmO Native~/.omo/agent/extensions/scirix.tsGenerated TypeScript extension; prompt trigger (not preview) + agent_settled. OMO > SENPI > PI agent-dir overrides.
OpenCode~/.config/opencode/plugin/scirix.jsGenerated 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.