Skip to main content

​
What is Beacon?

Beacon is a CLI tool and web API that analyzes your codebase and automatically generates an AGENTS.md file, making your repository discoverable and usable by autonomous AI agents.
AGENTS.md is a standard specification that describes what capabilities, endpoints, and authentication methods your repository provides to AI agents.
Instead of manually documenting your repository’s agent-usable features, Beacon scans your code, package manifests, and README files, then uses AI to infer and document capabilities in a machine-readable format.

​
Why Beacon exists

As AI agents become more prevalent in software development, repositories need a standardized way to communicate their capabilities. Without this, agents must:
  • Guess at available endpoints and functionality
  • Parse inconsistent documentation formats
  • Lack clear authentication requirements
  • Miss critical capabilities hidden in source code
Beacon solves this by automatically generating a standards-compliant AGENTS.md file that tells agents exactly what your repository can do and how to use it.

​
Key benefits

Automated discovery

Scans source files, README, package manifests, and OpenAPI specs to identify capabilities

AI-powered inference

Uses Gemini, Claude, OpenAI, or Beacon Cloud to intelligently extract agent-usable features

Standards-compliant

Generates AGENTS.md files following the AAIF specification

Validation built-in

Validates existing AGENTS.md files and optionally checks endpoint reachability

​
How it works at a high level

Beacon follows a three-step process to generate your AGENTS.md file:
1

Scan

Walks your repository and extracts:
  • README files
  • Source files (up to 50 files, max 50KB each)
  • Package manifests (Cargo.toml, package.json, pyproject.toml, go.mod)
  • OpenAPI specifications
Automatically skips common directories like node_modules, target, .git, and dist.
2

Infer

Sends the extracted context to your chosen AI provider (Gemini, Claude, OpenAI, or Beacon Cloud) with a structured prompt asking it to:
  • Identify agent-usable capabilities
  • Extract REST API endpoints with parameters
  • Determine authentication requirements
  • Generate JSON schemas for inputs and outputs
3

Generate

Writes a standards-compliant AGENTS.md file to your repository containing:
  • Repository description and version
  • Documented capabilities with input/output schemas
  • HTTP endpoints with method, path, and parameters
  • Authentication type and requirements
  • Rate limits and contact information

​
Use cases

​
Making APIs agent-discoverable

If you have a REST API built with Express, NestJS, FastAPI, or similar frameworks, Beacon extracts endpoint definitions from decorators and route handlers: 
// Beacon finds this in your source code
@Get('/users/:id')
async getUser(@Param('id') id: string) {
  // ...
}
And documents it in AGENTS.md: 
### `GET /users/:id`

Retrieve a user by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | `string` | ✅ | The user's unique identifier |

​
Documenting CLI tool capabilities

For CLI tools like Beacon itself, it identifies the commands agents can invoke: 
capabilities:
  - name: generate_agents_md
    description: Scans a repository and generates an AGENTS.md file
    input_schema:
      properties:
        target:
          type: string
          description: Path to repository or GitHub URL

​
Web services and background jobs

Beacon looks beyond just HTTP endpoints to identify background services, notification systems, chat integrations, and indexers that agents might want to trigger or monitor.

​
What’s next?

Install Beacon

Get Beacon installed on your system in under a minute

Quickstart guide

Generate your first AGENTS.md file in 5 minutes

How it works

Deep dive into the scanning and inference process

AI providers

Learn about Gemini, Claude, OpenAI, and Beacon Cloud options

Build docs developers (and LLMs) love

Get started for freeTalk to us