Index of every page on this site: llms.txt
All skills
openclaw avatar

/beam

@0a5ba4b
by openclawopenclaw/agent-skills1.1k stars
126
Run it yourself

Share a redacted coding session or hand its logical conversation to an authenticated OpenClaw Gateway.

Use this Skill: https://skilld.dev/gh/openclaw/agent-skills/beam

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

README.md

≈3.1k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Beam

Beam publishes a sanitized local Claude Code or Codex session to an authenticated OpenClaw Gateway. The Gateway shows the result in its existing external-session viewer; it never gains access to the source machine's filesystem, terminal, tools, credentials, or node runtime.

How it works

The beam helper is self-contained. It does not require agent-transcript, session-viewer, an SDK, or another installed skill.

  1. It resolves one exact transcript:
    • Claude Code: ${CLAUDE_CONFIG_DIR:-~/.claude}/projects/**/<session-id>.jsonl
    • Codex: ${CODEX_HOME:-~/.codex}/{sessions,archived_sessions}/**/*.jsonl, verified against session_meta.payload.id
    • lifecycle hooks: their exact transcript_path
    • explicit use: --session <file>
  2. It reads a bounded transcript window and recognizes visible Claude Code and Codex messages, including modern Codex item_completed records.
  3. It drops system/developer setup, reasoning, raw tool inputs/outputs, browser state, and unknown records. Images, pasted screenshots and files delivered with SendUserFile become [Beam asset omitted: …] placeholders (type and size only; no bytes, paths or URLs), so Team readers know an asset existed. Tool activity becomes aggregate family counts such as 2 read, 1 execute.
  4. It strips internal hook wrappers and redacts credentials, auth headers, private keys, email addresses, phone numbers (calendar dates such as 2026.12.06 stay readable), secret query parameters, and broad local paths.
  5. It uploads a closed, size-bounded JSON payload. The receiver exposes a passive transcript projection, not remote access to the local coding session.

Beam refuses fuzzy discovery. If an exact session cannot be resolved or multiple exact candidates exist, publication stops without choosing the newest nearby session. Discovery permits up to 20,000 JSONL files across the native roots; non-session files and empty directories do not consume that budget. Reads retry short filesystem results and stop publication on unexpected EOF, so an incomplete read cannot be uploaded as a complete snapshot.

Install

Install only Beam from the canonical skills checkout:

scripts/install-skills beam

A copied installation is also standalone:

scripts/install-skills --mode copy --target ~/.agents/skills beam

Publish (hands off by default)

beam publish hands the conversation to Team by default. Add --snapshot for a read-only share. Receivers without handoff support return a snapshot; the helper says so on stderr and keeps the source active. Lifecycle hooks always publish snapshots.

Set the installed skill directory and receiver endpoint:

export BEAM_SKILL_DIR="${AGENTS_HOME:-$HOME/.agents}/skills/beam"
export BEAM_ENDPOINT="https://gateway.example.com/api/v1/beam/sessions"

Claude Code:

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

Codex:

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

On success, Beam prints the endpoint-derived Control UI URL in its short share form, for example:

Beamed session: https://gateway.example.com/beam/fix-upload-flow-0123456789ab

When a receiver returns canView: false, the upload still succeeded, but Beam instead prints:

Beam upload succeeded: https://gateway.example.com/beam/fix-upload-flow-0123456789ab
This link is for authorized Team operators; upload-only access does not let you open it.

Share that link with the authorized Team operator for the handoff; do not promise the guest can view it. Staff and older receipts may omit canView; the helper preserves their existing output without treating omission as a new access grant.

A Gateway mounted below a base path returns that same base path, such as https://gateway.example.com/openclaw/beam/fix-upload-flow-0123456789ab.

The Gateway builds the optional title slug from the redacted --title value or the first shared user message. It contains up to 48 lowercase alphanumeric characters and hyphens. The final 12–32 lowercase hex characters identify the session independently of its title, so earlier named links still work after a rename. Bare /beam/<id-prefix> links remain accepted.

Explicit transcript:

node "$BEAM_SKILL_DIR/scripts/beam" publish \
  --endpoint "$BEAM_ENDPOINT" \
  --session /path/to/session.jsonl \
  --title "Fix upload flow"

Inspect the exact sanitized payload without networking:

node "$BEAM_SKILL_DIR/scripts/beam" publish \
  --endpoint http://127.0.0.1:9/api/v1/beam/sessions \
  --session /path/to/session.jsonl \
  --dry-run --quiet

Authentication

Personal guest access

Restricted guest uploads require receiver-side support and explicit operator authorization. This sender support does not announce deployed guest access. Once enabled, guests use their existing personal Cloudflare Access sign-in or a personal application token:

export BEAM_ACCESS_TOKEN="..."

For an interactive snapshot, Beam can ask the installed cloudflared CLI for an application token, using a cached sign-in or opening browser login when needed. Browser authentication stays between Cloudflare and the configured identity provider; Beam does not receive a GitHub token. Use only the receiver endpoint provided by the authorized operator.

Guests need no shared secret. Do not distribute or request a shared Gateway token, password, or another person's Access token for guest uploads. Current Visitor-enabled receivers let active verified publishers create, refresh, list, and read their own snapshots. These routes grant no access to other publishers' snapshots or permission to delete them. Updated receivers permit authorized continuation of an explicitly released owned Beam, using normal destination permissions. Older upload-only receivers can return canView: false; honor that restriction.

Expired Access credentials can cause authentication failure. Sign in again outside hooks (for example, cloudflared access login https://gateway.example.com for the configured application), or replace the expired personal BEAM_ACCESS_TOKEN. If access was revoked, reauthentication does not restore permission: an authorized operator must restore it. Do not work around a denial with a shared Gateway token. Beam does not automatically retry uploads. After a timeout or uncertain response, ask the operator to confirm receipt before trying again.

Ordinary operator access

Existing Gateway token or password authentication remains available to operators:

export BEAM_AUTH_TOKEN="..."

BEAM_ACCESS_TOKEN takes precedence over BEAM_AUTH_TOKEN. The bearer fallback is not a guest onboarding mechanism.

Lifecycle hooks never start interactive authentication. Configure one of the appropriate personal/operator token variables before enabling live hooks; expired or revoked access yields a concise error rather than browser login inside a hook.

Live updates

Beam accepts the snake_case JSON emitted on stdin by root Claude Code and Codex Stop hooks, plus Claude Code SessionEnd hooks. Subagent hooks are ignored:

node "$BEAM_SKILL_DIR/scripts/beam" hook \
  --endpoint "$BEAM_ENDPOINT" \
  --quiet

Templates:

Stop refreshes the snapshot after a completed root turn. Claude Code SessionEnd marks it complete. Codex users can publish a final snapshot with publish --snapshot --complete; the public Codex template intentionally does not claim an automatic completion hook. Hook failures exit nonzero but do not emit a blocking hook decision.

Receiver contract

The OpenClaw Beam plugin accepts POST /api/v1/beam/sessions. Ordinary Gateway HTTP-authenticated uploads require operator.write or operator.admin. Every operator.read client on that Gateway can view the catalog, so a separate Gateway remains the isolation boundary between teams. Restricted personal guest access requires receiver-side support and an active verified Visitor identity. It grants no operator.read scope or shared-catalog access. Separate publisher-bound routes allow listing and reading only that publisher's snapshots. They recheck current authority and ownership before returning data. Guests cannot delete snapshots; continuing an owned, released Beam still requires normal destination creation, session and model access.

The request remains version 1. The normal receipt remains { "ok": true, "beamId": "...", "url": "..." }. Current guest receipts add "canView": true for owned-snapshot viewing. Older upload-only receivers can return "canView": false. Staff and older receivers may omit canView; if present it must be a boolean. The receipt is not a credential or an access grant. Viewing still requires current publisher authority and snapshot ownership. The same origin, endpoint-derived base path, and Beam ID URL checks apply whether or not the publisher can view the result.

The receiver rejects transcript item text longer than 6,000 characters. Accordingly, explicit --entry-max-chars values above 6,000 fail locally before upload.

Live logical conversation handoff

A snapshot is read-only until its original verified publisher releases it with beam publish (the default) or beam handoff. The helper freezes sanitized source history and durably retires that Beam identity before network dispatch. It records the receiver-issued publication generation, then sends an existing-only release. A retry cannot create another incarnation after snapshot expiry. An uncertain release keeps the source retired; recover with handoff --beam-id ID at the same endpoint.

The first authorized continuation creates one Team conversation and imports the frozen history once. Later Team and source Beam continuations use that same conversation. beam read observes Team history; with no destination yet it reports a pending handoff and creates nothing. beam continue --message TEXT uses the operator's existing normal OpenClaw remote profile, returns the normal run acknowledgment, and exposes a request ID before dispatch. After a lost response, retry the same message with --request-id ID rather than creating another turn.

Read and continue require --profile-dir DIR pointing at the user's existing gateway.mode=remote profile for this exact endpoint. Requests preserve configured authentication and use the CLI's destination guard. Revoked access, a deleted or reset destination, and a changed Gateway stop the operation. No provider account, credential, source access or native runtime session ID transfers.

Source model metadata comes from the native transcript when present. The Gateway normalizes model/version aliases against its available permitted catalog; an unavailable preference leaves ordinary configured-default resolution in charge. Original local harness processes are not stopped or controlled. Independent local turns after release are not canonical Team turns, and late snapshot uploads are rejected without changing history or refreshing retention.

Requires Node 22.13+ for handoff state. The local SQLite store defaults to .local/state/openclaw-beam/handoffs.sqlite under the user's home; --state FILE or BEAM_STATE selects an explicit store. It holds sanitized pending history until acknowledgment, then only ownership and destination metadata. Do not delete pending or acknowledged retirement state to recover a source. Receiver ownership metadata survives snapshot expiry and archive without retaining transcript items. Ownerless/shared-token snapshots cannot be claimed: use the original publisher's verified identity.

See the handoff commands for usage and scope.

For rollout compatibility, the helper also accepts the current server's exact /chat/<agent>?catalog=beam&host=gateway&thread=<full-beam-id> URL. This is a narrow transition path: the obsolete ?session=catalog:... beta URL remains rejected.

OpenClaw plugin documentation: https://docs.openclaw.ai/plugins/beam

Development

node --check skills/beam/scripts/beam
node --check skills/beam/scripts/beam-session.js
node --check skills/beam/scripts/beam-handoff.js
node --test skills/beam/scripts/beam.test.mjs skills/beam/scripts/beam-handoff.test.mjs
python scripts/validate-skills

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert7d3 checks · Risk SAFE
  • Gen Agent Trust Hub7d

    This skill provides a utility to share sanitized local coding session transcripts with a remote OpenClaw Gateway. While it handles sensitive data and invokes external commands, it includes robust redaction logic and is designed as an official vendor tool.

  • Socket7d

    1 alert: gptAnomaly

  • Snyk7d

    Risk: CRITICAL · 2 issues

Signed by skilld at 0a5ba4b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last week

README badge

README badge for openclaw/agent-skills/beam