Beacon

Status: 0.2.0rc1 release candidate. Install the pinned release candidate from PyPI, or use a source checkout for development.

Beacon gives software projects a consistent way to explain themselves to coding agents.

Add a beacon.yaml to a repository and run the local MCP server. A connected agent can then ask:

• What is this project, and what is it trying to do?
• What should I read before touching any code?
• What does this term mean, and where is it implemented?
• What should I avoid changing without a senior review?
• What is the safest first contribution I can make?

Beacon returns structured answers with source citations instead of handing the agent a pile of raw text.

The current release is manifest-driven. It reads beacon.yaml and the documents listed there. It does not need an external service, database, runtime LLM call, telemetry, or update check.

Install

Install the release candidate and its published framework dependency from PyPI:

python -m pip install "archolith-beacon==0.2.0rc1"

The distribution name is archolith-beacon; the import package is beacon and the CLI command is beacon.

For development, check out this repository and install its dev dependencies:

git clone https://github.com/Archolith/beacon.git
cd beacon
pip install -e ".[dev]"

The package metadata uses the normal archolith-mcp-framework>=0.2,<0.3 constraint. It does not contain a Git URL or depend on a private package index.

Requires Python 3.12, 3.13, or 3.14.

Quick start

The v0.2 product loop is: initialize, review, validate strictly, inspect with a task in mind, export a reviewable snapshot, then connect an agent.

beacon init
  -> review beacon.yaml
  -> beacon validate --strict-warnings
  -> beacon inspect --task-hint "..."
  -> beacon export
  -> connect MCP client / beacon serve

1. Add a beacon.yaml to your repo.

The manifest is the source of truth. init generates a conservative starter from bounded repository evidence; you can also write one by hand. See beacon.yaml in this repo for a full example (describing Menhir), and the examples/ index for ready-to-run manifests in three different project shapes.

A minimal manifest declares identity, purpose, and the canonical docs:

beacon_version: "0.1"

project:
  name: my-project
  tagline: One sentence that explains what this is.
  status: experimental
  description: >
    Two to three sentences. What the project does, what problem
    it solves, and who it is for.

purpose:
  one_sentence: >
    What is the core job this project does for its users?

core_concepts:
  - id: key_concept
    name: Key Concept
    status: current
    description: What it is.

canonical_docs:
  - path: .agent/README.md
    role: entrypoint
    status: current
    title: Agent entry point

guardrails:
  - id: no_unsafe_change
    scope: core
    severity: high
    rule: >
      Do not change X without running the test suite and updating the docs.
    applies_to:
      - src/myproject/core/

2. Validate the manifest.

beacon validate path/to/beacon.yaml

Fix any reported errors before connecting an agent. Warnings are informational; under --strict-warnings, unresolved publication warnings block the export path.

3. Inspect what the tools will return.

beacon inspect path/to/beacon.yaml

Pass a task hint to see task-scoped onboarding and guardrails rather than only the no-argument defaults.

4. Check the installed version.

beacon --version
# beacon 0.2.0rc1

5. Start the MCP server.

Start stdio explicitly with serve, or rely on the environment-driven no-argument form. Both run the same MCP-over-stdio server:

beacon serve --manifest beacon.yaml
# or the compatible no-argument form, driven by the environment:
BEACON_MANIFEST_PATH=/absolute/path/to/beacon.yaml beacon

beacon serve also accepts --docs-root DIR and the six --max-* limit flags. Configure your agent client to launch one of these commands (see Connecting an agent and the maintained docs/client-setup.md).

What agents can ask

Beacon registers five read-only MCP tools when the server starts.

beacon_project_overview

"What is this project and what should I read next?"

Returns a structured summary: project description, problem statement, current status, core components, and a canonical read order.

Inputs:
  audience: "new_contributor" | "coding_agent" | "researcher" | "maintainer"
            (default: "coding_agent")
  depth:    "short" | "standard" | "deep" (default: "standard")

beacon_agent_onboarding

"I am about to work on X. What do I need to know?"

Returns a task-specific onboarding pack: docs to read first, relevant files, concepts to understand, safe first steps, and a do-not-touch list.

Inputs:
  task_hint:      description of what you plan to do (optional)
  risk_tolerance: "low" | "medium" | "high" (default: "low")

beacon_search

"What does this project know about temporal memory?"

Keyword search across docs, concepts, and guardrails. Every result carries a status (current, experimental, superseded) and a why_relevant field.

Inputs:
  query:        search string
  source_types: list of "docs" | "concepts" | "guardrails" (default: all)
  limit:        max results (default: 8)

beacon_explain_concept

"What is blast_radius and where is it implemented?"

Looks up a project-specific term by id or name. Returns the definition, motivation, related concepts, and implementation locations.

Inputs:
  concept: concept id or display name
  depth:   "simple" | "technical" | "implementation" (default: "technical")

beacon_guardrails

"What should I avoid touching, and what checks are required?"

Returns the full guardrail set, filtered to a task if a hint is provided. Includes risky files aggregated from applies_to fields and the project's required test/build commands.

Inputs:
  task_hint: description of planned work (optional)

Every response includes:

{
  "status":       "current | experimental | uncertain | mixed",
  "confidence":   "low | medium | high",
  "sources":      [{ "type": "doc", "path": "...", "line_start": 12, "line_end": 34 }],
  "next_actions": ["Call beacon_agent_onboarding with task_hint=..."]
}

Agents should respect status and confidence. A response marked experimental or low confidence is a signal to verify, not to treat as ground truth.

Connecting an agent

Replace /absolute/path/to/beacon.yaml with the real path on your machine. The maintained, install-first guide is docs/client-setup.md; the ready-to-connect configs below are also reproduced there.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "beacon": {
      "command": "beacon",
      "env": {
        "BEACON_MANIFEST_PATH": "/absolute/path/to/beacon.yaml"
      }
    }
  }
}

Cursor

.cursor/mcp.json in your project root, or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "beacon": {
      "command": "beacon",
      "env": {
        "BEACON_MANIFEST_PATH": "/absolute/path/to/beacon.yaml"
      }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.beacon]
command = "beacon"

[mcp_servers.beacon.env]
BEACON_MANIFEST_PATH = "/absolute/path/to/beacon.yaml"

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "beacon": {
      "command": "beacon",
      "env": {
        "BEACON_MANIFEST_PATH": "/absolute/path/to/beacon.yaml"
      }
    }
  }
}

OpenCode

opencode.json in your project root:

{
  "mcp": {
    "beacon": {
      "type": "local",
      "command": ["beacon"],
      "environment": {
        "BEACON_MANIFEST_PATH": "/absolute/path/to/beacon.yaml"
      }
    }
  }
}

Generic stdio

Any MCP client that accepts a stdio server can use this shape:

{
  "command": "beacon",
  "env": {
    "BEACON_MANIFEST_PATH": "/absolute/path/to/beacon.yaml"
  }
}

Configuration

How it works

Beacon v0 is deterministic. At startup it:

1. Loads and validates beacon.yaml into a typed BeaconManifest.
2. Reads every canonical_docs entry and chunks them at Markdown headings into an in-memory DocIndex.
3. Stores the resulting ManifestBeaconProvider in a module-level slot.

On each tool call, the provider reads from the in-memory index and returns a frozen answer dataclass. It does not call an LLM, access the network, or query a database.

BeaconProvider is a typed protocol, so another provider can supply the same five tools without changing their answer contracts. A future Menhir-backed provider could add temporal memory, structure graphs, and Git history behind that interface.

Examples

Three small, self-contained example repositories live under examples/, one per project shape:

Each has a valid beacon.yaml, real canonical docs, and meaningful concepts/guardrails/build-and-test metadata, and is checked automatically by tests/test_examples.py for validation, all five provider tools, and clean embedded/metadata-only snapshot export. Use the closest match as a starting point for your own manifest.

Versions

Beacon tracks three independent version numbers:

A snapshot records its generator (product) version, the manifest schema version it came from, and its own snapshot version separately. The default snapshot embeds each canonical document's heading-chunk text once; --metadata-only emits structure and hashes without the text.

Status

Beacon is experimental, and this checkout is the 0.2.0rc1 release candidate. The v0.2 local functionality is implemented: beacon init, validate, inspect, export, and serve (plus the no-argument stdio server) are shipped and tested, and the maintained examples pass their validation/provider/snapshot matrix. One release gate remains, not missing feature scope:

• Unaided developer trial. The 15-minute cold-start claim is a separate acceptance gate to be measured with a developer who did not write the implementation; documentation does not assert that it has passed.

A MenhirBeaconProvider is a deferred v0.3 limitation, not evidence that this v0.2 scope is unfinished. Beacon is static and offline: no database, no runtime network call, no LLM or embedding, no telemetry, and no update check. It reads only the manifest and the documents it lists.

Track the product path in docs/beacon-functional-product-roadmap.md. The tool-level interface history and backlog remain in docs/beacon-mcp-roadmap.md.

Contributing

Read docs/beacon-strategy-handoff.md for the positioning rationale before proposing new features.

Useful contributions at this stage include:

• Adding example manifests for different project shapes (library, research project, monorepo service).
• Adding docs/demo-transcript.md showing a real agent session.
• Writing golden-output tests for each MCP tool.

Please hold off on adding tools or expanding the manifest schema. The current five tools need clearer documentation and easier client setup before the interface grows.

Development setup:

git clone https://github.com/Archolith/beacon.git
cd beacon
pip install -e ".[dev]"
python -m pytest tests/ -x --tb=short

All tests run offline. They do not require Neo4j, a network connection, or an external service.

The negative-control mutation gate deliberately breaks four release-critical behaviors in temporary package copies and requires the focused tests to fail:

python scripts/run_mutation_tests.py

The command succeeds only when every mutant is caught. The real checkout is not modified.

License

MIT. See LICENSE.