The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
feat(skills): add session handoff workflow
akhilpotturi4e26ee4641f9
diff --git a/CLAUDE.md b/CLAUDE.mdindex 63cfaf47..ac08eb09 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -13,7 +13,7 @@ Beacon Endpoint Agent is a local-only endpoint telemetry agent for AI runtimes.- `browser-extension`: optional MV3 collector (Chrome, plus a beta Firefox build target) that relays Claude.ai and ChatGPT chat telemetry into the local pipeline as OTLP.- `pkg/asymptoteobserve`: shared Go library — event schema, harness-name normalization, provenance markers, token usage, and the threat-rules engine. Imported by the CLI, the hook adapter, and the collector exporter, so a change here reaches all three.- `plugins`: TypeScript sources for the managed runtime plugins/extensions (`opencode-beacon`, `cline-beacon`, `pi-beacon`, `omp-beacon`, `openclaw-beacon`, `prime-beacon`, `omo-beacon`), each mirrored into an embedded copy under `cli/beacon/internal/endpoint/hooks/assets/`.-- `agent-skills`: publishable Agent Skills plugin for the traces-to-memory workflow (`beacon-memory-recall`, `beacon-memory-distill`, `beacon-memory-promote`) for authoring dashboard lenses (`beacon-lens-create`), and for sharing the current session to beacon.sh (`beacon-trace-share`, which runs `beacon share --current --harness <runtime> --json`, keeps the default direct visibility and asks before public) with manifests for Claude Code, Agent Plugins (Codex, Copilot, VS Code, Kiro, Devin), Cursor, Kimi Code, and Gemini CLI. At the repo root, `.claude-plugin/marketplace.json` is read by most harnesses, `.cursor-plugin/marketplace.json` by Cursor, and `package.json` (`pi.skills` only) makes the repo a Pi/Prime Agent package; keep that root `package.json` free of dependencies and scripts. `cli/beacon/cmd/agent_skills_test.go` checks every `beacon` command and flag the skills name against the real command tree, so rename a command and update the skills together. The binary carries a copy of `agent-skills/skills` in `cli/beacon/internal/agentskills/skills` for onboarding and `beacon skills install`; a test keeps it identical, so copy it across whenever a skill changes.+- `agent-skills`: publishable Agent Skills plugin for the traces-to-memory workflow (`beacon-memory-recall`, `beacon-memory-distill`, `beacon-memory-promote`), for authoring dashboard lenses (`beacon-lens-create`), for sharing the current session to beacon.sh (`beacon-trace-share`, which runs `beacon share --current --harness <runtime> --json`, keeps the default direct visibility and asks before public), and for continuing local sessions in another runtime (`beacon-session-handoff`, which uses detached CLI launch) with manifests for Claude Code, Agent Plugins (Codex, Copilot, VS Code, Kiro, Devin), Cursor, Kimi Code, and Gemini CLI. At the repo root, `.claude-plugin/marketplace.json` is read by most harnesses, `.cursor-plugin/marketplace.json` by Cursor, and `package.json` (`pi.skills` only) makes the repo a Pi/Prime Agent package; keep that root `package.json` free of dependencies and scripts. `cli/beacon/cmd/agent_skills_test.go` checks every `beacon` command and flag the skills name against the real command tree, so rename a command and update the skills together. The binary carries a copy of `agent-skills/skills` in `cli/beacon/internal/agentskills/skills` for onboarding and `beacon skills install`; a test keeps it identical, so copy it across whenever a skill changes.- `rules` and `spec/threat-rules`: the open rule corpus and the Threat Rules format it conforms to. Every rule's `taxonomy.beacon_category` is its directory name, and the six embedded baseline rules in `pkg/asymptoteobserve/rulestore/baseline` are byte-identical copies of their corpus rules; conformance tests enforce both.- `spec/lenses`: the Lenses format — single-file HTML views of one trace that the local dashboard runs in a sandboxed, network-less frame and feeds once through `window.beacon.getTrace()`. The contract types (`LensManifestV1`, `LensDataV1`) live in `pkg/asymptoteobserve/lens.go`, and `lens_test.go` pins the spec's examples and manifest schema to them. The dashboard builds the data in `BuildLensData` (`/api/lens-data`), lists lenses at `/api/lenses`, and serves each lens at `/lenses/frame/<id>` under the spec's CSP with `lenses/prelude.js` (which defines `window.beacon`) injected ahead of it; that route is the only one that may be framed. Built-in lenses are `cli/beacon/internal/endpoint/dashboard/lenses/*.lens.html`, and `activity` is byte-identical to the spec example (a test enforces it). The session page (`static/session.html`, `initLensTabs` in `app.js`) shows lenses as tabs fed by `/api/lens-data?session=`, which projects exactly the events that page lists; it is the host half of the protocol and closes a lens that errors, stalls, or navigates its own frame. Trust model (SPEC "Trust model"): the opaque origin, sandbox and CSP keep a lens from touching Beacon or the dashboard and block ordinary network APIs, but cannot fully prevent a lens from sending trace data out through browser features no CSP governs (WebRTC, resource hints, speculative loading), so an installed lens is code the person trusts with the trace data it is shown; never describe the sandbox as making exfiltration impossible. `prelude.js` removes the `RTC*` globals and guards the document (refuses creating, inserting or parsing in nested frames, `<link>` elements and `<script type=speculationrules>`, parsing markup in the real call's document and context and inserting exactly the checked nodes so `<noscript>`/foreign-content parser differentials cannot slip through, refuses `document.write` and `execCommand("insertHTML")`, and a mutation observer removes those from the file's own markup); that is best-effort hardening, not a boundary, and the hostile `probe` fixture in `testdata/lens-e2e` pins each covered path. Installed lenses live in the lens store (`cli/beacon/internal/endpoint/lensstore`, `<BaseDir>/lenses/<id>.lens.html`, 0600 under 0700), written only by `beacon lenses add|remove` (`cli/beacon/cmd/lenses.go`; `add` prints the trust warning and confirms on a TTY, and refuses without one or in CI unless `--yes`); the dashboard rescans it per request and never writes it, and a store lens can never shadow a built-in. `asymptoteobserve.CheckLensFile` is the one file check every installer, server and linter uses. User docs are `docs/concepts/lenses.mdx` and `docs/cli/lenses.mdx`; keep them in sync with the commands and built-in lenses. The authoring loop is `beacon lenses spec` (the spec carried in the binary as `dashboard/lenses/SPEC.md`, kept byte-identical to `spec/lenses/SPEC.md` by a test), `beacon lenses data` (the exact `LensDataV1` for a session), `beacon lenses lint` (`lensstore.Lint`; built-ins must lint clean) and `beacon lenses preview` (the dashboard with `Options.LensFiles`, re-read per reload).- `beacon-sandbox`: harness that runs a real Claude Code session in a disposable sandbox and checks what Beacon captured. See `beacon-sandbox/AGENTS.md`.diff --git a/agent-skills/README.md b/agent-skills/README.mdindex b7c56b9b..7b1ba572 100644--- a/agent-skills/README.md+++ b/agent-skills/README.md@@ -1,7 +1,8 @@-# Beacon memory skills+# Beacon Agent Skills-Agent Skills that turn Beacon's cross-harness traces into reviewed project memory, and-bring that memory back to any agent in any harness.+Agent Skills that turn Beacon's cross-harness traces into reviewed project memory, bring that+memory back to any agent in any harness, create dashboard lenses, share traces, and continue+sessions in another runtime.| Skill | What it does | Network ||-------|--------------|---------|@@ -10,6 +11,7 @@ bring that memory back to any agent in any harness.| `beacon-memory-promote` | Install an approved memory as `.agents/skills/<slug>/SKILL.md` so harnesses load it automatically. | None || `beacon-lens-create` | Build, lint, preview and install a lens for the local Beacon dashboard. | None || `beacon-trace-share` | Share the current session as a trace on beacon.sh (`beacon share --current`) and post the link; direct by default, asks before public. | Uploads the session, on request |+| `beacon-session-handoff` | Continue a selected local agent session in another supported runtime using Beacon's detached CLI launch. | None |Every skill needs the [Beacon CLI](https://docs.beacon.sh/get-started/overview) with endpointcapture installed. The plugin also registers the local `beacon mcp serve` server fordiff --git a/agent-skills/skills/beacon-session-handoff/SKILL.md b/agent-skills/skills/beacon-session-handoff/SKILL.mdnew file mode 100644index 00000000..e4a56f10--- /dev/null+++ b/agent-skills/skills/beacon-session-handoff/SKILL.md@@ -0,0 +1,45 @@+---+name: beacon-session-handoff+description: Continue the user's current or selected local agent session in another supported runtime using Beacon. Use when the user asks to hand off, transfer, continue, or reopen work in Claude Code, Codex, Copilot CLI, Cursor, or another Beacon-supported harness.+license: MIT+compatibility: Requires the Beacon CLI.+metadata:+ author: asymptote-labs+ version: "0.1.0"+---++# Beacon session handoff++Use Beacon to transfer local session context without copying the conversation into a command line.+The destination starts independently in a new terminal or a resumable tmux session.++## Workflow++1. If the user did not provide a session ID, inspect sessions with:++ ```bash+ beacon handoff list --here+ ```++ Keep the default directory scope unless the user asks to search elsewhere. If more than one+ plausible session is returned, ask the user which one to continue.+2. Resolve the destination from the user's request. Do not invent a destination runtime.+3. After identifying an unambiguous session and destination, launch it with:++ ```bash+ beacon handoff resume <session-id> --agent <runtime> --launch auto --yes+ ```++ `--launch auto` opens another terminal in the calling cmux workspace or a new terminal on macOS,+ Windows, or a Linux desktop. In SSH and headless Linux environments it creates a detached tmux+ session and prints the attach command. If automatic launch cannot find a safe terminal surface,+ report the error and use:++ ```bash+ beacon handoff resume <session-id> --agent <runtime> --print+ ```+4. Report the returned terminal launcher or tmux attach command. Do not claim success when the+ command returns an error.++Do not run the destination agent directly inside the current harness's non-TTY command tool. Do+not add flags or environment variables that disable the destination runtime's approval prompts.diff --git a/cli/beacon/internal/agentskills/skills/beacon-session-handoff/SKILL.md b/cli/beacon/internal/agentskills/skills/beacon-session-handoff/SKILL.mdnew file mode 100644index 00000000..e4a56f10--- /dev/null+++ b/cli/beacon/internal/agentskills/skills/beacon-session-handoff/SKILL.md@@ -0,0 +1,45 @@+---+name: beacon-session-handoff+description: Continue the user's current or selected local agent session in another supported runtime using Beacon. Use when the user asks to hand off, transfer, continue, or reopen work in Claude Code, Codex, Copilot CLI, Cursor, or another Beacon-supported harness.+license: MIT+compatibility: Requires the Beacon CLI.+metadata:+ author: asymptote-labs+ version: "0.1.0"+---++# Beacon session handoff++Use Beacon to transfer local session context without copying the conversation into a command line.+The destination starts independently in a new terminal or a resumable tmux session.++## Workflow++1. If the user did not provide a session ID, inspect sessions with:++ ```bash+ beacon handoff list --here+ ```++ Keep the default directory scope unless the user asks to search elsewhere. If more than one+ plausible session is returned, ask the user which one to continue.+2. Resolve the destination from the user's request. Do not invent a destination runtime.+3. After identifying an unambiguous session and destination, launch it with:++ ```bash+ beacon handoff resume <session-id> --agent <runtime> --launch auto --yes+ ```++ `--launch auto` opens another terminal in the calling cmux workspace or a new terminal on macOS,+ Windows, or a Linux desktop. In SSH and headless Linux environments it creates a detached tmux+ session and prints the attach command. If automatic launch cannot find a safe terminal surface,+ report the error and use:++ ```bash+ beacon handoff resume <session-id> --agent <runtime> --print+ ```+4. Report the returned terminal launcher or tmux attach command. Do not claim success when the+ command returns an error.++Do not run the destination agent directly inside the current harness's non-TTY command tool. Do+not add flags or environment variables that disable the destination runtime's approval prompts.diff --git a/docs/cli/skills.mdx b/docs/cli/skills.mdxindex 518589bd..7d0d92cf 100644--- a/docs/cli/skills.mdx+++ b/docs/cli/skills.mdx@@ -17,7 +17,9 @@ beacon skills uninstallThe interactive [`beacon endpoint install`](/cli/endpoint-onboarding#agent-tools) runs`beacon skills install` for you unless you turn the Beacon agent skills off in the wizard.-The skills are `beacon-memory-recall`, `beacon-memory-distill`, `beacon-memory-promote`, `beacon-lens-create` and `beacon-trace-share`; [Beacon Skills](/concepts/beacon-skills) describes each.+The skills are `beacon-memory-recall`, `beacon-memory-distill`, `beacon-memory-promote`,+`beacon-lens-create`, `beacon-trace-share` and `beacon-session-handoff`;+[Beacon Skills](/concepts/beacon-skills) describes each.The skills are carried in the `beacon` binary, so installing them needs no network. They go to:diff --git a/docs/concepts/beacon-skills.mdx b/docs/concepts/beacon-skills.mdxindex f99e8519..60ce3850 100644--- a/docs/concepts/beacon-skills.mdx+++ b/docs/concepts/beacon-skills.mdx@@ -1,6 +1,6 @@---title: "Beacon Skills"-description: "Install Agent Skills that turn Beacon traces into reviewed project memory in any harness"+description: "Install Agent Skills for Beacon memory, lenses, sharing and session handoff"---## Overview@@ -10,7 +10,8 @@ harness run Beacon's [cross-harness memory](/concepts/cross-harness-memory) loopagent working in Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, or anothersupported harness can use them to recall what earlier sessions learned about arepository. It can also turn a recent session into a reviewed lesson, and promote that-lesson into a skill the whole team loads.+lesson into a skill the whole team loads. Other Beacon Skills build local dashboard+lenses, share traces and continue a local session in another runtime.The skills do not replace Beacon's capture or review model. They tell the agent which`beacon` commands to run and when to stop and ask. They keep the person reviewing in@@ -23,6 +24,7 @@ control of every write to memory.| `beacon-memory-promote` | Installs an approved memory as a project Agent Skill | None locally; Beacon Cloud MCP for memory approved there || `beacon-lens-create` | Builds a [lens](/concepts/lenses) for the local dashboard: reads the spec, inspects real trace data, writes, lints and previews the file with the user, then installs it | None || `beacon-trace-share` | Shares the current session as a trace on beacon.sh with [`beacon share --current`](/cli/share#sharing-this-session) and posts the link. Direct (link-only) by default, asks before public | Uploads the session to beacon.sh, only when you ask |+| `beacon-session-handoff` | Finds a local session and continues it in another supported runtime through [`beacon handoff`](/cli/handoff), using a detached terminal when the calling agent has no TTY | None |## Requirements@@ -86,8 +88,8 @@ installs add the skills only, and recall falls back to `beacon memory list`.In Claude Code the skills appear as `/beacon:beacon-memory-recall`,`/beacon:beacon-memory-distill`, `/beacon:beacon-memory-promote`, `/beacon:beacon-lens-create`,-and `/beacon:beacon-trace-share`. Every harness also-loads them on its own when a request matches.+`/beacon:beacon-trace-share` and `/beacon:beacon-session-handoff`. Every harness also loads them+on its own when a request matches.## Using the skills@@ -130,6 +132,12 @@ when your request matches.found it lists candidates with `beacon share --list`, and when you are not signed in it asksyou to run `beacon login` yourself.</Step>+ <Step title="Continue a session in another runtime">+ Ask to "handoff this session to Codex" or name another supported runtime.+ `beacon-session-handoff` lists local sessions when needed, resolves the requested destination+ and runs `beacon handoff resume` with detached launch so the interactive runtime receives a+ real terminal instead of inheriting the calling agent's non-TTY command subprocess.+ </Step></Steps>## Why the agent writes the lesson