Sidewisp Plugin Technical Reference

COPY-PASTE RUNBOOKS

Agent-assisted setup

Shipped runtimes get install runbooks. Other established coding agents get custom-adapter audit, build, and verification chains with explicit unsupported status.

Prepare a local shell session

HUMAN-ONLY SHELLPLAIN TEXT

read -rsp 'Sidewisp setup token: ' SIDEWISP_SETUP_TOKEN
export SIDEWISP_SETUP_TOKEN
printf '\n'

# Start your coding agent from this shell so it inherits the variable.
# Do not paste the token into a prompt, issue, log, or source file.

01OpenClawNative plugin · OpenClaw 2026.7.1+SHIPPED02Hermes AgentPer-user sidecar · Linux or macOSSHIPPED 03CodexStable command hooks · Codex CLI 0.145.0+SHIPPED04Claude CodeCommand hooks · Claude Code 2.1.218+SHIPPED05Gemini CLICustom adapter development · not shipped in v0.2.0CUSTOM 06GitHub Copilot CLICustom adapter development · not shipped in v0.2.0CUSTOM 07OpenCodeCustom adapter development · not shipped in v0.2.0CUSTOM 08Cursor AgentCustom adapter development · not shipped in v0.2.0CUSTOM 09Kiro CLICustom adapter development · not shipped in v0.2.0CUSTOM

OpenClawNative plugin · OpenClaw 2026.7.1+SHIPPED

Run phases in order. Each phase must report evidence before the next phase starts. Keep real setup tokens outside chat and source control.

OPENCLAW · 01 · Read-only preflightPLAIN TEXT

Prepare a read-only Sidewisp Plugin v0.2.0 compatibility report for this OpenClaw host.

1. Read https://sidewisp.com/docs/ and
   https://github.com/golem-workers/sidewisp-plugin/blob/v0.2.0/docs/OPENCLAW.md.
2. Check Node.js and OpenClaw versions against the documented minimums.
3. Inspect current plugin state and whether a Sidewisp installation already exists.
4. Check outbound HTTPS reachability to https://api.sidewisp.com without sending credentials.
5. Return PASS, WARN, or FAIL for every prerequisite, plus exact remediation commands.

Do not install, restart, edit configuration, enroll, or print environment values in this phase.

OPENCLAW · 02 · Install and enrollPLAIN TEXT

Install Sidewisp Plugin v0.2.0 on this OpenClaw host.

Prerequisites:
- Phase 1 passed.
- SIDEWISP_SETUP_TOKEN is available through the approved process environment or secret store.

Requirements:
1. Never print, log, persist, or repeat SIDEWISP_SETUP_TOKEN.
2. Install immutable tag v0.2.0, never main.
3. Inspect the loaded plugin before enrollment.
4. Configure the setup token by variable reference, restart the gateway once, and wait for enrollment.
5. Confirm the one-time token was removed from active configuration after exchange.
6. Stop on any checksum, version, load, or enrollment failure. Do not bypass checks.

Report changed files/config keys, commands executed, and sanitized results. If the token is unavailable, stop and give the human the exact local command to run; never ask for the token in chat.

OPENCLAW · 03 · Verify and hand offPLAIN TEXT

Verify the existing Sidewisp v0.2.0 OpenClaw installation without changing it.

Run plugin runtime inspection, sidewisp.status, and sidewisp.supportBundle.
Confirm:
- service sidewisp-collector is loaded;
- only sidewisp.status and sidewisp.supportBundle operator methods are exposed;
- no agent tools or model providers were added;
- configured=true, mode=zero-llm, installation.state=active;
- spool is healthy and uploader is idle or sent;
- support output contains no setup token, installation secret, event payload,
  prompt, response, identity, or full endpoint path.

Return a compact evidence table. Mark any degraded adapter capability explicitly.
Do not claim success when a required field is missing.

Hermes AgentPer-user sidecar · Linux or macOSSHIPPED

Run phases in order. Each phase must report evidence before the next phase starts. Keep real setup tokens outside chat and source control.

HERMES AGENT · 01 · Read-only preflightPLAIN TEXT

Prepare a read-only Sidewisp Plugin v0.2.0 compatibility report for this Hermes Agent host.

1. Read https://sidewisp.com/docs/ and
   https://github.com/golem-workers/sidewisp-plugin/blob/v0.2.0/docs/HERMES.md.
2. Check Node.js 22.22.3+, locate the Hermes source directory, and identify OS/service manager.
3. Confirm a systemd user session on Linux or LaunchAgent support on macOS.
4. Inspect existing Sidewisp Hermes install/state directories without reading credentials or telemetry payloads.
5. Check outbound HTTPS reachability to https://api.sidewisp.com without sending credentials.

Return PASS, WARN, or FAIL for every prerequisite. Do not install, enroll, start services, or modify files.

HERMES AGENT · 02 · Install and enrollPLAIN TEXT

Install Sidewisp Plugin v0.2.0 for Hermes Agent as a least-privileged per-user sidecar.

Prerequisites:
- Phase 1 passed.
- SIDEWISP_SETUP_TOKEN is available through the approved process environment or secret store.

Requirements:
1. Download the v0.2.0 release archive and SHA256SUMS.
2. Verify SHA-256 and GitHub Sigstore attestation before unpacking.
3. Use the detected HERMES_SOURCE_DIR and https://api.sidewisp.com.
4. Run scripts/install-hermes.sh by referencing SIDEWISP_SETUP_TOKEN; never print it.
5. Do not use sudo or create a system service.
6. Confirm owner-only permissions on install/state files and that no token entered the service definition.

Stop on failed verification, unsupported service manager, enrollment failure, or unhealthy startup. Report only sanitized evidence.

HERMES AGENT · 03 · Verify and hand offPLAIN TEXT

Verify the Sidewisp v0.2.0 Hermes collector without changing it.

On Linux inspect the systemd user unit and journal. On macOS inspect the
com.sidewisp.hermes-collector LaunchAgent. Confirm:
- service is active under the current user;
- current points to an immutable release directory;
- installation.json and spool.sqlite are owner-only;
- heartbeat is current and delivery is not permanently retrying;
- service environment contains no setup token;
- logs remain metadata-only and contain no prompts, files, tool payloads, or credentials.

Return exact service manager, paths, permission modes, heartbeat age, and PASS/WARN/FAIL.
Do not print credential or event contents.

CodexStable command hooks · Codex CLI 0.145.0+SHIPPED

Run phases in order. Each phase must report evidence before the next phase starts. Keep real setup tokens outside chat and source control.

CODEX · 01 · Read-only preflightPLAIN TEXT

Prepare a read-only Sidewisp Plugin v0.2.0 compatibility report for this Codex CLI host.

1. Read https://sidewisp.com/docs/ and
   https://github.com/golem-workers/sidewisp-plugin/blob/v0.2.0/docs/CODEX.md.
2. Check Node.js 22.22.3+, Codex CLI 0.145.0+, and that "codex features list"
   reports hooks as stable.
3. Inspect whether ~/.codex/hooks.json and Sidewisp Codex install/state paths exist.
4. Describe existing hook groups without printing commands containing secrets or environment values.
5. Check outbound HTTPS reachability to https://api.sidewisp.com without sending credentials.

Return PASS, WARN, or FAIL for every prerequisite. Do not modify hooks, install, enroll, or restart Codex.

CODEX · 02 · Install and enrollPLAIN TEXT

Install Sidewisp Plugin v0.2.0 for Codex CLI.

Prerequisites:
- Phase 1 passed.
- SIDEWISP_SETUP_TOKEN is available through the approved process environment or secret store.

Requirements:
1. Download and verify the v0.2.0 archive, SHA-256 checksum, and GitHub attestation.
2. Run scripts/install-codex.sh using SIDEWISP_SETUP_TOKEN by variable reference.
3. Preserve every unrelated ~/.codex/hooks.json group and handler.
4. Confirm hooks.json.sidewisp-backup was created once when prior settings existed.
5. Confirm install root ~/.local/share/sidewisp-codex and state root
   ~/.local/state/sidewisp-codex are owner-only.
6. Never print prompts, transcripts, tool input/output, credentials, or the setup token.

After install, stop at the Codex trust boundary. Ask the human to restart Codex,
open /hooks, review the exact Sidewisp command, and approve its hash. Do not claim
collection is active before that approval.

CODEX · 03 · Verify and hand offPLAIN TEXT

Verify the Sidewisp v0.2.0 Codex adapter after the human approved it in /hooks.

Create one harmless session with one harmless local tool call, then inspect only
Sidewisp status metadata and spool counts. Confirm:
- SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, and SessionEnd hooks are installed once;
- unrelated Codex hooks remain unchanged;
- hook command exits without stdout/stderr and cannot block Codex;
- sanitized events contain opaque IDs, tool name, outcome, and bounded scalars only;
- prompts, transcripts, assistant messages, tool arguments, and tool output are absent;
- uploader acknowledges delivery or retains it for retry.

Report provider-hooks as degraded: Codex exposes no dedicated provider-failure hook.
Never print event payloads if they contain unexpected content; report a privacy failure instead.

Claude CodeCommand hooks · Claude Code 2.1.218+SHIPPED

Run phases in order. Each phase must report evidence before the next phase starts. Keep real setup tokens outside chat and source control.

CLAUDE CODE · 01 · Read-only preflightPLAIN TEXT

Prepare a read-only Sidewisp Plugin v0.2.0 compatibility report for this Claude Code host.

1. Read https://sidewisp.com/docs/ and
   https://github.com/golem-workers/sidewisp-plugin/blob/v0.2.0/docs/CLAUDE_CODE.md.
2. Check Node.js 22.22.3+ and Claude Code 2.1.218+.
3. Inspect whether ~/.claude/settings.json and Sidewisp Claude Code install/state paths exist.
4. Describe existing hook groups without printing commands containing secrets or environment values.
5. Check outbound HTTPS reachability to https://api.sidewisp.com without sending credentials.

Return PASS, WARN, or FAIL for every prerequisite. Do not modify settings, install, enroll, or restart Claude Code.

CLAUDE CODE · 02 · Install and enrollPLAIN TEXT

Install Sidewisp Plugin v0.2.0 for Claude Code.

Prerequisites:
- Phase 1 passed.
- SIDEWISP_SETUP_TOKEN is available through the approved process environment or secret store.

Requirements:
1. Download and verify the v0.2.0 archive, SHA-256 checksum, and GitHub attestation.
2. Run scripts/install-claude-code.sh using SIDEWISP_SETUP_TOKEN by variable reference.
3. Preserve every unrelated field and hook in ~/.claude/settings.json.
4. Confirm settings.json.sidewisp-backup was created once when prior settings existed.
5. Confirm install root ~/.local/share/sidewisp-claude-code and state root
   ~/.local/state/sidewisp-claude-code are owner-only.
6. Never print prompts, transcripts, tool input/output, provider error text,
   credentials, or the setup token.

Restart Claude Code after successful installation. Stop on verification, version,
enrollment, or settings-merge failure. Report only sanitized evidence.

CLAUDE CODE · 03 · Verify and hand offPLAIN TEXT

Verify the Sidewisp v0.2.0 Claude Code adapter without changing unrelated settings.

Run one harmless session and one harmless tool call. Confirm:
- lifecycle, turn, tool, permission-denial, and StopFailure hooks are installed once;
- unrelated Claude Code settings and hooks remain unchanged;
- hook commands return no decisions, stdout, or stderr and cannot block the runtime;
- only documented StopFailure classes are retained;
- error_details, last_assistant_message, prompts, transcripts, tool_input,
  tool_response, commands, files, and credentials are absent;
- uploader acknowledges delivery or retains it for retry.

Return a PASS/WARN/FAIL evidence table with installed version, hook count, state
permissions, and delivery state. Do not print event contents containing unexpected data.

Gemini CLICustom adapter development · not shipped in v0.2.0CUSTOM BUILD

Run phases in order. This chain audits and builds a local adapter; it does not turn an unshipped runtime into official v0.2.0 support.

GEMINI CLI · 01 · Read-only hook auditPLAIN TEXT

Prepare a read-only Sidewisp custom-adapter feasibility report for Gemini CLI.

1. Read https://sidewisp.com/docs/, the Sidewisp Plugin v0.2.0 source, and
   https://geminicli.com/docs/hooks/
2. Record the installed Gemini CLI version and enumerate only lifecycle,
   turn, tool, permission, and failure events documented for that exact version.
3. Map each usable event to sidewisp.telemetry.v1. Mark missing capabilities
   DEGRADED or UNAVAILABLE; do not infer events from logs or transcript files.
4. Identify every content-bearing input field that the adapter must ignore.
5. Verify hooks can run non-blocking commands and existing configuration can be
   merged, backed up, and restored without replacing unrelated handlers.

Return PASS, WARN, or FAIL with source links and an event-mapping table.
Do not install, edit configuration, enroll, or claim official Sidewisp support.

GEMINI CLI · 02 · Build custom adapterPLAIN TEXT

Build a local custom Sidewisp adapter for Gemini CLI.

Prerequisites:
- Phase 1 found a documented, non-blocking integration surface.
- Work starts from immutable Sidewisp Plugin tag v0.2.0 on a new branch.

Requirements:
1. Implement sidewisp.runtime-adapter.v1 and declare exact capabilities.
2. Reuse the command-hook inbox, SQLite spool, credential, and HMAC delivery layers.
3. Sanitize against the closed telemetry allowlist before durable storage.
4. Never read or retain prompts, responses, transcripts, files, commands,
   tool input/output, raw errors, environment values, or credentials.
5. Preserve unrelated Gemini CLI configuration and create an idempotent
   install, uninstall, backup, and rollback path.
6. Add unit tests, fixture tests, privacy-negative tests, and an isolated E2E.
7. Stop if the runtime exposes only content-bearing logs or blocking hooks.

This is a custom AGPL build, not a Sidewisp v0.2.0 shipped adapter.
Do not publish, deploy, or describe it as officially supported.

GEMINI CLI · 03 · Verify custom buildPLAIN TEXT

Verify the local custom Gemini CLI adapter.

Run one harmless session, one harmless turn, one successful tool call, and one
safe failure path. Confirm:
- declared capabilities match observed events exactly;
- hooks cannot block or alter Gemini CLI;
- unrelated hooks and settings remain unchanged;
- only opaque IDs, tool name, outcome, bounded duration, and allowlisted facts survive;
- prompts, responses, transcripts, files, commands, tool payloads, raw errors,
  environment values, and credentials are absent;
- duplicate import is idempotent and an offline receiver leaves durable retry state;
- uninstall restores prior configuration without deleting pending spool data.

Return PASS/WARN/FAIL evidence and label the result LOCAL CUSTOM BUILD.
Do not claim Sidewisp v0.2.0 support.

GitHub Copilot CLICustom adapter development · not shipped in v0.2.0CUSTOM BUILD

Run phases in order. This chain audits and builds a local adapter; it does not turn an unshipped runtime into official v0.2.0 support.

GITHUB COPILOT CLI · 01 · Read-only hook auditPLAIN TEXT

Prepare a read-only Sidewisp custom-adapter feasibility report for GitHub Copilot CLI.

1. Read https://sidewisp.com/docs/, the Sidewisp Plugin v0.2.0 source, and
   https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-hooks
2. Record the installed GitHub Copilot CLI version and enumerate only lifecycle,
   turn, tool, permission, and failure events documented for that exact version.
3. Map each usable event to sidewisp.telemetry.v1. Mark missing capabilities
   DEGRADED or UNAVAILABLE; do not infer events from logs or transcript files.
4. Identify every content-bearing input field that the adapter must ignore.
5. Verify hooks can run non-blocking commands and existing configuration can be
   merged, backed up, and restored without replacing unrelated handlers.

Return PASS, WARN, or FAIL with source links and an event-mapping table.
Do not install, edit configuration, enroll, or claim official Sidewisp support.

GITHUB COPILOT CLI · 02 · Build custom adapterPLAIN TEXT

Build a local custom Sidewisp adapter for GitHub Copilot CLI.

Prerequisites:
- Phase 1 found a documented, non-blocking integration surface.
- Work starts from immutable Sidewisp Plugin tag v0.2.0 on a new branch.

Requirements:
1. Implement sidewisp.runtime-adapter.v1 and declare exact capabilities.
2. Reuse the command-hook inbox, SQLite spool, credential, and HMAC delivery layers.
3. Sanitize against the closed telemetry allowlist before durable storage.
4. Never read or retain prompts, responses, transcripts, files, commands,
   tool input/output, raw errors, environment values, or credentials.
5. Preserve unrelated GitHub Copilot CLI configuration and create an idempotent
   install, uninstall, backup, and rollback path.
6. Add unit tests, fixture tests, privacy-negative tests, and an isolated E2E.
7. Stop if the runtime exposes only content-bearing logs or blocking hooks.

This is a custom AGPL build, not a Sidewisp v0.2.0 shipped adapter.
Do not publish, deploy, or describe it as officially supported.

GITHUB COPILOT CLI · 03 · Verify custom buildPLAIN TEXT

Verify the local custom GitHub Copilot CLI adapter.

Run one harmless session, one harmless turn, one successful tool call, and one
safe failure path. Confirm:
- declared capabilities match observed events exactly;
- hooks cannot block or alter GitHub Copilot CLI;
- unrelated hooks and settings remain unchanged;
- only opaque IDs, tool name, outcome, bounded duration, and allowlisted facts survive;
- prompts, responses, transcripts, files, commands, tool payloads, raw errors,
  environment values, and credentials are absent;
- duplicate import is idempotent and an offline receiver leaves durable retry state;
- uninstall restores prior configuration without deleting pending spool data.

Return PASS/WARN/FAIL evidence and label the result LOCAL CUSTOM BUILD.
Do not claim Sidewisp v0.2.0 support.

OpenCodeCustom adapter development · not shipped in v0.2.0CUSTOM BUILD

Run phases in order. This chain audits and builds a local adapter; it does not turn an unshipped runtime into official v0.2.0 support.

OPENCODE · 01 · Read-only hook auditPLAIN TEXT

Prepare a read-only Sidewisp custom-adapter feasibility report for OpenCode.

1. Read https://sidewisp.com/docs/, the Sidewisp Plugin v0.2.0 source, and
   https://opencode.ai/docs/plugins/
2. Record the installed OpenCode version and enumerate only lifecycle,
   turn, tool, permission, and failure events documented for that exact version.
3. Map each usable event to sidewisp.telemetry.v1. Mark missing capabilities
   DEGRADED or UNAVAILABLE; do not infer events from logs or transcript files.
4. Identify every content-bearing input field that the adapter must ignore.
5. Verify hooks can run non-blocking commands and existing configuration can be
   merged, backed up, and restored without replacing unrelated handlers.

Return PASS, WARN, or FAIL with source links and an event-mapping table.
Do not install, edit configuration, enroll, or claim official Sidewisp support.

OPENCODE · 02 · Build custom adapterPLAIN TEXT

Build a local custom Sidewisp adapter for OpenCode.

Prerequisites:
- Phase 1 found a documented, non-blocking integration surface.
- Work starts from immutable Sidewisp Plugin tag v0.2.0 on a new branch.

Requirements:
1. Implement sidewisp.runtime-adapter.v1 and declare exact capabilities.
2. Reuse the command-hook inbox, SQLite spool, credential, and HMAC delivery layers.
3. Sanitize against the closed telemetry allowlist before durable storage.
4. Never read or retain prompts, responses, transcripts, files, commands,
   tool input/output, raw errors, environment values, or credentials.
5. Preserve unrelated OpenCode configuration and create an idempotent
   install, uninstall, backup, and rollback path.
6. Add unit tests, fixture tests, privacy-negative tests, and an isolated E2E.
7. Stop if the runtime exposes only content-bearing logs or blocking hooks.

This is a custom AGPL build, not a Sidewisp v0.2.0 shipped adapter.
Do not publish, deploy, or describe it as officially supported.

OPENCODE · 03 · Verify custom buildPLAIN TEXT

Verify the local custom OpenCode adapter.

Run one harmless session, one harmless turn, one successful tool call, and one
safe failure path. Confirm:
- declared capabilities match observed events exactly;
- hooks cannot block or alter OpenCode;
- unrelated hooks and settings remain unchanged;
- only opaque IDs, tool name, outcome, bounded duration, and allowlisted facts survive;
- prompts, responses, transcripts, files, commands, tool payloads, raw errors,
  environment values, and credentials are absent;
- duplicate import is idempotent and an offline receiver leaves durable retry state;
- uninstall restores prior configuration without deleting pending spool data.

Return PASS/WARN/FAIL evidence and label the result LOCAL CUSTOM BUILD.
Do not claim Sidewisp v0.2.0 support.

Cursor AgentCustom adapter development · not shipped in v0.2.0CUSTOM BUILD

Run phases in order. This chain audits and builds a local adapter; it does not turn an unshipped runtime into official v0.2.0 support.

CURSOR AGENT · 01 · Read-only hook auditPLAIN TEXT

Prepare a read-only Sidewisp custom-adapter feasibility report for Cursor Agent.

1. Read https://sidewisp.com/docs/, the Sidewisp Plugin v0.2.0 source, and
   https://cursor.com/docs
2. Record the installed Cursor Agent version and enumerate only lifecycle,
   turn, tool, permission, and failure events documented for that exact version.
3. Map each usable event to sidewisp.telemetry.v1. Mark missing capabilities
   DEGRADED or UNAVAILABLE; do not infer events from logs or transcript files.
4. Identify every content-bearing input field that the adapter must ignore.
5. Verify hooks can run non-blocking commands and existing configuration can be
   merged, backed up, and restored without replacing unrelated handlers.

Return PASS, WARN, or FAIL with source links and an event-mapping table.
Do not install, edit configuration, enroll, or claim official Sidewisp support.

CURSOR AGENT · 02 · Build custom adapterPLAIN TEXT

Build a local custom Sidewisp adapter for Cursor Agent.

Prerequisites:
- Phase 1 found a documented, non-blocking integration surface.
- Work starts from immutable Sidewisp Plugin tag v0.2.0 on a new branch.

Requirements:
1. Implement sidewisp.runtime-adapter.v1 and declare exact capabilities.
2. Reuse the command-hook inbox, SQLite spool, credential, and HMAC delivery layers.
3. Sanitize against the closed telemetry allowlist before durable storage.
4. Never read or retain prompts, responses, transcripts, files, commands,
   tool input/output, raw errors, environment values, or credentials.
5. Preserve unrelated Cursor Agent configuration and create an idempotent
   install, uninstall, backup, and rollback path.
6. Add unit tests, fixture tests, privacy-negative tests, and an isolated E2E.
7. Stop if the runtime exposes only content-bearing logs or blocking hooks.

This is a custom AGPL build, not a Sidewisp v0.2.0 shipped adapter.
Do not publish, deploy, or describe it as officially supported.

CURSOR AGENT · 03 · Verify custom buildPLAIN TEXT

Verify the local custom Cursor Agent adapter.

Run one harmless session, one harmless turn, one successful tool call, and one
safe failure path. Confirm:
- declared capabilities match observed events exactly;
- hooks cannot block or alter Cursor Agent;
- unrelated hooks and settings remain unchanged;
- only opaque IDs, tool name, outcome, bounded duration, and allowlisted facts survive;
- prompts, responses, transcripts, files, commands, tool payloads, raw errors,
  environment values, and credentials are absent;
- duplicate import is idempotent and an offline receiver leaves durable retry state;
- uninstall restores prior configuration without deleting pending spool data.

Return PASS/WARN/FAIL evidence and label the result LOCAL CUSTOM BUILD.
Do not claim Sidewisp v0.2.0 support.

Kiro CLICustom adapter development · not shipped in v0.2.0CUSTOM BUILD

Run phases in order. This chain audits and builds a local adapter; it does not turn an unshipped runtime into official v0.2.0 support.

KIRO CLI · 01 · Read-only hook auditPLAIN TEXT

Prepare a read-only Sidewisp custom-adapter feasibility report for Kiro CLI.

1. Read https://sidewisp.com/docs/, the Sidewisp Plugin v0.2.0 source, and
   https://kiro.dev/docs/cli/hooks/
2. Record the installed Kiro CLI version and enumerate only lifecycle,
   turn, tool, permission, and failure events documented for that exact version.
3. Map each usable event to sidewisp.telemetry.v1. Mark missing capabilities
   DEGRADED or UNAVAILABLE; do not infer events from logs or transcript files.
4. Identify every content-bearing input field that the adapter must ignore.
5. Verify hooks can run non-blocking commands and existing configuration can be
   merged, backed up, and restored without replacing unrelated handlers.

Return PASS, WARN, or FAIL with source links and an event-mapping table.
Do not install, edit configuration, enroll, or claim official Sidewisp support.

KIRO CLI · 02 · Build custom adapterPLAIN TEXT

Build a local custom Sidewisp adapter for Kiro CLI.

Prerequisites:
- Phase 1 found a documented, non-blocking integration surface.
- Work starts from immutable Sidewisp Plugin tag v0.2.0 on a new branch.

Requirements:
1. Implement sidewisp.runtime-adapter.v1 and declare exact capabilities.
2. Reuse the command-hook inbox, SQLite spool, credential, and HMAC delivery layers.
3. Sanitize against the closed telemetry allowlist before durable storage.
4. Never read or retain prompts, responses, transcripts, files, commands,
   tool input/output, raw errors, environment values, or credentials.
5. Preserve unrelated Kiro CLI configuration and create an idempotent
   install, uninstall, backup, and rollback path.
6. Add unit tests, fixture tests, privacy-negative tests, and an isolated E2E.
7. Stop if the runtime exposes only content-bearing logs or blocking hooks.

This is a custom AGPL build, not a Sidewisp v0.2.0 shipped adapter.
Do not publish, deploy, or describe it as officially supported.

KIRO CLI · 03 · Verify custom buildPLAIN TEXT

Verify the local custom Kiro CLI adapter.

Run one harmless session, one harmless turn, one successful tool call, and one
safe failure path. Confirm:
- declared capabilities match observed events exactly;
- hooks cannot block or alter Kiro CLI;
- unrelated hooks and settings remain unchanged;
- only opaque IDs, tool name, outcome, bounded duration, and allowlisted facts survive;
- prompts, responses, transcripts, files, commands, tool payloads, raw errors,
  environment values, and credentials are absent;
- duplicate import is idempotent and an offline receiver leaves durable retry state;
- uninstall restores prior configuration without deleting pending spool data.

Return PASS/WARN/FAIL evidence and label the result LOCAL CUSTOM BUILD.
Do not claim Sidewisp v0.2.0 support.

Completion criteria

artifact

Immutable v0.2.0 release verified by SHA-256 and Sigstore attestation.

runtime

Supported Node.js and runtime version; adapter-specific hooks or service active.

credential

One-time token consumed, scoped credential owner-only, no token retained.

privacy

No prompts, responses, files, identities, secrets, or tool payloads enter telemetry.

delivery

Signed batch acknowledged, or durable local retry state proven during outage.

evidence

Agent returns exact versions, paths, permission modes, health, and degraded capabilities.

SYSTEM MODEL

Architecture and invariants

A zero-LLM collector converts runtime facts into a closed schema, commits them to a bounded local spool, and uploads signed batches to a compatible receiver.

Sidewisp Plugin observes deterministic runtime facts, sanitizes them against a closed allowlist, stores pending events in an owner-only SQLite spool, and sends signed batches over HTTPS. OpenClaw runs it as a native background plugin, Hermes uses a per-user sidecar, and Codex plus Claude Code use documented command hooks.

The plugin contains no hosted dashboard, incident engine, alerting service, or autonomous remediation. Use Sidewisp's managed service, implement the compatible receiver protocol below, or generate your own operations stack from the public contract.

Data path

01 · RUNTIMEFour shipped
adaptersLifecycle + health facts

02 · PLUGINSanitize
and spoolClosed schema + SQLite

03 · RECEIVERVerify
and storeSigned HTTPS batches

04 · YOUR STACKDashboard
and alertsAny compatible tools

Non-negotiable invariants

Content-free

No prompts, responses, files, credentials, personal data, or tool payloads.

Durable

Pending events survive restarts and package upgrades in a bounded SQLite spool.

Inspectable

Read-only status and support methods expose health without exposing event content.

Portable

Versioned telemetry and receiver contracts keep storage and presentation replaceable.

Compatibility matrix

Adapter	Minimum runtime	Integration	Default state	Known limitation
OpenClaw	2026.7.1	Native background plugin	OpenClaw state / `sidewisp`	Hook coverage follows plugin API
Hermes	Supported checkout	systemd user / LaunchAgent	`~/.local/state/sidewisp-hermes`	Sidecar until stable native lifecycle exists
Codex	CLI 0.145.0	`~/.codex/hooks.json`	`~/.local/state/sidewisp-codex`	No dedicated provider-failure hook
Claude Code	2.1.218	`~/.claude/settings.json`	`~/.local/state/sidewisp-claude-code`	Only documented failure classes retained

Every adapter requires Node.js 22.22.3 or newer, outbound HTTPS, and one scoped installation credential. Unknown telemetry schemas stay local. Production installs pin immutable release artifacts, never main.

Configuration reference

Setting	Scope	Default	Semantics
`enabled`	OpenClaw config	`true`	Starts collector service when true. False retains package and state.
`endpoint`	OpenClaw config	`https://api.sidewisp.com`	HTTPS base URL implementing enrollment and batch contracts.
`setupToken`	OpenClaw config	none	Single-use secret. Removed from active config after successful exchange.
`SIDEWISP_ENDPOINT`	Sidecar / command hooks	`https://api.sidewisp.com`	HTTPS receiver base URL stored as origin only.
`SIDEWISP_SETUP_TOKEN`	Installer process	none	Required only for first enrollment; unset after exchange.
`SIDEWISP_INSTALL_ROOT`	Sidecar / command hooks	XDG data directory	Immutable release directories plus atomic `current` symlink.
`SIDEWISP_STATE_DIR`	Sidecar / command hooks	XDG state directory	Owner-only credential, runtime-hook config, inbox, and SQLite spool.
`HERMES_SOURCE_DIR`	Hermes only	`~/hermes-agent`	Explicit Hermes checkout observed by per-user sidecar.

Runtime coverage

Plugin v0.2.0 ships four collector adapters. Each declares its exact capabilities instead of pretending every runtime exposes the same hooks. Custom runtimes can implement the public adapter and telemetry contracts.

SUPPORTED

OpenClaw

Native background plugin with typed lifecycle/tool hooks, recovery, health, status, and support diagnostics.

SHIPPED IN V0.2.0

SUPPORTED

Hermes Agent

Least-privileged per-user sidecar using the shared telemetry, spool, credential, and delivery contracts.

SHIPPED IN V0.2.0

SUPPORTED

Codex

Stable command hooks cover sessions, turns, and tools. Provider failures remain an explicitly degraded capability.

CODEX CLI 0.145.0+

SUPPORTED

Claude Code

Command hooks cover sessions, turns, tools, permission denials, and bounded provider/context failure classes.

CLAUDE CODE 2.1.218+

EXTENSIBLE

Custom runtimes

Implement sidewisp.runtime-adapter.v1, declare every capability, and emit sanitized sidewisp.telemetry.v1 facts.

PUBLIC ADAPTER INTERFACE

NATIVE PLUGIN

Install on OpenClaw

OpenClaw 2026.7.1+, Node.js 22.22.3+, outbound HTTPS, and a one-time token from Sidewisp or your compatible receiver are required. No sudo, inbound port, model provider, or LLM key.

Install an immutable release

TERMINALPLAIN TEXT

openclaw plugins install git:github.com/golem-workers/sidewisp-plugin@v0.2.0 --force
openclaw plugins inspect sidewisp --runtime --json

Enroll and verify

TERMINALPLAIN TEXT

openclaw config set plugins.entries.sidewisp.config.setupToken sw_setup_REPLACE_ME
openclaw gateway restart
openclaw gateway call sidewisp.status --json

The setup token is exchanged once for a scoped installation credential and removed from active configuration. A healthy status reportsconfigured: true, installation state active, spool status healthy, uploader status idle orsent, and mode zero-llm.

Runtime surface

Surface	Value	Access
Service	`sidewisp-collector`	Background lifecycle only
Method	`sidewisp.status`	`operator.read`
Method	`sidewisp.supportBundle`	`operator.read`
Agent tools	none	Not model-visible
Model providers	none	Zero inference calls

Verify a release archive +

RELEASE VERIFICATIONPLAIN TEXT

gh release download v0.2.0 \
  --repo golem-workers/sidewisp-plugin \
  --pattern '*.tgz' \
  --pattern SHA256SUMS
sha256sum --check SHA256SUMS
gh attestation verify sidewisp-plugin-0.2.0.tgz \
  --repo golem-workers/sidewisp-plugin
openclaw plugins install ./sidewisp-plugin-0.2.0.tgz --force

PER-USER SIDECAR

Install on Hermes Agent

Hermes uses a user-owned sidecar on Linux or macOS until an equivalent stable native lifecycle is available.

Verify and unpack the release, then run the installer from its directory. Linux needs a systemd user session; macOS needs LaunchAgent support. Default installation never uses sudo.

TERMINALPLAIN TEXT

SIDEWISP_ENDPOINT=https://api.sidewisp.com \
HERMES_SOURCE_DIR="$HOME/hermes-agent" \
./scripts/install-hermes.sh sw_setup_REPLACE_ME

Validate

Check HTTPS endpoint, setup token shape, source directory, OS, and Node.js.

Exchange

Create scoped credentials before installing any background service.

Activate

Stage immutable release, switch atomically, and start user service.

Prove health

Inspect systemd or LaunchAgent state and metadata-only logs.

VERIFYPLAIN TEXT

# Linux
systemctl --user status sidewisp-hermes.service
journalctl --user -u sidewisp-hermes.service --since today

# macOS
launchctl print "gui/$(id -u)/com.sidewisp.hermes-collector"

Installed layout

Path or unit	Purpose	Expected mode
`~/.local/share/sidewisp-hermes`	Immutable releases and `current` symlink	owner only
`~/.local/state/sidewisp-hermes/sidewisp`	Credential and SQLite spool	`0700` directory; `0600` files
`sidewisp-hermes.service`	Linux systemd user service	NoNewPrivileges, private temp, read-only home
`com.sidewisp.hermes-collector`	macOS LaunchAgent	current user, no sudo

STABLE COMMAND HOOKS

Install on Codex

Codex CLI 0.145.0+, Node.js 22.22.3+, outbound HTTPS, and one setup token are required. Sidewisp observes sessions, turns, and local tool calls without reading content.

TERMINALPLAIN TEXT

codex --version
codex features list | grep '^hooks '

SIDEWISP_ENDPOINT=https://api.sidewisp.com \
./scripts/install-codex.sh sw_setup_REPLACE_ME

Merge safely

Preserve existing ~/.codex/hooks.json handlers and create a one-time backup.

Review trust

Restart Codex, open /hooks, inspect the command, and trust its exact definition.

Stage locally

Each hook atomically writes one sanitized event into an owner-only inbox.

Deliver safely

A detached zero-LLM worker spools and signs HTTPS batches without blocking Codex.

Covered hooks: SessionStart, SessionEnd,UserPromptSubmit, PreToolUse,PostToolUse, and Stop. Prompts, transcripts, assistant messages, tool arguments, and tool output are ignored. Only opaque IDs, tool name, outcome, and bounded scalar result metadata are eligible.

Hook mapping

Codex hook	Sidewisp event	Eligible metadata
`SessionStart`	`runtime.started`	Opaque session ID, runtime version
`SessionEnd`	`runtime.stopped`	Opaque session ID
`UserPromptSubmit`	`turn.started`	Opaque turn/session IDs; no prompt
`Stop`	`turn.completed`	Outcome and bounded duration
`PreToolUse`	`tool.started`	Tool name and opaque call ID
`PostToolUse`	`tool.completed / failed / timeout`	Bounded scalar status only

COMMAND HOOKS

Install on Claude Code

Claude Code 2.1.218+, Node.js 22.22.3+, outbound HTTPS, and one setup token are required. The adapter covers lifecycle, tools, permission denials, and bounded provider failures.

TERMINALPLAIN TEXT

claude --version

SIDEWISP_ENDPOINT=https://api.sidewisp.com \
./scripts/install-claude-code.sh sw_setup_REPLACE_ME

Preserve settings

Merge Sidewisp into ~/.claude/settings.json without replacing other hooks.

Observe outcomes

Map session, turn, tool, denial, and StopFailure events.

Drop content

Ignore prompt, transcript, assistant text, tool payload, and raw error fields.

Retry outages

Keep events in local SQLite until a signed batch is acknowledged.

StopFailure retains only its documented class, such asrate_limit, authentication_failed,overloaded, or max_output_tokens.error_details and last_assistant_messagenever enter telemetry.

Hook mapping

Claude Code hook	Sidewisp event	Eligible metadata
`SessionStart / SessionEnd`	`runtime.started / stopped`	Opaque session ID, runtime version
`UserPromptSubmit / Stop`	`turn.started / completed`	Opaque turn ID; no message text
`StopFailure`	`turn.failed` plus bounded failure fact	Documented failure class only
`PreToolUse / PostToolUse`	`tool.started / completed`	Tool name, call ID, duration
`PostToolUseFailure`	`tool.failed / cancelled`	Outcome and interrupt flag
`PermissionDenied`	`tool.cancelled`	Expected denial flag; no reason text

CUSTOM ADAPTER PATH

Other coding agents

Sidewisp v0.2.0 does not ship adapters for these runtimes. The setup section provides evidence-first development chains for agents with documented extension surfaces.

Documented extension surfaces

Runtime	Observed public surface	Sidewisp status	Runbook
Gemini CLI	Documented lifecycle and BeforeTool / AfterTool hooks ↗	NOT SHIPPED IN V0.2.0	Audit and build chain ↑
GitHub Copilot CLI	Documented CLI lifecycle and tool hooks ↗	NOT SHIPPED IN V0.2.0	Audit and build chain ↑
OpenCode	Typed plugin event bus ↗	NOT SHIPPED IN V0.2.0	Audit and build chain ↑
Cursor Agent	Agent lifecycle hooks ↗	NOT SHIPPED IN V0.2.0	Audit and build chain ↑
Kiro CLI	Documented lifecycle and tool hooks ↗	NOT SHIPPED IN V0.2.0	Audit and build chain ↑

Candidate hooks may expose prompts, messages, commands, tool arguments, tool output, or raw errors. A Sidewisp adapter must discard those fields before the atomic inbox and SQLite spool. Presence of hooks alone is insufficient: the exact installed runtime version, non-blocking behavior, merge semantics, and failure coverage must pass the phase-one audit.

Discovery-only runtimes

Windsurf CascadeClineRoo CodeAiderGooseQwen Code

These established agents have no Sidewisp v0.2.0 adapter and no compatibility claim here. Before implementation, verify the current official event or extension API. Do not scrape transcripts, model traffic, shell history, editor databases, or unstructured logs as a substitute for a stable lifecycle surface.

DISCOVERY PROMPTPLAIN TEXT

Read https://sidewisp.com/docs/ and Sidewisp Plugin tag v0.2.0.

For TARGET_RUNTIME, perform a read-only integration discovery:
1. Identify the exact installed version and official extension documentation.
2. List stable lifecycle, turn, tool, permission, and failure events.
3. Map safe metadata to sidewisp.telemetry.v1.
4. Mark missing capabilities DEGRADED or UNAVAILABLE.
5. Prove hooks are non-blocking and configuration changes are reversible.
6. List every content-bearing field that must be ignored.

Return evidence and source links. Do not modify the runtime, read transcripts,
install a collector, or claim Sidewisp support.

CLOSED ALLOWLIST

Privacy is structural

Only allowlisted fields survive sanitation. Unknown fields are discarded; malformed or unsafe allowlisted values are rejected before the spool.

COLLECTED

Runtime kind, version, and opaque instance ID
Lifecycle and health event type
Success, failure, degraded, or informational outcome
Opaque correlation IDs
Bounded status, code, component, and operation labels
Integer durations, exit codes, attempts, and HTTP status
Recoverable and expected flags

NEVER COLLECTED

Prompts, responses, or message content
Files, file contents, or tool input/output
API keys, tokens, passwords, or credentials
Names, emails, or personal identifiers
Raw command lines, environment values, or logs
Screen, microphone, camera, contacts, or browser data
Arbitrary JSON fields

SIDEWISP.TELEMETRY.V1

Telemetry contract

One sanitized event is one bounded fact. Consumers should validate the schema string before reading any other field.

SAFE EVENTPLAIN TEXT

{
  "schema": "sidewisp.telemetry.v1",
  "eventId": "evt_01JZQY7Q9Y6V8H4D4T6P3A",
  "installationId": "sw_ins_example123",
  "sequence": 42,
  "occurredAt": "2026-07-24T08:20:00.000Z",
  "observedAt": "2026-07-24T08:20:00.012Z",
  "runtime": {
    "kind": "openclaw",
    "name": "gateway",
    "version": "2026.7.1",
    "instanceId": "host_a1"
  },
  "source": {
    "kind": "hook",
    "adapterVersion": "0.2.0"
  },
  "type": "tool.failed",
  "outcome": "failure",
  "correlation": {
    "sessionId": "session_7",
    "turnId": "run_12",
    "toolCallId": "call_3"
  },
  "details": {
    "operation": "github",
    "code": "AUTH_FAILED",
    "durationMs": 831,
    "recoverable": false
  }
}

FieldContract

eventIdStable event identity. Use as deduplication key.

installationIdScoped collector installation identity.

sequenceNon-negative local ordering value.

occurredAt / observedAtISO timestamps for source occurrence and collection.

runtime / sourceAllowlisted adapter and origin metadata.

type / outcomeClosed event type plus info, success, failure, or degraded.

correlationOpaque session, turn, tool call, message, and parent event IDs.

detailsOnly allowlisted safe labels, integers, and booleans.

Event catalog

Runtime

runtime.startedruntime.stoppedruntime.restartedruntime.crashed

Gateway

gateway.connectedgateway.disconnected

Turns

turn.startedturn.completedturn.failedturn.timeoutturn.cancelled

Tools

tool.startedtool.completedtool.failedtool.timeouttool.cancelled

Delivery

message.receivedmessage.deliveredmessage.rejectedmessage.failed

Providers

provider.auth_failedprovider.rate_limitedprovider.unavailable

Runtime health

queue.stuckqueue.recoveredcontext.exhaustedconfig.invalidplugin.failed

Collector

health.snapshotcollector.startedcollector.stoppedcollector.degraded

Allowlisted detail fields

codereasonstatuscomponentoperationcapabilityattemptcountdurationMsexitCodehttpStatusrecoverableexpected

Collector defaults

64 MiB

Maximum local spool footprint. Owner-only directory and database permissions.

100

Maximum events per upload batch, capped at 256 KiB before compression.

1 KiB

Minimum raw batch size before transport switches to gzip compression.

5s / 30s

Upload tick and health heartbeat intervals in OpenClaw v0.2.0.

Local spool semantics

Property	Implementation	Operational effect
Database	SQLite schema v1, WAL, `synchronous=FULL`	Committed events survive process restart and ordinary host failure.
Deduplication	`events.event_id` primary key	Repeated local import is idempotent.
Writer model	Owner-token lock plus atomic command-hook inbox files	Concurrent hooks do not write SQLite directly.
Quota	64 MiB across DB, WAL, and shared-memory files	At 80% status becomes degraded; at quota it becomes unhealthy.
Retention	Acknowledged events eligible for prune after 7 days	Pending events remain until ack or explicit dead letter.
Corruption	Failed integrity check renames DB with `.corrupt-<timestamp>`	Collector starts a new spool and reports recovery state.
Forward schema	Newer spool schema rejected	Downgrade fails closed instead of modifying unknown state.

COMPATIBLE ENDPOINT

Receiver protocol

A custom endpoint must implement enrollment, HMAC verification, replay protection, batch validation, explicit acknowledgements, and idempotent storage.

POST /v1/installations/exchange

Accept one-time setupToken. Return installationId and installationSecret. Consume token once.

POST /v1/telemetry/batches

Verify installation, timestamp, nonce, and HMAC against raw body before decompression or JSON parsing.

Validate and deduplicate

Accept only known schemas and allowlisted fields. Make repeated eventId delivery harmless.

Acknowledge explicitly

Return accepted IDs and permanent per-event rejections. Unacknowledged events remain in local spool for retry.

Point OpenClaw to your receiver

TERMINALPLAIN TEXT

openclaw config set plugins.entries.sidewisp.config.endpoint https://telemetry.example.com
openclaw config set plugins.entries.sidewisp.config.setupToken sw_setup_REPLACE_ME
openclaw gateway restart

Point command-hook runtimes to your receiver

TERMINALPLAIN TEXT

# Codex
SIDEWISP_ENDPOINT=https://telemetry.example.com \
./scripts/install-codex.sh sw_setup_REPLACE_ME

# Claude Code
SIDEWISP_ENDPOINT=https://telemetry.example.com \
./scripts/install-claude-code.sh sw_setup_REPLACE_ME

A URL change alone is not enough. Receiver must implement the exchange and signed batch contracts below over HTTPS.

Enrollment

REQUEST / RESPONSEPLAIN TEXT

POST /v1/installations/exchange
Content-Type: application/json

{ "setupToken": "sw_setup_REPLACE_ME" }

200 OK
{
  "installationId": "sw_ins_example123",
  "installationSecret": "sw_secret_REPLACE_ME_WITH_RANDOM_SECRET"
}

Batch and signature

BATCH BODYPLAIN TEXT

{
  "schema": "sidewisp.telemetry-batch.v1",
  "events": [
    { "...": "sidewisp.telemetry.v1 event" }
  ]
}

SIGNATUREPLAIN TEXT

digest = SHA256(rawRequestBody)
canonical = timestamp + "\n" + nonce + "\n" + hex(digest)
signature = HMAC_SHA256(installationSecret, canonical)

Authorization: Sidewisp <installationId>:<hex(signature)>
X-Sidewisp-Algorithm: hmac-sha256-v1
X-Sidewisp-Timestamp: <unix-seconds>
X-Sidewisp-Nonce: <random-base64url>

The raw request body may be gzip-compressed and carriesContent-Encoding: gzip. Verify HMAC over those exact received bytes. Enforce a short timestamp window, reject nonce reuse, compare signatures in constant time, cap body size, and parse JSON only after authentication succeeds.

Transport limits and retry policy

Parameter	v0.2.0 default	Receiver requirement
Events per batch	100	Accept partial validity and acknowledge per event.
JSON body limit	256 KiB before compression	Set a finite raw and decompressed size limit.
Compression	gzip at 1 KiB	Verify HMAC over received compressed bytes before decompression.
Request timeout	10 seconds	Make persistence idempotent; client may retry after timeout.
Backoff	Exponential jitter, capped at 60 seconds	Return `Retry-After` on 429 when useful.
Delivery	At least once	Use `eventId` as unique idempotency key.

Partial acknowledgement

200 RESPONSEPLAIN TEXT

{
  "acknowledgedEventIds": [
    "evt_01JZQY7Q9Y6V8H4D4T6P3A"
  ],
  "rejected": [
    {
      "eventId": "evt_invalid",
      "code": "invalid-schema"
    }
  ]
}

200

Process valid events. Return accepted IDs and permanent event rejections.

401 / 403

Credential invalid or revoked. Collector reports credential-rejected.

429

Temporary rate limit. Optional Retry-After controls bounded backoff.

5xx

Temporary receiver failure. Collector retains events and retries with jitter.

COMPOSABLE BY DESIGN

Build your own stack

The plugin does not generate a dashboard. It exposes enough stable, privacy-safe structure for a developer or coding agent to build one.

Local health dashboard

Run a receiver on your own machine, keep SQLite local, and show uptime, recent failures, tool outcomes, and spool health for one agent.

Node.js · SQLite · React

Fleet operations

Group events by installation and runtime instance. Build status boards, failure timelines, duration percentiles, and crash-loop detection across many agents.

Postgres · ClickHouse · React

Alerts and routing

Route bounded failure facts to Slack, Telegram, Discord, PagerDuty, email, or a generic webhook without forwarding prompts or tool payloads.

Webhooks · Queues · Rules

Metrics and Grafana

Translate event counters, durations, provider failures, and health snapshots into Prometheus metrics and operate with your existing Grafana stack.

Prometheus · Grafana

Internal admin tools

Embed agent health into an existing operations console. Join installation IDs to your own inventory without changing the plugin contract.

Your API · Your UI · SSO

New runtime adapter

Map lifecycle facts from another runtime into the same closed schema. Keep content out, preserve stable correlation IDs, and reuse the delivery layer.

Custom runtime · Public contract

CODING-AGENT STARTER

Turn this contract into a working product.

Give the prompt to Codex, OpenClaw, Claude Code, or another capable coding agent. Add your preferred framework, storage, deployment, authentication, and alert destinations.

PROMPTPLAIN TEXT

Read https://sidewisp.com/docs/ and the Sidewisp plugin source.

Build a TypeScript receiver that:
- implements POST /v1/installations/exchange;
- verifies Sidewisp HMAC signatures before parsing telemetry;
- stores deduplicated sidewisp.telemetry.v1 events in SQLite;
- acknowledges accepted event IDs and rejects invalid events explicitly;
- exposes a read-only JSON API;
- serves a React dashboard with runtime health, event timeline, failure
  categories, tool durations, crash loops, and provider errors;
- sends failure alerts to my chosen webhook;
- never stores prompts, responses, files, credentials, identities,
  message content, or tool input/output.

Add tests for signature verification, replay rejection, duplicate delivery,
partial acknowledgement, schema validation, and privacy exclusions.

DAY-TWO OPERATIONS

Upgrade, roll back, remove

Credentials and pending telemetry live outside the package. Preserve runtime state across upgrades and verified rollbacks.

Inspect and support

TERMINALPLAIN TEXT

openclaw gateway call sidewisp.status --json
openclaw gateway call sidewisp.supportBundle --json

The support bundle excludes setup tokens, installation secrets, event payloads, prompts, responses, identities, and full endpoint paths.

Upgrade or roll back

TERMINALPLAIN TEXT

# Install verified target
openclaw plugins install git:github.com/golem-workers/sidewisp-plugin@v0.2.0 --force
openclaw gateway restart
openclaw gateway call sidewisp.status --json

# Roll back package without deleting state
openclaw plugins install git:github.com/golem-workers/sidewisp-plugin@v0.1.20 --force
openclaw gateway restart

Disable or uninstall

TERMINALPLAIN TEXT

# Disable collection, retain package and state
openclaw config set plugins.entries.sidewisp.config.enabled false
openclaw gateway restart

# Preview, then remove package
openclaw plugins uninstall sidewisp --dry-run
openclaw plugins uninstall sidewisp
openclaw gateway restart

Update or remove command-hook adapters

TERMINALPLAIN TEXT

# Update: run installer from the verified target release
./scripts/install-codex.sh
./scripts/install-claude-code.sh

# Remove only Sidewisp hook handlers
./scripts/uninstall-codex.sh
./scripts/uninstall-claude-code.sh

Reinstall uses the existing scoped credential, so a new setup token is required only after revocation or state removal. Uninstall preserves credentials, pending telemetry, releases, and unrelated runtime hooks.

awaiting setup

No active credential. Create a fresh single-use setup token, configure it, and restart.

enrollment-failed

Check outbound HTTPS, endpoint origin, token freshness, and system time.

credential-rejected

Installation may be revoked. Issue replacement enrollment from an authorized receiver.

spool degraded

Check disk capacity and ownership. Never edit SQLite while collector is running.

plugin not loaded

Inspect plugin runtime and compare Node.js/OpenClaw versions with release compatibility.

delivery retry

Check DNS, TLS, clock, receiver availability, rate limits, and response contract.

TRUST BOUNDARY

Security and license

The collector remains metadata-only, outbound-only, zero-LLM, and unable to control the observed agent.

PERMISSIONS

Least privilege

User-owned state, outbound HTTPS, detected runtime paths only. No screen, microphone, camera, browser data, or broad filesystem access.

CREDENTIALS

Scoped and local

Setup token is short-lived. Installation secret is stored owner-only and used only to sign telemetry delivery.

CONTROL

Read-only surface

OpenClaw exposes operator-read methods. Codex and Claude Code hooks emit no decisions or model-visible output. Plugin adds no agent tools or providers.

REPORTING

Private disclosure

Report vulnerabilities through GitHub private security advisories. Never attach tokens, event databases, or runtime content.

LICENSE

GNU AGPLv3 only

Plugin releases beginning with v0.2.0 useAGPL-3.0-only. Personal and commercial use, modification, and redistribution are allowed. Covered modified versions and derivative works must remain under AGPLv3, with corresponding source provided when the license requires it.

Sidewisp's hosted storage, analysis, incidents, notifications, and recovery workflows are separate managed services and are not licensed by the plugin repository.

READ LICENSE ↗REPORT A VULNERABILITY ↗

REFERENCE LINKS

Source, release, and runtime specifications

Plugin sourceImmutable v0.2.0 tree ↗Release artifactsArchive, checksum, provenance ↗Compatibility policyBaselines and rollback contract ↗Security policyThreat model and reporting ↗

Sidewisp PluginTechnical Reference

Prepare a local shell session

Completion criteria

Data path

Non-negotiable invariants

Content-free

Durable

Inspectable

Portable

Compatibility matrix

Configuration reference

Runtime coverage

OpenClaw

Hermes Agent

Codex

Claude Code

Custom runtimes

Install an immutable release

Enroll and verify

Runtime surface

Installed layout

Hook mapping

Hook mapping

Documented extension surfaces

Discovery-only runtimes

Event catalog

Runtime

Gateway

Turns

Tools

Delivery

Providers

Runtime health

Collector

Allowlisted detail fields

Collector defaults

Local spool semantics

Point OpenClaw to your receiver

Point command-hook runtimes to your receiver

Enrollment

Batch and signature

Transport limits and retry policy

Partial acknowledgement

Local health dashboard

Fleet operations

Alerts and routing

Metrics and Grafana

Internal admin tools

New runtime adapter

Turn this contract into a working product.

Inspect and support

Upgrade or roll back

Disable or uninstall

Update or remove command-hook adapters

Least privilege

Scoped and local

Read-only surface

Private disclosure

GNU AGPLv3 only

Source, release, and runtime specifications

Sidewisp Plugin
Technical Reference