<h1 align="center">Self‑improving memory for coding agents</h1>

<a href="https://beacon.sh">Website</a> · <a href="https://docs.beacon.sh">Docs</a> · <a href="https://discord.gg/zdNChS2fBu">Discord</a> · <a href="https://docs.beacon.sh/cli/install">Install</a> · <a href="https://docs.beacon.sh/cli">Commands</a>

⭐ Help us reach more developers and grow the Beacon community. Star this repo!

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

text

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

<details open> <summary>macOS</summary>

bash

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

beacon endpoint install

</details>

<details> <summary>Linux</summary>

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

bash

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:

bash

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.

bash

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 on its own catches a corrupted download but does not prove who built the release. From 1.3.57 on, checksums.txt.sig signs it with Beacon's Linux release key (fingerprint 07BEA34ED6A411F4C066D98322F94195DCDC8F45), which install.sh checks; the Linux install guide shows how to check it by hand and how to install from the signed apt repository instead. You can also 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).

</details>

<details> <summary>Windows</summary>

Download the x64 MSI from the latest release.

bash

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

For silent installation:

bash

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

</details>

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

bash

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:

bash

beacon endpoint dashboard

Or inspect the raw event stream:

text

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

ℹ️ Ghi chú & Thông tin

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:

bash

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:

bash

beacon whoami

🧠 Turn Session History Into Memory

Every agent session contains potentially useful knowledge about your codebase.

Beacon creates a loop around that history:

text

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.

Beacon sits across the harness layer.

text

Claude Code ─┐
Cursor ──────┤
Codex ───────┼──→ Beacon ──→ shared project knowledge
OpenCode ────┤
Cline ───────┘

Because Beacon captures and normalizes session history across tools, knowledge learned through Claude Code doesn't have to stay in Claude Code.

Your Cursor sessions can improve Codex. Your Codex sessions can improve OpenCode. Your history keeps compounding even as you switch tools.

Your agent session history belongs to you, not the harness.

🔎 One Trace Format for Every Agent

Beacon captures agent execution where it happens and normalizes it into a common OpenTelemetry-based event model.

That includes:

sessions
prompts and responses
tool calls
commands
file activity
approvals
MCP interactions
token usage

Instead of separate proprietary histories for every coding tool, you get one dataset you can inspect, search, learn from, and build on.

🖥️ Local Dashboard

Beacon ships with a local, read-only dashboard:

bash

beacon endpoint dashboard

Use it to explore session history across harnesses and understand what your agents actually did. Open the URL it prints: it carries a secret for that run, so other accounts on a shared machine cannot read your log through the port. Administrators can turn the dashboard off for everyone with beacon endpoint install|repair --system --dashboard disabled (BEACON_DASHBOARD=disabled for package installs).

Each session page can also show lenses: purpose-built views of one trace, such as files changed with their diffs, an itemized token bill, a security review grouped by risk, or the approval timeline. A lens is a single HTML file running in a sandboxed frame with no access to Beacon or the dashboard and no ordinary network APIs, so you can have your coding agent write your own (beacon lenses spec, lint, preview, add). The sandbox cannot block every way a browser can send data out, so install only lenses you trust with your traces. See Lenses.

The underlying JSONL remains directly accessible, so you're never dependent on the UI.

Supported Agents

Beacon supports local agents, browser agents, cloud agents, CI workflows, and agent SDKs.

Local Agent Coverage

Runtime	Collection	Session	Prompt	Tool	Command	File	Approval	MCP	Tokens	Skills
Antigravity CLI	Hooks + poll	✅	✅	✅	✅	✅	–	–	✅	✅ skills CLI
Claude Code	OTLP + hooks + poll	✅	✅	✅	✅	✅	✅	✅	✅	✅ Plugin
Claude Cowork	OTLP	✅	✅	✅	✅	✅	✅	✅	✅	✅ Plugin
Cline	Plugin + poll	✅	✅	✅	✅	✅	–	✅	✅	✅ `.cline/skills`
Codex CLI	OTLP + hooks + poll	✅	✅	✅	✅	–	✅	–	✅	✅ Plugin
Codex Desktop	OTLP	✅	✅	✅	✅	–	✅	–	✅	✅ Plugin
Cursor	Hooks + poll	✅	✅	✅	✅	✅	✅	✅	–	✅ Plugin
DeepSeek Harness	Hooks + poll	✅	✅	✅	✅	✅	–	✅	✅	✅ `.agents/skills`
Devin CLI	Hooks + poll	✅	✅	✅	✅	✅	✅	✅	✅	✅ Plugin
Devin Desktop	Hooks	–	✅	✅	✅	✅	–	✅	–	✅ via Devin CLI
Factory Droid	OTLP + hooks + poll	✅	✅	✅	–	✅	✅	–	–	✅ Plugin
fx (Vercel Labs)	Poll	✅	✅	✅	✅	✅	–	✅	✅	✅ `/skills install`
Gemini CLI	OTLP	–	✅	✅	–	✅	✅	✅	–	✅ `gemini skills install`
GitHub Copilot CLI	OTLP + poll	✅	✅	✅	✅	✅	✅	–	✅	✅ Plugin
goose	Adapter only; manual hooks/OTLP	✅	✅	✅	✅	✅	–	✅	✅	✅ skills CLI
Grok Build	Hooks + poll	✅	✅	✅	✅	✅	✅	–	–	✅ Plugin
Hermes Agent	Hooks + poll	✅	✅	✅	✅	✅	✅	✅	–	✅ `hermes skills install`
Kimi Code	Hooks	✅	✅	✅	✅	✅	✅	✅	–	✅ Plugin
Kiro	Hooks	✅	✅	✅	✅	✅	–	✅	–	✅ Power
Muse Code	Hooks	✅	✅	✅	✅	✅	✅	–	–	✅ `.agents/skills`
Oh My Pi	Extension	✅	✅	✅	✅	✅	✅	✅	✅	✅ Plugin
OpenClaw Gateway	Plugin + OTLP + poll	✅	✅	✅	✅	✅	–	✅	~	✅ Plugin
OpenCode	Plugin + poll	✅	✅	✅	✅	✅	✅	✅	✅	✅ skills CLI
OpenHands	Hooks	✅	✅	✅	✅	✅	–	✅	–	✅ skills CLI
Pi	Extension + poll	✅	✅	✅	✅	✅	–	✅	✅	✅ Package
Prime Agent	Extension + poll	✅	✅	✅	✅	✅	–	–	✅	✅ Package
Qwen Code	Hooks	✅	✅	✅	✅	✅	✅	–	–	✅ Plugin
Senpi	Extension	✅	✅	✅	✅	✅	–	–	✅	✅ `.agents/skills`
VS Code	OTLP + hooks	✅	✅	✅	~	~	–	~	–	✅ Plugin

Skills shows how to install Beacon Skills, the Agent Skills that recall and distill project memory from these traces. Every runtime above loads Agent Skills:

Plugin: install the beacon plugin from this repository's marketplace, for example /plugin marketplace add asymptote-labs/agent-beacon in Claude Code.
Package (Pi, Prime Agent): pi install git:github.com/asymptote-labs/agent-beacon.
Power (Kiro): import https://github.com/asymptote-labs/agent-beacon/tree/main/agent-skills from the Powers panel.
skills CLI: npx skills add asymptote-labs/agent-beacon, optionally with -a <agent>.
A directory: copy agent-skills/skills/* into that project directory.

The Beacon Skills page has the exact command for each runtime.

Browser Chat

Site	Collection	Prompt	Response	Tool	Tokens
Claude.ai	Chromium + Firefox extension → local OTLP	✅	✅	✅	~
ChatGPT	Chromium + Firefox extension → local OTLP	✅	✅	✅	–

Cloud Agents

Runtime	Collection	Session	Prompt	Tool	Command	File	Tokens
Claude Code Cloud Agents	Sandbox hooks → GCS or S3	✅	✅	✅	✅	✅	–
Cursor Cloud Agents	Sandbox hooks → GCS or S3	–	✅	✅	✅	✅	–
Devin Cloud Agents	API poll → GCS	✅	✅	–	–	–	✅
CI jobs	`beacon ci exec` → temporary local collector	✅	✅	✅	✅	✅	✅

SDK Instrumentation

SDK Surface	Collection	Captures
Anthropic	OpenLLMetry through `@asymptote/sdk`	Model call spans, errors, and OTel attributes
OpenAI	OpenLLMetry through `@asymptote/sdk`	Model call spans, errors, and OTel attributes
Claude Agent SDK	`Observe.wrapClaudeAgentQuery()`	Query root spans with Beacon-compatible prompt attributes
Vercel AI SDK	`experimental_telemetry` tracer handoff	Model call and tool spans where telemetry is enabled

LLM Gateways

Gateway	Collection	Captures
LiteLLM, Envoy (incl. Envoy Gateway, Istio), Portkey	`beacon-gateway` hook adapter	Prompts, responses, tool calls, and token usage for every model call routed through the gateway

Output Destinations

Beacon writes endpoint telemetry to local JSONL by default.

You can also forward the same normalized session history into infrastructure you already use:

Splunk · Datadog · Elastic · Microsoft Sentinel · CrowdStrike Falcon LogScale · Sumo Logic · Wazuh · AWS S3 · GCS · CloudWatch

Destination	Category	Support Path
Local JSONL	Local	Default endpoint log and local dashboard source
Beacon Cloud	Hosted forwarding	Signed-in device enrollment with Standard or Metadata-only privacy
CrowdStrike Falcon LogScale HEC	SIEM	Endpoint forwarding with LogScale ingest tokens
Microsoft Sentinel	SIEM	Azure Monitor Agent and Data Collection Rule content pack
Rapid7 InsightIDR	SIEM	Custom Logs webhook content pack
Splunk HEC	SIEM	Endpoint forwarding during install or repair
Sumo Logic	SIEM	HTTP Logs & Metrics Source content pack
Wazuh	SIEM	Localfile configuration and Beacon content pack
AWS CloudWatch Logs	Log aggregation	Vector content pack
Datadog	Log aggregation	Datadog Agent custom log collection
Elastic	Log aggregation	Filebeat or Elastic Agent
Customer-managed pipelines	Log aggregation	Forward directly from local Beacon JSONL
AWS S3	Object storage	Vector, CI upload, or cloud-agent snapshots
Google Cloud Storage	Object storage	Vector, CI upload, or cloud-agent snapshots

Architecture

Beacon captures activity where agents actually run and normalizes it into one shared event model.

text

Local agents ───────┐
Browser chat ───────┤
CI ─────────────────┼──→ Beacon ──→ unified session history
Cloud agents ───────┤                    │
Agent SDKs ─────────┤                    ├──→ local JSONL
LLM gateways ───────┘                    │
                                         ├──→ reviewed memory
                                         ├──→ MCP / Agent Skills
                                         └──→ your own infrastructure

See the documentation for the full architecture breakdown.

Documentation

Read the docs for:

installation
supported runtimes
event schema
session history
memory
MCP
Agent Skills
forwarding
advanced configuration

Read the docs →

Contributing

Contributions are welcome.

Open an issue, submit a pull request, or join the Discord.

License

MIT

Star History

#Beacon Overview

#🎬 Demo

#🚀 Quick Start

#1. Install Beacon

#2. Use your agents normally

#3. Explore your history

#🧠 Turn Session History Into Memory

#🔀 Cross-Harness by Design

#🔎 One Trace Format for Every Agent

#🖥️ Local Dashboard

#Supported Agents

#Local Agent Coverage

#Browser Chat

#Cloud Agents

#SDK Instrumentation

#LLM Gateways

#Output Destinations

#Architecture

#Documentation

#Contributing

#License

#Star History

Beacon Overview

🎬 Demo

🚀 Quick Start

1. Install Beacon

2. Use your agents normally

3. Explore your history

🧠 Turn Session History Into Memory

🔀 Cross-Harness by Design

🔎 One Trace Format for Every Agent

🖥️ Local Dashboard

Supported Agents

Local Agent Coverage

Browser Chat

Cloud Agents

SDK Instrumentation

LLM Gateways

Output Destinations

Architecture

Documentation

Contributing

License

Star History