Skip to main content
The beacon-trace-share skill is one of the Beacon Skills. Install it once, and you can ask the agent you are working with to “share this session”. The agent runs beacon share --current from its own shell, then replies with the link.

​
Install the skill

The interactive beacon endpoint install installs the Beacon Skills for every project unless you turn them off in the wizard. To install them at any other time:
This writes the skills to ~/.agents/skills, which Codex CLI, Gemini CLI, OpenCode, Pi and other runtimes read, and to ~/.claude/skills when Claude Code is set up. They are carried in the beacon binary, so installing needs no network. The skills also install as a plugin from the asymptote-labs/agent-beacon repository, for example in Claude Code:
Beacon Skills lists the install command for every other runtime.

​
Sign in

The agent shares with your credential, so sign in once in your own terminal:
The agent never runs beacon login itself, because it opens a browser. In CI or another headless environment, set a Beacon API key in BEACON_API_KEY instead (see Sharing via API Key). Never paste a key into the conversation.

​
Share from chat

Ask in your own words:
The skill tells the agent to:
  1. Check that beacon is on PATH, and stop if it is not.
  2. Run beacon share --current --harness <its runtime> --json from the session’s working directory. Naming its runtime keeps Beacon from picking another runtime’s session in the same directory.
  3. Reply with the link, its visibility and how many events the trace holds. When Beacon picked the most recent session in the directory rather than one it knew was this one, the agent says which session it shared.
New traces are direct (anyone with the link). The agent uses private when you ask for it, and asks you to confirm before it makes a session public. Asked to update a trace, it runs beacon share refresh, which uploads only the steps added since the last upload. To see what would be uploaded first, ask the agent to run the share with --print.

​
How the agent finds its own session

An agent does not know its session id. beacon share --current finds it from, in order:
  1. BEACON_SESSION_ID and BEACON_HARNESS, which Beacon’s Claude Code SessionStart hook exports into every shell command the session runs.
  2. The session Beacon’s hooks last saw for that runtime in this directory.
  3. The most recent session in this directory.
See Sharing this session for how conflicts are resolved.

​
Remove the skill

This removes only the copies Beacon installed. If you installed the plugin from a marketplace, uninstall it there.

Beacon Skills

Every Beacon skill and how to install it in each runtime.

Sharing via Agent Hooks

Share every new session automatically instead.