/beam

name: beam
description: "Share a redacted coding session or hand its logical conversation to an authenticated OpenClaw Gateway."

Beam

Use when the user explicitly asks to beam, publish, or share the current local coding session with an authenticated OpenClaw receiver.

Contract

• Treat invoking this skill as approval for one snapshot upload to the named destination.
• Never upload raw JSONL, reasoning, system/developer prompts, tool output, environment values, credentials, browser state, cookies, or local paths.
• The helper is self-contained: it resolves and parses exact Claude Code or Codex transcripts, then uploads only locally redacted user/assistant messages and compact tool counts.
• Ordinary publishing shares a read-only snapshot. A separately requested `handoff` releases the source Beam identity and moves its logical conversation to Team. After handoff, use Beam's authenticated `read` and `continue` commands for subsequent work; do not resume independent source work or publish another transcript copy.
• Team owns one durable conversation after release. The source history imports once; reads, reconnects and continuations resolve that same conversation. Native provider runtime IDs need not survive. Do not connect a node, expose a terminal, transfer credentials or grant filesystem/tool access.
• Require HTTPS except for loopback development endpoints.
• Guests use their existing personal Cloudflare Access sign-in or `BEAM_ACCESS_TOKEN`; never request, share, or copy a Gateway token for guest uploads. `BEAM_AUTH_TOKEN` remains the ordinary operator Gateway-auth fallback, not a guest credential. Never print token values.
• Live synchronization is opt-in persistent behavior. Do not install hooks unless the user explicitly asks for live Beam updates.

Snapshot

Set or obtain the destination receiver URL first:

export BEAM_ENDPOINT="https://gateway.example.com/api/v1/beam/sessions"

Prefer the harness-specific exact identifier. Resolve the directory containing this `SKILL.md` as `BEAM_SKILL_DIR` first.

Claude Code exposes the current session id:

node "$BEAM_SKILL_DIR/scripts/beam" publish \
  --endpoint "$BEAM_ENDPOINT" \
  --session-id "${CLAUDE_SESSION_ID}"

In Codex, resolve the directory containing this `SKILL.md` as `BEAM_SKILL_DIR`; normal shell-tool children expose the current thread id:

node "$BEAM_SKILL_DIR/scripts/beam" publish \
  --endpoint "$BEAM_ENDPOINT" \
  --thread-id "$CODEX_THREAD_ID"

Prefer exact harness metadata when available:

• Claude Code: `${CLAUDE_SESSION_ID}` identifies the current local conversation; the helper finds its transcript.
• Codex shell tools: `CODEX_THREAD_ID` identifies the current thread.
• Hook adapters: pass their JSON to `beam hook`; `transcript_path` is authoritative.
• Exact fallback: Beam scans only the native Claude/Codex session roots for the supplied id and fails closed on no match or ambiguity.

Useful options:

node "$BEAM_SKILL_DIR/scripts/beam" publish --endpoint "$BEAM_ENDPOINT" --session /path/to/session.jsonl
node "$BEAM_SKILL_DIR/scripts/beam" publish --endpoint "$BEAM_ENDPOINT" --thread-id "$CODEX_THREAD_ID"
node "$BEAM_SKILL_DIR/scripts/beam" publish --endpoint "$BEAM_ENDPOINT" --title "Fix upload flow"
node "$BEAM_SKILL_DIR/scripts/beam" publish --endpoint "$BEAM_ENDPOINT" --complete
node "$BEAM_SKILL_DIR/scripts/beam" publish --endpoint "$BEAM_ENDPOINT" --dry-run

`--dry-run` prints the sanitized payload locally and performs no network request.

On success, return only the Beam URL and a short disclosure summary: source harness, shared message count, whether older entries were truncated, and whether the beam is complete. The URL uses the endpoint-derived Control UI base path followed by `/beam/<title-slug>-<id-prefix>`, for example `https://gateway.example.com/beam/fix-upload-flow-0123456789ab`. The title comes from `--title` or the first shared user message. The stable ID suffix identifies the session; links with an earlier title remain valid.

If the receipt includes `canView: false`, say that the upload succeeded and the link is for authorized Team operators; upload-only access does not let the guest open it. Do not present it as a guest-viewable link. Staff and older receipts may omit `canView`; omission is not a new access grant.

Guest access requires receiver-side support and operator authorization. Sender support alone does not mean it is deployed. Current Visitor-enabled receivers let active verified publishers create, refresh, list, and read only their own snapshots. They grant no shared-catalog access or deletion. Updated receivers allow authorized continuation of a publisher's own explicitly released Beam, subject to normal destination creation, model, account and session permissions. Older upload-only receivers can return `canView: false`; honor that receipt. Guests need no shared secret. If personal access expires, sign in again outside hooks or refresh the personal `BEAM_ACCESS_TOKEN`. Revoked access needs an authorized operator to restore it. Never blindly retry an uncertain upload.

Live logical handoff

Only perform this when the user asks to move or continue the conversation in Team; permission to share a snapshot alone is insufficient. Requires Node 22.13+ and an updated receiver.

node "$BEAM_SKILL_DIR/scripts/beam" handoff --endpoint "$BEAM_ENDPOINT" --thread-id "$CODEX_THREAD_ID"
node "$BEAM_SKILL_DIR/scripts/beam" read --endpoint "$BEAM_ENDPOINT" --beam-id BEAM_ID --profile-dir /path/to/own/remote-profile
node "$BEAM_SKILL_DIR/scripts/beam" continue --endpoint "$BEAM_ENDPOINT" --beam-id BEAM_ID --profile-dir /path/to/own/remote-profile --message "Continue the work"

Use `--session-id` for Claude Code. The handoff receipt prints `BEAM_ID`. `--profile-dir` selects an existing normal OpenClaw remote profile for that exact Gateway; configure your own authentication first. No shared account or provider token is requested or