Beacon is a local dashboard for long-running AI coding agents. It watches the session files already on your machine, writes normalized events to ClickHouse, and gives you a live view of what agents are doing, which tools they used, how much token volume they consumed, and what happened in past runs.

What It Looks Like

Why Use Beacon

• See active and completed agent runs in one place, including project paths, models, duration, turns, tool calls, and subagents.
• Catch expensive or noisy work quickly with token charts, cache-token counts, model health, and error activity.
• Search prompts, responses, tool calls, paths, and errors across captured sessions without rebuilding an external search service.
• Replay a session as a readable transcript with expandable tool payloads and timeline context.
• Let agents query prior work through MCP tools instead of asking you to remember which session contained the answer.

Beacon currently understands session data from Claude Code, OpenAI Codex, Hermes Agent, OpenCode, and Pi coding-agent runs.

Install

The installer supports macOS and Linux on amd64 and arm64.

curl -sSfL https://johnnygreco.dev/beacon/install.sh | sh

It installs beacon to ~/.local/bin. If ClickHouse is not already available on PATH, it also installs a managed ClickHouse binary to ~/.beacon/bin.

If your shell cannot find beacon, add the install directory to PATH:

export PATH="$HOME/.local/bin:$PATH"

Common variants:

curl -sSfL https://johnnygreco.dev/beacon/install.sh | INSTALL_DIR=/usr/local/bin sh
curl -sSfL https://johnnygreco.dev/beacon/install.sh | VERSION=0.1.0 sh
curl -sSfL https://johnnygreco.dev/beacon/install.sh | INSTALL_CLICKHOUSE=0 sh
curl -sSfL https://johnnygreco.dev/beacon/install.sh | UNINSTALL=1 sh

Use INSTALL_CLICKHOUSE=0 only when you already run ClickHouse yourself. UNINSTALL=1 removes the installed beacon binary and ~/.beacon, including Beacon-managed ClickHouse data.

Start

beacon up

Open http://localhost:4600. On startup, Beacon loads ~/.beacon/beacon.toml if it exists, starts local ClickHouse when the configured ClickHouse address is local, migrates the schema, backfills existing sessions, and then watches for new events.

Useful commands:

beacon status   # server, ClickHouse, session, and search-index health
beacon down     # stop the running Beacon web server
beacon db down  # stop Beacon-managed local ClickHouse

Capture Sources

These sources are enabled by default:

Source	Runtime	Default path
Claude Code	claude-code	~/.claude/projects/**/*.jsonl
OpenAI Codex	codex	~/.codex/sessions/**/*.jsonl
Hermes Agent	hermes-agent	~/.hermes/state.db
OpenCode	opencode	~/.local/share/opencode/opencode*.db
Pi coding agent	pi-coding-agent	~/.pi/agent/sessions/**/*.jsonl

Backfill runs on startup by default, then the watcher keeps configured paths up to date.

Configuration

Beacon reads ~/.beacon/beacon.toml by default. Pass --config <path> to use another file:

beacon --config ./beacon.toml up

Start from the example in beacon.toml. The settings most people change are the web port, ClickHouse address, and capture sources:

[server]
host = "0.0.0.0"
port = 4600

[database]
addrs = ["127.0.0.1:9000"]
database = "beacon"
username = "default"
password = ""
secure = false

[[capture.sources]]
name = "codex"
runtime = "codex"
provider = "openai"
glob = "~/.codex/sessions/**/*.jsonl"
watch_root = "~/.codex/sessions"
format = "jsonl"

If [database].addrs points to a remote ClickHouse host, Beacon will not start ClickHouse for you. Start the database yourself and run beacon db migrate.

ClickHouse

For local addresses such as 127.0.0.1:9000, localhost:9000, or 0.0.0.0:9000, beacon up, beacon serve, and beacon watch try to start ClickHouse when it is not already reachable.

Auto-start prefers:

1. a clickhouse binary from BEACON_CLICKHOUSE_BIN, PATH, or ~/.beacon/bin/clickhouse
2. an existing Docker container named beacon-clickhouse
3. a new Docker container using clickhouse/clickhouse-server:24.12

Manual database commands:

beacon db up                  # start local ClickHouse and migrate tables
beacon db up --runtime native # require a local clickhouse binary
beacon db up --runtime docker # require Docker
beacon db migrate             # migrate an already-running ClickHouse
beacon db reset --force       # destructive: drop and recreate Beacon tables

Native ClickHouse data lives under ~/.beacon/clickhouse. Docker mode uses the beacon-clickhouse-data volume.

MCP Integration

Run beacon up or beacon db up first so ClickHouse is available and migrated, then add Beacon to your MCP client:

{
  "mcpServers": {
    "beacon": {
      "command": "beacon",
      "args": ["mcp"]
    }
  }
}

If your MCP client cannot use Beacon's config file, pass ClickHouse directly:

{
  "mcpServers": {
    "beacon": {
      "command": "beacon",
      "args": ["mcp", "--clickhouse", "127.0.0.1:9000"]
    }
  }
}

Available tools:

• search_sessions searches the precomputed activity index and returns session/event IDs.
• open retrieves one event plus nearby context from the same session.
• list_sessions lists recent sessions with summary stats.

Commands

Command	Use it for
beacon or beacon up	Start the dashboard and capture service
beacon serve	Start the dashboard and capture service explicitly
beacon down or beacon stop	Stop the running Beacon web server
beacon watch or beacon run capture	Capture sessions without the web dashboard
beacon run web	Run web and capture services
beacon mcp or beacon run mcp	Start the MCP server over stdin/stdout JSON-RPC
beacon status	Show server, database, session, and search-index status
beacon db up	Start local ClickHouse and migrate tables
beacon db down	Stop Beacon-managed local ClickHouse
beacon db migrate	Create or update ClickHouse tables
beacon db reset --force	Delete Beacon data and recreate tables

Build From Source

Source builds require Go 1.24.1 or newer. Node/npm are only needed for Playwright tests and vendoring browser assets.

git clone https://github.com/johnnygreco/beacon.git
cd beacon
make build
./bin/beacon up

Development commands:

make generate       # regenerate templ output
make test           # generate templates and run Go tests
make test-race      # run Go tests with the race detector
make perf-bench     # run perf benchmarks; set PERF_SIZE=small|medium|large
npm install         # install Playwright and asset-vendoring dependencies
npm run vendor      # refresh vendored frontend assets
npm run test:e2e    # dashboard and search Playwright tests
npm run test:a11y   # accessibility tests
npm run test:visual # visual regression tests

Most Go tests do not need a live ClickHouse server. Live ClickHouse integration and perf tests are opt-in:

beacon db up
BEACON_TEST_CLICKHOUSE=127.0.0.1:9000 go test ./internal/store ./internal/search ./internal/web
BEACON_TEST_CLICKHOUSE=127.0.0.1:9000 go test ./internal/perf -bench . -run '^$'

Playwright tests start their own e2e server by default. To test against an already running Beacon-compatible server, set BEACON_E2E_BASE_URL.

Troubleshooting

beacon is not found after install. Add the install directory to PATH, usually export PATH="$HOME/.local/bin:$PATH".

ClickHouse does not start. Run beacon db up --runtime native if you installed the managed ClickHouse binary, or beacon db up --runtime docker if you prefer Docker. Set BEACON_CLICKHOUSE_BIN=/path/to/clickhouse to use a specific binary.

Beacon connects to the wrong database. Check [database].addrs in ~/.beacon/beacon.toml or pass --config <path>.

No sessions appear. Confirm the agent has written session files in one of the configured source paths, then run beacon status and restart with backfill_on_start = true.

Port 4600 is already in use. Change [server].port in the config file or stop the existing process with beacon down.

Acknowledgements

This project was inspired by Wes McKinney's agentsview, Eric Tramel's moraine, and Simon Willison's claude-code-transcripts.

License

Apache License 2.0