beacon-agent 0.1.0a1

Production-to-dev bridge. Ingests logs/errors from observability tools, clusters them, asks an LLM to summarize each cluster, opens or updates issues on GitHub/GitLab. Optional handoff to relay-agent closes the full SDLC loop. Standalone: no inter-package runtime deps.

Beacon

Production-to-dev bridge. Ingests logs and errors from observability tools, clusters them with an LLM, files structured issues on GitHub or GitLab. Optional handoff to Relay closes the full SDLC loop.

Status: alpha, live on PyPI as beacon-agent==0.1.0a1. Standalone: no inter-package runtime deps. GitHub + GitLab fully supported in v0.1.0a1; webhook server mode (Sentry, Datadog, OpenTelemetry receivers) lands in v0.1.0a2.

What it does

cat errors.jsonl | beacon digest \
  --vcs github --repo myorg/myapp \
  --relay-label relay

Beacon:

1. Ingests observability events (JSON-lines from stdin or a file)
2. Clusters them by stack signature so the same incident does not file 47 separate issues
3. Summarizes each cluster with an LLM: likely cause, suggested action, suspected file:line
4. Files (or updates) one issue per cluster on the VCS, with a stable hidden signature for dedup
5. Hands off to Relay: if the LLM judges the issue small and well-scoped, Beacon applies your --relay-label; Relay's workflow then picks it up and ships a fix PR

This closes the SDLC loop: production noise to triaged story to autonomous fix to review by Tribune to deploy to verify with Sentinel.

Why this exists

ThinkNext ships an OSS agentic SDLC stack:

Stage	Tool
Idea to code	Cascade (human-gated) or Relay (autonomous)
Code to review	Tribune
Code to tested running app	Sentinel
Production to next story	Beacon (this repo)

Beacon is the only piece that touches running production: the place where errors actually happen.

Install

pip install 'beacon-agent[claude-code]'    # or [anthropic], [openai], [google], [all]
beacon configure llm claude_code --set-default
beacon configure vcs github --token ghp_xxx --set-default

Run

# Dry run: print what would be filed
cat errors.jsonl | beacon digest --vcs github --repo myorg/myapp --dry-run

# File issues, label the small ones for Relay
cat errors.jsonl | beacon digest \
  --vcs github --repo myorg/myapp \
  --label beacon \
  --relay-label relay \
  --min-count 3 \
  --max-clusters 10

Read from a file instead of stdin:

beacon digest --source ./errors.jsonl --vcs gitlab --repo group/project

Input format

One JSON object per line. Beacon maps common field name aliases automatically so most sources work without an explicit adapter:

{"message": "User not found", "level": "error", "exception.type": "NotFound", "stacktrace": "...", "service.name": "api", "environment": "prod", "timestamp": "2026-05-27T10:15:00Z"}
{"msg": "DB connection refused", "level": "fatal", "service": "worker"}

Recognized aliases include: msg/message, level/severity, ts/timestamp, exception.type/exc_type/error.type, stack/stacktrace/traceback, service.name/service/app, env/environment, release/version, plus syslog-style numeric severities.

What ships in 0.1.0a1

Capability	Status
stdin / file JSONL ingest with multi-source field aliases	Full
Clustering by stack signature with stable fingerprints	Full
LLM summary per cluster (cause + action + relay-safe judgment)	Full
GitHub: find-or-create issue with hidden signature marker for dedup	Full
GitLab: same	Full
Optional --relay-label for autonomous handoff	Full
Multi-LLM via vendored client (Anthropic / OpenAI / Google / Claude Code / Ollama)	Full
Webhook server (Sentry, Datadog, OpenTelemetry receivers)	Planned 0.1.0a2
Per-repo beacon.yaml (severity thresholds, ignore patterns, custom prompt)	Planned 0.1.0a2
Scheduled digest mode (cron-style weekly rollups)	Planned 0.1.0a2
Bitbucket + Azure DevOps issue creators	Planned 0.1.0a3

License

MIT. See LICENSE.

About

Built and maintained by ThinkNext Software Solutions, alongside Cascade, Relay, Tribune, and Sentinel.