The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
refresh beacon readme
Justin D'Souzad43af2e2c71f
diff --git a/README.md b/README.mdindex 2da350d2..546bc59a 100644--- a/README.md+++ b/README.md@@ -1,85 +1,50 @@-<p align="center">- <img src="images/beacon-hero.png" alt="Beacon" width="860">-</p>+# Beacon-<h1 align="center">Beacon</h1>+### The open-source cross-harness memory layer for AI agents.-<p align="center">- <a href="https://github.com/asymptote-labs/agent-beacon/releases"><img src="https://img.shields.io/github/v/release/asymptote-labs/agent-beacon" alt="GitHub release"></a>- <a href="https://github.com/asymptote-labs/homebrew-tap"><img src="https://img.shields.io/badge/homebrew-beacon-fbb040?logo=homebrew" alt="Homebrew"></a>- <a href="https://github.com/asymptote-labs/agent-beacon/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/asymptote-labs/agent-beacon/ci.yml" alt="GitHub Workflow Status"></a>- <a href="https://github.com/asymptote-labs/agent-beacon/blob/main/LICENSE"><img src="https://img.shields.io/github/license/asymptote-labs/agent-beacon" alt="MIT license"></a>- <a href="https://docs.beacon.sh"><img src="https://img.shields.io/badge/docs-beacon.sh-0369a1" alt="Docs"></a>- <a href="https://discord.gg/zdNChS2fBu"><img src="https://img.shields.io/badge/discord-community-5865F2?logo=discord&logoColor=white" alt="Discord"></a>-</p>+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.-<p align="center">- <strong>The cross-harness self-improving memory layer for AI agents.</strong>-</p>+**A problem solved by one agent shouldn't need to be learned from scratch by another.**-<p align="center">- <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>-</p>+[Docs](https://docs.beacon.sh) · [Discord](https://discord.gg/zdNChS2fBu) · [Install](#quick-start) · [Commands](https://docs.beacon.sh/cli)-Beacon captures what happens across Claude Code, Codex, Cursor, OpenCode, and 20+ other agent 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-## Your Agents Keep Forgetting+AI agents learn useful things every time you work with them. But that knowledge is usually trapped inside individual sessions and individual harnesses.-You teach Claude Code how your repo handles migrations.+Beacon gives your agents a shared history.-Later, Cursor hits the same problem and has to figure it out again.+It continuously captures agent session history across your coding agents, normalizes those traces into one common format, and helps turn the highest-signal work into reviewed memory that other agents can reuse.-Then Codex makes the same mistake.--The knowledge exists. It's just trapped across isolated agent transcripts.--Beacon gives your agents a shared history across harnesses.--```text-Claude Code --+-Cursor -------+-Codex --------+--> Beacon --> reusable knowledge-OpenCode -----+ |-Cline --------+ v- future agents-```--Your Claude Code sessions can teach Codex.-Your Cursor debugging can improve OpenCode.+Your Claude Code sessions can teach Codex.+Your Cursor debugging can improve OpenCode.A workflow solved once can become reusable everywhere.-## How It Works+### Key Capabilities-Beacon continuously captures agent activity across supported harnesses:+- **Cross-harness session history** — one record across Claude Code, Cursor, Codex, OpenCode, Cline, and 20+ more+- **Compounding knowledge** — surface successful workflows, repeated corrections, debugging patterns, and repo conventions from real agent work+- **Reviewed agent memory** — promote useful knowledge into memory future agents can retrieve through MCP or Agent Skills+- **Unified traces** — prompts, responses, tool calls, commands, file edits, approvals, MCP activity, and tokens in one event model+- **Local-first** — durable JSONL and a local dashboard with no account or network dependency+- **Open and portable** — your session history is independent of whichever agent harness you use-- prompts and responses-- tool calls-- commands-- file changes-- approvals-- MCP activity-- token usage-- session context+----Every harness is normalized into the same event model.+## Use Cases-Beacon can then evaluate historical traces, identify useful workflows and corrections, and turn them into reviewed project memory that future agents can retrieve through MCP or Agent Skills.+- **Cross-harness memory** — let knowledge discovered in one coding agent benefit every other agent you use+- **Repository knowledge** — capture conventions, workflows, and context agents repeatedly have to rediscover+- **Debugging memory** — preserve successful approaches to difficult bugs instead of losing them in old sessions+- **Repeated corrections** — identify things developers keep teaching agents and make them reusable+- **Session replay** — reconstruct what an agent actually did across commands, tools, files, and prompts+- **Portable history** — switch harnesses without throwing away everything your previous agents learned-```text-Run agents -> capture traces -> find what worked -> extract knowledge -> reuse it everywhere-```--Your agent history stops being dead logs and becomes knowledge that compounds as you work.+----## Getting Started+## 🚀 Quick StartBeacon is open source, local-first, and requires no account.@@ -93,27 +58,25 @@ brew install beaconbeacon endpoint install```-Then use your coding agents normally.+Then use Claude Code, Cursor, Codex, or another supported agent normally.-To inspect your agent history:+Open your local session history:```bashbeacon endpoint dashboard```-Events are also written locally to:+Events are also written directly to:```text~/.beacon/endpoint/logs/runtime.jsonl```-No account. No API key. No network dependency.--Your data stays on your machine unless you explicitly configure forwarding.+**No account. No API key. Nothing leaves your machine unless you configure it to.**### Linux-Install a `.deb` or `.rpm` from the [latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest):+Install the `.deb` or `.rpm` from the [latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest):```bashsudo apt install ./beacon_<version>_linux_amd64.deb@@ -127,95 +90,250 @@ sudo dnf install ./beacon_<version>_linux_amd64.rpm### Windows-Install the x64 `.msi` from the [latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest):+Install the x64 MSI from the [latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest):-```powershell+```bashmsiexec /i BeaconEndpointAgent-<version>-x64.msi```-## What Beacon Gives You+For silent installation:-### Cross-Harness Memory+```bash+msiexec /i BeaconEndpointAgent-<version>-x64.msi /qn+```-Useful knowledge isn't tied to one coding agent.+----A debugging pattern discovered in Claude Code can be reused by Codex. A correction made in Cursor can become available to OpenCode.+## 🧠 Turn Session History Into Memory-Switch harnesses without throwing away everything your previous agents learned.+Every agent session contains potentially useful knowledge about your codebase.-### Knowledge From Real Work+Beacon creates a loop around that history:-Beacon helps surface things your agents repeatedly learn while working:+```text+Run agents+ ↓+Capture session history+ ↓+Evaluate what worked+ ↓+Extract useful knowledge+ ↓+Review + approve+ ↓+Reuse across future agents+```-- successful debugging approaches-- repository conventions-- repeated corrections-- useful tool sequences-- migration and deployment workflows-- recurring failure patterns+That could be:-Instead of manually documenting every lesson, build knowledge from the agent work already happening.+- 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-### One History Across Every Agent+Instead of disappearing into old sessions, that knowledge becomes reusable.-Beacon also gives you a normalized record of what your agents actually did.+----See commands, tools, edits, failures, retries, approvals, and context across harnesses from one local dataset.+## 🔀 Cross-Harness by Design-When something goes wrong, reconstruct the run instead of digging through separate transcripts.+Most agent memory belongs to a single harness.-### Local-First+Beacon sits across the harness layer.-Beacon stores telemetry as durable local JSONL.+```text+Claude Code ─┐+Cursor ──────┤+Codex ───────┼──→ Beacon ──→ shared project knowledge+OpenCode ────┤+Cline ───────┘+```-Use the local dashboard, query the data yourself, build on top of it, or forward it into your own infrastructure.+Because Beacon captures and normalizes session history across tools, knowledge learned through Claude Code doesn't have to stay in Claude Code.-Your agent history belongs to you, not the harness.+Your Cursor sessions can improve Codex.+Your Codex sessions can improve OpenCode.+Your history keeps compounding even as you switch tools.-## Supported Agents+**Your agent session history belongs to you, not the harness.**-Beacon supports Claude Code, Cursor, Codex, OpenCode, Cline, Gemini CLI, GitHub Copilot CLI, Devin, Factory Droid, Pi, and 20+ other agent runtimes.+----### Local Agents+## 🔎 One Trace Format for Every Agent-| Runtime | Session | Prompt | Tool | Command | File | MCP | Tokens |-| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: |-| Claude Code | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |-| Cursor | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | - |-| Codex CLI | ✅ | ✅ | ✅ | ✅ | - | - | ✅ |-| OpenCode | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |-| Cline | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |-| Gemini CLI | - | ✅ | ✅ | - | ✅ | ✅ | - |-| GitHub Copilot CLI | ✅ | ✅ | ✅ | - | - | - | - |-| Devin CLI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | - |-| Factory Droid | ✅ | ✅ | ✅ | - | ✅ | - | - |-| Pi | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |+Beacon captures agent execution where it happens and normalizes it into a common OpenTelemetry-based event model.-[See full runtime coverage ->](https://docs.beacon.sh/runtimes)+That includes:-Beacon also supports browser chat, cloud agents, CI jobs, and SDK instrumentation.+- 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.-## Where The Data Can Go+----Local JSONL is the default.+## 🖥️ Local Dashboard-Beacon can also forward the same normalized event stream into systems including:+Beacon ships with a local, read-only dashboard:-Splunk · Datadog · Elastic · Microsoft Sentinel · CrowdStrike LogScale · Sumo Logic · Wazuh · AWS S3 · GCS · CloudWatch+```bash+beacon endpoint dashboard+```-Or build directly on the JSONL yourself.+Use it to explore session history across harnesses and understand what your agents actually did.-## Open Source+The underlying JSONL remains directly accessible, so you're never dependent on the UI.-Beacon is MIT licensed.+----Try it with the coding agents you already use:+## Supported Agents-```bash-brew install asymptote-labs/tap/beacon+Beacon supports local agents, browser agents, cloud agents, CI workflows, and agent SDKs.++Popular supported runtimes include:++**Claude Code · Cursor · Codex CLI · Codex Desktop · OpenCode · Cline · Gemini CLI · GitHub Copilot CLI · Devin · Factory Droid · Pi · OpenHands · Kiro · goose · Hermes**++And 20+ more.++### Local Agent Coverage++| Runtime | Collection | Session | Prompt | Tool | Command | File | Approval | MCP | Tokens |+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |+| Antigravity CLI | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | – | – | – |+| Claude Code | OTLP + hooks + poll | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |+| Claude Cowork | OTLP | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |+| Cline | Plugin + poll | ✅ | ✅ | ✅ | ✅ | ✅ | – | ✅ | ✅ |+| Codex CLI | OTLP + hooks + poll | ✅ | ✅ | ✅ | ✅ | – | ✅ | – | ✅ |+| Codex Desktop | OTLP | ✅ | ✅ | ✅ | ✅ | – | ✅ | – | ✅ |+| Cursor | Hooks + poll | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | – |+| DeepSeek Harness | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | – | ✅ | – |+| Devin CLI | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | – |+| Devin Desktop | Hooks | – | ✅ | ✅ | ✅ | ✅ | – | ✅ | – |+| Factory Droid | OTLP + hooks + poll | ✅ | ✅ | ✅ | – | ✅ | ✅ | – | – |+| fx (Vercel Labs) | Poll | ✅ | ✅ | ✅ | ✅ | ✅ | – | ✅ | ✅ |+| Gemini CLI | OTLP | – | ✅ | ✅ | – | ✅ | ✅ | ✅ | – |+| GitHub Copilot CLI | OTLP | ✅ | ✅ | ✅ | – | – | ✅ | – | – |+| goose | Adapter only; manual hooks/OTLP | ✅ | ✅ | ✅ | ✅ | ✅ | – | ✅ | ✅ |+| Grok Build | Hooks + poll | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | – | – |+| Hermes Agent | Hooks + poll | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | – |+| Kiro | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | – | ✅ | – |+| Muse Code | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | – | – |+| Oh My Pi | Extension | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |+| OpenClaw Gateway | Plugin + OTLP + poll | ✅ | ✅ | ✅ | ✅ | ✅ | – | ✅ | ~ |+| OpenCode | Plugin + poll | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |+| OpenHands | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | – | ✅ | – |+| Pi | Extension + poll | ✅ | ✅ | ✅ | ✅ | ✅ | – | ✅ | ✅ |+| Prime Agent | Extension + poll | ✅ | ✅ | ✅ | ✅ | ✅ | – | – | ✅ |+| Qwen Code | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | – | – |+| Senpi | Extension | ✅ | ✅ | ✅ | ✅ | ✅ | – | – | ✅ |+| VS Code | OTLP + hooks | ✅ | ✅ | ✅ | ~ | ~ | – | ~ | – |++### Browser Chat++| Site | Collection | Prompt | Response | Tool | Tokens |+| --- | --- | --- | --- | --- | --- |+| Claude.ai | Extension → local OTLP | ✅ | ✅ | ✅ | ~ |+| ChatGPT | 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 |++---++## 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 |+| 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+ ├──→ reviewed memory+ ├──→ MCP / Agent Skills+ └──→ your own infrastructure```-If Beacon is useful, give the repo a star.+See the [documentation](https://docs.beacon.sh/architecture/architecture) 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 →**](https://docs.beacon.sh)++---++## Contributing++Contributions are welcome.++Open an issue, submit a pull request, or join the [Discord](https://discord.gg/zdNChS2fBu).++---## License