Agent Beacon
Quick Take
When a coding agent spends an hour on a task, most of what happened disappears once the session ends: which files it read, which commands it ran, where it went wrong, and what finally worked. Beacon, an open-source project from Asymptote Labs that is often listed as Agent Beacon after its repository name, keeps that record. It captures sessions from more than 20 coding agents into a common format, stores them on your machine, and gives you tools to browse and replay them. It then goes a step further, pulling reusable lessons out of past sessions and, once you approve them, handing them to future agents.
What It Records
Beacon normalizes agent activity into an event model based on OpenTelemetry, the open standard for traces and telemetry. Depending on the agent, it captures:
- sessions, prompts, and responses
- tool calls and shell commands
- file activity, including diffs for some sessions
- approvals you gave or denied
- MCP interactions
- token usage
How it collects varies by tool. Claude Code reports through OpenTelemetry plus hooks, Cursor through hooks, OpenCode and Cline through plugins, and some tools through polling. A browser extension covers Claude.ai and ChatGPT chats, cloud agents from Claude Code and Cursor can write to S3 or Google Cloud Storage, and a beacon ci exec wrapper covers agents run in CI. Beacon notes that what it can capture varies by runtime, so check its support table for your tools.
Browsing, Replay, and Lenses
By default, events go to a JSONL file in your home directory (~/.beacon/endpoint/logs/runtime.jsonl), which you can read with any tool. Beacon adds beacon traces, a terminal browser for sessions and event timelines, and a local, read-only web dashboard. It describes exact session replay as a core feature, and “lenses” give focused views of one session, such as the files it changed with diffs or an itemized token bill.
From Session History to Reusable Knowledge
Beacon’s distinctive idea is a loop: run agents, capture what they did, evaluate what worked, extract knowledge, and have a person review and approve it before reuse. Approved knowledge reaches future agents in two ways: as Agent Skills installed into ~/.agents/skills and ~/.claude/skills, or through an MCP server that beacon mcp connect registers in supported tools. The local MCP server makes no network calls.
A practical example from coverage of the project: if a Cursor session runs into a usage limit partway through a task, you can ask Claude Code to pick up where it stopped, and Beacon supplies the relevant context from the Cursor session.
Tracing, History, and Memory Are Different Jobs
Tools in this space blur several ideas. It helps to separate them:
- Tracing records each step of a run, with timing and inputs and outputs, so you can see exactly what happened. See agent trace.
- Session history keeps those traces after the run, so you can search and compare them later.
- Debugging uses the history to find where a run went wrong: the wrong file, the misread error, the command that silently failed. Doing this across many runs is agent runtime observability.
- Persistent memory is what an agent should know at the start of the next run, such as project conventions or a decision you made last week. See persistent agent state and agent memory.
- Knowledge extraction turns history into memory, deciding which lessons are worth keeping.
- Cross-agent portability makes that knowledge usable by a different tool. See portable context.
Beacon is strongest on the first three and builds the last three from them. A memory service such as Atlaso starts at the other end: it stores and recalls decisions and preferences, without keeping a detailed record of what each agent did. Neither replaces a hand-maintained context file such as CLAUDE.md for rules you want every agent to follow.
Privacy and Security
A complete record of agent sessions is useful precisely because it holds everything, and that is also the risk. Agent histories routinely contain API keys and tokens pasted into a prompt or printed by a command, responses from internal APIs, private source code and diffs, customer or personal data the agent read while debugging, and the output of every tool call.
What Beacon does: it writes to a local file by default and does not forward anything to its cloud until you confirm, but note that the interactive setup preselects Beacon Cloud forwarding, so you have to pick the Local option deliberately. It also offers a metadata-only privacy mode for Beacon Cloud, and can send events to destinations you control, such as Splunk, Datadog, Elastic, Microsoft Sentinel, S3, or Google Cloud Storage. Its documentation also warns that the lens sandbox cannot block every way a browser can send data out.
What we did not find: the repository does not describe automatic secret redaction. So treat the local log like any file that may contain credentials:
- Keep it out of synced folders and backups you do not control.
- Rotate any secret you know an agent printed or read.
- Use metadata-only mode, or no cloud at all, for client or regulated work.
- Review approved knowledge before it reaches other agents, since a “lesson” can carry a secret or a mistaken assumption with it.
- Set a retention habit, such as clearing old logs after each project.
Our agent security checklist covers the wider picture.
Installing It
Beacon installs on macOS through Homebrew, on Linux through an install script that installs a verified .deb or .rpm package (amd64 and arm64), and on Windows through an x64 MSI installer. After installing, beacon endpoint install sets up the local collector, and you connect each agent following the repository’s instructions. The project is under active development, so read the current README rather than relying on old tutorials.
Pricing
The CLI, local collector, dashboard, and local MCP server are free and MIT-licensed. Beacon Cloud is optional and has a free tier. Third-party pricing pages list Beacon Cloud Pro at $20 a month, or $15 a month billed annually, with enterprise plans quoted separately; we could not confirm those figures on Asymptote Labs’ own site.
Limitations
- Coverage varies by agent. Each integration captures different detail, and some depend on hooks or polling that can break when the agent updates.
- No documented secret redaction. You are responsible for what ends up in the logs.
- Knowledge needs review. Extracted lessons are only as good as the sessions they came from, which is why Beacon puts an approval step before reuse.
- A developer tool. Setup assumes comfort with a terminal, OpenTelemetry, and your agents’ configuration files.
- Young project. Expect frequent changes; check the repository’s release notes.
Alternatives
- Atlaso, a hosted memory layer across AI tools; see Agent Beacon vs Atlaso
- Gauge, an open-source tool that tests whether agents succeed on fixed tasks rather than recording everyday sessions; see Gauge vs Agent Beacon
- Foundation by Chroma, a team-oriented agent memory system
- A hand-maintained context file, the simplest way to give every agent the same starting rules
Related tools: Claude Code, Codex, Cursor, and OpenCode. For the concepts, see our guide to portable context across AI tools.
Continue learning
Explore related guides, tools, workflows, and prompts that help you go deeper into this topic.
See how this tool fits into a workflow
Browse step-by-step AI workflows that use ChatGPT, Claude, Gemini, and other tools.
Frequently Asked Questions
What is Agent Beacon?
Agent Beacon is the open-source project Asymptote Labs calls Beacon. It captures the sessions of AI coding agents (prompts, responses, tool calls, commands, file activity, approvals, MCP calls, and token usage) from Claude Code, Cursor, Codex, OpenCode, and more than 20 other tools, stores them locally by default, and lets you browse, replay, and learn from them.
Is Agent Beacon a memory tool?
Partly. Its foundation is session history and telemetry: a record of what agents did. On top of that, it extracts workflows, corrections, and debugging patterns, and after you review and approve them, makes them available to future agents through MCP or Agent Skills. That makes it a memory layer built from traces, rather than a store of facts you or the agent write down.
Does Agent Beacon send my code to the cloud?
Only if you let it. Beacon writes captured activity to a local JSONL file, and its local MCP server makes no network calls. But the interactive setup signs in through beacon.sh and preselects forwarding to Beacon Cloud, with an explicit Local option, so choose Local if you want nothing to leave your machine. Beacon Cloud also offers a metadata-only privacy mode. Session history can contain secrets and private code, so protect the local files too.
Which coding agents does Agent Beacon support?
Its repository lists Claude Code, Codex CLI and Desktop, Cursor, OpenCode, Cline, Gemini CLI, GitHub Copilot CLI, VS Code, Kiro, OpenHands, Devin CLI, Factory Droid, and others, plus browser chats on Claude.ai and ChatGPT through an extension, some cloud agents, and CI jobs. Collection works through OpenTelemetry, hooks, plugins, or polling depending on the agent, and coverage varies by tool.
How is Agent Beacon different from Atlaso?
Beacon starts from recording what agents did, locally and in detail, and builds reviewed knowledge from those traces. Atlaso is a hosted memory service that stores decisions and preferences and recalls them into your tools. See our Agent Beacon vs Atlaso comparison.
Last updated: