Beacon CLI
A CLI that records session history from Claude Code, Cursor, Codex and other agents in one format and turns reviewed lessons into memory for new sessions
- 2,921 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Records prompts, replies, commands, file edits and tool output of all your agents, and text with a secret of no recognizable shape may be stored as is
- Changes the settings of Claude Code, Cursor, Codex and other agents: it connects hooks, plugins and skills and then records sessions continuously in the background
- The wizard offers sending the log to Beacon Cloud by default, and the skills can upload a session to beacon.sh and call an evaluator service
Install
- Works in
Manual install
brew trust asymptote-labs/tap && brew tap asymptote-labs/tap && brew install beacon && beacon endpoint installmacOS install. The wizard offers Beacon Cloud, choose Local to stay on the machine.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Records prompts, replies, commands, file edits and tool output of all your agents, and text with a secret of no recognizable shape may be stored as is
- Changes the settings of Claude Code, Cursor, Codex and other agents: it connects hooks, plugins and skills and then records sessions continuously in the background
- The wizard offers sending the log to Beacon Cloud by default, and the skills can upload a session to beacon.sh and call an evaluator service
This is third-party code. Review the repository files before installing.
What it does
Beacon is an open-source command-line program written in Go that runs next to coding agents and keeps a shared log of their sessions. The `beacon endpoint install` command sets up a collector: it connects to the hooks, plugins and telemetry of Claude Code, Cursor, Codex, OpenCode, Cline, Gemini CLI and two dozen more harnesses, and writes events in one OpenTelemetry-based format. The log holds prompts, replies, tool calls, commands, file edits, approvals, MCP calls and token usage. The `~/.beacon/endpoint/logs/runtime.jsonl` file stays on your disk, `beacon traces` opens a terminal viewer for it, and `beacon endpoint dashboard` gives a read-only local web interface. Beacon builds project memory from the log. A set of five skills (`beacon-memory-recall`, `beacon-memory-distill`, `beacon-memory-promote`, `beacon-lens-create`, `beacon-trace-share`) pulls approved lessons before a task, picks sessions and writes a lesson with your consent, and `beacon-memory-promote` saves it as `.agents/skills/<name>/SKILL.md` so any harness loads the lesson itself. The local MCP server starts with `beacon mcp serve`. The log can optionally travel further: to Beacon Cloud at beacon.sh, to Splunk, Datadog, Elastic, Microsoft Sentinel, Wazuh, and to S3 and GCS storage. Before sending, secrets are replaced by pattern with `[REDACTED]` and long fields are truncated. The cloud has two privacy modes, standard and metadata-only.
Who it is for. For developers and teams who work in several agents at once, want their session history in one place and want to reuse solutions they already found instead of explaining them again.
Good fit when
- You switch between Claude Code, Cursor and Codex and want solutions from one harness handed to another without copying by hand
- You need to review what an agent did in a session: commands, edits, approvals and token usage in one timeline
- A team needs to send agent events to Splunk, Datadog or Microsoft Sentinel for investigations and accounting
- Fixes you keep repeating to agents should become reviewed lessons placed in `.agents/skills`
Not a fit when
- Session content must not be stored even locally: the log includes prompts and command output, and pattern-based redaction misses an unlabeled password
- You work in a single agent and its built-in memory is enough: a collector for one harness is overkill
- You need history search without a separate collector: Coding Agent Session Search is closer for existing Claude Code and Codex logs
- You do not want the install to change agent settings: it connects hooks and plugins, and the wizard puts skills into `~/.agents/skills` and `~/.claude/skills`
Example request
Find in past session history how we solved the migrations problem in this repository, and remind me what workedLimitations
- The interactive `beacon endpoint install` wizard offers Beacon Cloud by default rather than local mode. Signing in at beacon.sh sends nothing by itself, but confirming the connection turns forwarding on. To keep data on the machine choose Local. `beacon endpoint disconnect` stops forwarding.
- Secret redaction is pattern-based: a password with no label or recognizable shape is not found, so treat text kept in the log as sensitive.
- Event coverage is uneven. For example, Gemini CLI has no session or command events and Codex has no file events. The repository holds a full coverage table per harness.
- After a dry run and your consent, the `beacon-memory-distill` skill calls an evaluator service, and `beacon-trace-share` uploads a session to beacon.sh when asked.
- Available as Homebrew on macOS, `.deb` and `.rpm` packages for Linux and an MSI for Windows. License MIT.
How to disable. Run `beacon endpoint disconnect` to stop forwarding and `beacon skills uninstall` to remove the skills. `beacon mcp disconnect` removes the connected cloud MCP. Remove the program itself with your package manager, for example `brew uninstall beacon`. The log lives in `~/.beacon` and can be deleted by hand.
FAQ
Where does Beacon keep session history?
By default in the local `~/.beacon/endpoint/logs/runtime.jsonl` file in JSONL format. Until you choose the cloud or an external system, nothing is sent anywhere. Viewing is local: `beacon traces` in the terminal and `beacon endpoint dashboard` in the browser.
What are lenses in the Beacon dashboard?
A lens is a single HTML file that shows one session's data in a convenient form: changed files with diffs, a token count, a breakdown by risk, an approval timeline. It runs in a sandboxed frame. The author warns that the sandbox does not block every way out, so install only lenses you trust.
How does project memory work?
The `beacon-memory-distill` skill offers sessions, scores them with the evaluator after a dry run and your consent, reads the source trace and drafts a lesson grounded in it. You approve the lesson together with the agent. `beacon-memory-recall` fetches approved lessons before a task, and `beacon-memory-promote` turns them into an ordinary skill.
Can it record a browser chat?
Yes, claude.ai and ChatGPT are covered by an extension for Chromium and Firefox. It passes prompts, replies and tool calls to a local OTLP collector on your machine. Token usage for claude.ai is approximate and is not captured for ChatGPT.
How does Beacon work in continuous integration?
`beacon ci exec` runs a job with a temporary local collector and records the session, commands, files and tokens. The repository ships an `action.yml` for GitHub Actions. For Claude Code and Cursor cloud agents the session snapshot goes through sandbox hooks to GCS or S3 storage.
How many harnesses does Beacon support?
More than twenty local ones, from Antigravity CLI and Claude Code to OpenHands and Qwen Code. The repository table lists the collection method for each (hooks, OTLP, polling, plugin) and which event types are supported. Cloud agents include Claude Code, Cursor and Devin.
Discussion
No questions or reviews yet.
Related
CLI toolsA CLI and skill that gather coding-agent session history into one SQLite file the agent can search for past decisions
Persistent agent memory in a folder of linked markdown notes, so Claude Code remembers a project across sessions
One local binary that gives Claude Code, Codex and Cursor shared memory across sessions, with a knowledge graph on disk and no API keys
Engram by Gentleman Programming
Engram (Gentleman Programming)
Persistent memory for AI coding agents in a single Go binary: an MCP server on SQLite with full-text search that remembers your project across sessions
Open infrastructure for agents that learn from experience: session traces, a knowledge base and skill packs via CLI, MCP and API
Long-term agent memory in local Markdown files with a link graph, semantic search and MCP access
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| Beacon (this entry) | no | 2,921 | |
| Coding Agent Session Search (cass) | no | 1,196 | a CLI and TUI for searching local session history, with a --robot mode for the agents themselves |
| Claude Code History Viewer | no | 2,289 | a desktop app for viewing and analysing conversation history from various agents |
| Mem0 | no | 68,007 | a memory layer for agents with plugins, a CLI and an SDK that carry context between sessions |
README in short
The repository holds the Go sources of the CLI and collector, a plugin with five memory skills and manifests for Claude Code, Codex, Cursor, Gemini CLI and other harnesses, a browser extension, packages for macOS, Linux and Windows, a sandbox for checking installs, and docs on privacy and secret redaction. The front page opens with the idea of shared memory for agents and the install, followed by the loop that turns history into knowledge, tables of supported harnesses and log destinations.