---
name: beam
description: "Share a redacted coding session or hand its logical conversation to an authenticated OpenClaw Gateway."
title: beam
canonical_url: https://skilld.dev/gh/openclaw/agent-skills/beam
last_updated: 2026-11-14T01:21:28.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [package.json](https://skilld.dev/api/skills-raw/openclaw/agent-skills/beam/package.json), [README.md](https://skilld.dev/api/skills-raw/openclaw/agent-skills/beam/README.md), [references/claude-code-hooks.json](https://skilld.dev/api/skills-raw/openclaw/agent-skills/beam/references/claude-code-hooks.json), [references/codex-hooks.toml](https://skilld.dev/api/skills-raw/openclaw/agent-skills/beam/references/codex-hooks.toml), [scripts/beam](https://skilld.dev/api/skills-raw/openclaw/agent-skills/beam/scripts/beam), [scripts/beam-handoff.js](https://skilld.dev/api/skills-raw/openclaw/agent-skills/beam/scripts/beam-handoff.js), [scripts/beam-handoff.test.mjs](https://skilld.dev/api/skills-raw/openclaw/agent-skills/beam/scripts/beam-handoff.test.mjs), [scripts/beam-session.js](https://skilld.dev/api/skills-raw/openclaw/agent-skills/beam/scripts/beam-session.js), [scripts/beam.test.mjs](https://skilld.dev/api/skills-raw/openclaw/agent-skills/beam/scripts/beam.test.mjs).
>
> If the user asked to install this Skill, run `npx skilld install openclaw/agent-skills/beam`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/beam`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/openclaw/agent-skills/beam) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/beam`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/beam --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/beam --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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 to hand the current conversation to the named destination. `publish` hands off by default; pass `--snapshot` only when the user asks for a read-only share (or for `--complete` snapshots).
- 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.
- A handoff releases the source Beam identity and moves its logical conversation to Team; receivers without handoff support get a read-only snapshot and the source stays active. 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.
- Beam carries text only. Images, pasted screenshots and delivered files (`SendUserFile`) become `[Beam asset omitted: …]` placeholders with type and size, never bytes, paths or URLs. The receiver caps a request at about 56 KB and 6,000 characters per item. When the conversation's point is a large asset (video, deck, build output), tell the user it will be omitted and offer to share it separately, or ask first if the beam is useless without it.
- Live synchronization is opt-in persistent behavior. Do not install hooks unless the user explicitly asks for live Beam updates.

## Publish (handoff by default)

Set or obtain the destination receiver URL first:

```bash
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:

```bash
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:

```bash
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:

```bash
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" --snapshot
node "$BEAM_SKILL_DIR/scripts/beam" publish --endpoint "$BEAM_ENDPOINT" --snapshot --complete
node "$BEAM_SKILL_DIR/scripts/beam" publish --endpoint "$BEAM_ENDPOINT" --dry-run
```

`--dry-run` prints the sanitized payload locally, performs no network request and changes no ownership. `BEAM_STATE` (or `--state FILE`) selects the local handoff store; tests and sandboxes must point it at a temporary file.

On success, return only the Beam URL and a short disclosure summary: source harness, shared message count, whether older entries were truncated, whether it was handed off or shared as a snapshot, and which assets were omitted. 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

`publish` performs this by default; `handoff` is the explicit form and the recovery entry point (`--beam-id`). Requires Node 22.13+ and an updated receiver; older receivers fall back to a snapshot without retiring the source.

```sh
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 copied. Permission or runtime denial stays a denial.

The helper durably retires this source identity before network dispatch. A pending handoff stays retired after errors; recover with `handoff --endpoint "$BEAM_ENDPOINT" --beam-id BEAM_ID`, including when the source transcript is gone. Never delete the retirement record to retry. Snapshot expiry or archive cannot restore source ownership. A `read` with no destination returns a visible pending result and creates nothing; `continue` creates the destination once. Deleted or reset destinations require reconciliation, not a new transcript copy.

Source model/version metadata is normalized against models available and permitted at Team. If unavailable, the destination's configured default resolves normally; authentication/setup requirements remain in force. The original local harness is not stopped or remotely controlled. Local turns after handoff are not canonical Team turns.

Continuation returns the Gateway's normal run acknowledgment. Keep the printed request ID: after an uncertain send, retry the same message with `--request-id ID` to avoid a duplicate turn. `read` obtains the current Team history. The local SQLite record contains only sanitized pending history and ownership metadata; acknowledged history is discarded locally. Default location: the user's `.local/state/openclaw-beam/handoffs.sqlite`; `--state FILE` selects an explicit local store. Preserve it while the handed-off identity can be used.

The helper also accepts bare `/beam/<id-prefix>` links and, during rollout, the current server's exact `/chat/<agent>?catalog=beam&host=gateway&thread=<full-beam-id>` response. It still rejects the obsolete `?session=catalog:...` beta form.

## Live Hooks

The helper accepts the snake_case JSON emitted by both Claude Code and Codex lifecycle hooks:

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

Configure root `Stop` hooks for turn-by-turn updates. Claude Code can also use `SessionEnd` for finalization; Codex finalization uses an explicit `publish --snapshot --complete`. See:

- `references/claude-code-hooks.json`
- `references/codex-hooks.toml`

Hook failures must not block the coding session. Keep ordinary success quiet (including upload-only receipts); a retired Beam emits a concise direction to read/continue through Team even with `--quiet`. Log one concise redacted error on failure. Hooks never start interactive authentication or automatically hand off ownership.

Full installation, authentication, data-boundary, and hook documentation:
[`README.md`](https://skilld.dev/api/skills-raw/openclaw/agent-skills/beam/README.md).

## Development

```bash
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
scripts/validate-skills
```
