agent-beacon

Beacon captures agent session history across Claude Code, Cursor, Codex, OpenCode, and 20+ other harnesses, then turns useful workflows, corrections, and debugging patterns into reusable knowledge for future agents.

A problem solved by one agent shouldn't need to be learned from scratch by another.

Beacon Overview

Beacon is an open-source memory layer for AI coding agents that learns from your work across Claude Code, Cursor, Codex, OpenCode, and 20+ other harnesses. It captures full session history, identifies useful workflows, corrections, and debugging patterns, and makes that knowledge reusable by future agents. Built for developers who want agent knowledge to compound across tools instead of disappearing when a session ends.

Key Capabilities:

• Cross-harness history - sessions from Claude Code, Cursor, Codex, OpenCode, Cline, and 20+ harnesses in one place
• Knowledge that compounds - workflows, corrections, debugging patterns, and repo conventions that survive beyond a single session
• Shared agent memory - reviewed knowledge future agents can retrieve through MCP or Agent Skills
• Exact session replay - prompts, responses, tools, commands, edits, approvals, MCP activity, and tokens in one trace
• Local-first portability - durable JSONL, explicit destinations, and no harness lock-in

🎬 Demo

https://github.com/user-attachments/assets/38995612-84e9-4989-a905-0099f77955f0

🚀 Quick Start

Beacon is open source and local-first. Interactive endpoint setup signs in through beacon.sh and preselects Beacon Cloud, with an explicit Local opt-out. Signing in forwards nothing; confirming Managed installs Beacon and connects this machine in the same command, and the confirm screen says so before you accept. Setup then ends on a short summary and opens the hosted dashboard at beacon.sh/dashboard. System, package, MDM, and CI installation paths remain noninteractive and account-free.

1. Install Beacon

Copy & paste setup prompt into your coding agent

Read https://beacon.sh/start.md then set me up on Beacon

brew update
brew trust asymptote-labs/tap
brew tap asymptote-labs/tap
brew install beacon

beacon endpoint install

Install the latest .deb or .rpm for your distribution and architecture (Debian, Ubuntu, Fedora, RHEL, Rocky, Alma):

curl -fsSL https://github.com/asymptote-labs/agent-beacon/releases/latest/download/install.sh | bash

The installer downloads the package for your architecture, verifies it against the release checksums.txt, and installs it with apt-get or dnf. Set BEACON_VERSION=<version> to install a specific release.

Prefer not to pipe a script into your shell? Either read the script before you run it:

curl -fsSLO https://github.com/asymptote-labs/agent-beacon/releases/latest/download/install.sh
less install.sh
bash install.sh

Or skip the script and run its steps yourself: pick a version, download the package and checksums.txt, verify the package, and install it with your package manager.

VERSION="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/asymptote-labs/agent-beacon/releases/latest)"; VERSION="${VERSION##*/v}"
case "$(uname -m)" in x86_64) ARCH=amd64 ;; aarch64) ARCH=arm64 ;; esac
FORMAT=deb   # or rpm for Fedora, RHEL, Rocky, Alma
PKG="beacon_${VERSION}_linux_${ARCH}.${FORMAT}"
BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/v${VERSION}"

# Download into a directory APT can read. A package in your home directory still
# installs, but APT ends with a harmless "Permission denied" notice.
DIR="$(mktemp -d /tmp/beacon-install.XXXXXXXX)" && chmod 0711 "$DIR" && cd "$DIR"
curl -fsSLO "${BASE}/${PKG}" && curl -fsSLO "${BASE}/checksums.txt" && chmod 0644 "${PKG}"
grep "  ${PKG}$" checksums.txt | sha256sum --check - && \
sudo apt install "./${PKG}"   # or: sudo dnf install "./${PKG}"

checksums.txt is published with the release, so it catches a corrupted or swapped download but does not prove who built the release. To check that, verify the package's build-provenance attestation, which shows it was built by this repository's release workflow: gh attestation verify "${PKG}" --repo asymptote-labs/agent-beacon. You can also pin VERSION to a release you have reviewed instead of following latest. To install without root, use the tarball in user mode (Linux install guide).

Download the x64 MSI from the latest release.

msiexec /i BeaconEndpointAgent-<version>-x64.msi

For silent installation:

msiexec /i BeaconEndpointAgent-<version>-x64.msi /qn

2. Use your agents normally

Open Claude Code, Cursor, Codex, or any other supported harness.

Beacon continuously captures your session history in the background

3. Explore your history

beacon traces

This opens a local terminal browser for traces, event timelines, token usage, and retained content. Nothing is sent anywhere. To use the local web view instead:

beacon endpoint dashboard

Or inspect the raw event stream:

~/.beacon/endpoint/logs/runtime.jsonl

[!NOTE] Signing in does not enable forwarding. Confirming the preselected Beacon Cloud option does: the confirm screen names the signed-in account, states that confirming installs Beacon and starts forwarding, names Asymptote Labs as the operator, the destination, and the capture mode, and connects the endpoint after the install succeeds. Choose Local to keep everything on this machine, and disconnect any time with beacon endpoint disconnect.

Whichever destination you choose, the wizard also installs the Beacon Skills into ~/.agents/skills and ~/.claude/skills unless you turn them off; redo or undo that with beacon skills install|uninstall.

If you choose Beacon Cloud, the wizard also registers Beacon Cloud MCP in your harnesses unless you turn it off, so your agents can search the forwarded history. To do it later, or for an endpoint connected another way:

beacon mcp connect

This registers the beacon-managed MCP server in Claude Code, Codex CLI, Cursor, VS Code, Gemini CLI, and OpenCode, and each harness signs in with OAuth the first time it connects. No token is written. beacon mcp disconnect removes exactly what it added. The local beacon MCP server (beacon mcp serve) is separate and never touches the network. See beacon mcp connect.

Inspect the account used during interactive setup:

beacon whoami

🧠 Turn Session History Into Memory

Every agent session contains potentially useful knowledge about your codebase.

Beacon creates a loop around that history:

Run agents
    ↓
Capture session history
    ↓
Evaluate what worked
    ↓
Extract useful knowledge
    ↓
Review + approve
    ↓
Reuse across future agents

That could be:

• the right way to run a migration
• a debugging path that finally fixed an obscure issue
• a testing convention agents repeatedly get wrong
• a repository-specific workflow
• the right sequence of internal tools
• a correction you've given multiple agents

Instead of disappearing into old sessions, that knowledge becomes reusable.

🔀 Cross-Harness by Design

Most agent memory belongs to a single harness.

B