Skip to main content
This guide walks you through generating your first AGENTS.md file using Beacon. You’ll go from installation to a validated AGENTS.md file in under 10 minutes.

​
Before you begin

You’ll need:
  • A repository or project directory to analyze
  • An API key from Gemini, Claude, or OpenAI (or use Beacon Cloud with USDC payment)
  • Basic command line knowledge
For this quickstart, we’ll use Gemini 2.5 Flash (the default provider) since it’s free and fast. You can get an API key at Google AI Studio.

​
Step 1: Install Beacon

Run the install script: 
curl -fsSL https://raw.githubusercontent.com/DavidNzube101/beacon/master/install.sh | sh
Verify it’s installed: 
beacon --version
You should see something like beacon 0.2.4.
If you prefer Docker:
docker pull ghcr.io/davidnzube101/beacon
You’ll need to adjust the commands below to use Docker. See the Docker deployment guide for details.

​
Step 2: Set your API key

Export your Gemini API key as an environment variable: 
export GEMINI_API_KEY=your_api_key_here
Never commit API keys to version control. Add them to your shell profile or use a secrets manager in production.
You can also pass the key directly with --api-key if you prefer: 
beacon generate ./my-project --api-key your_api_key_here

​
Step 3: Generate your AGENTS.md

Navigate to your project directory or specify a path: 
beacon generate ./my-project
Beacon will:
  1. Scan your repository for source files, README, and manifests
  2. Send the context to Gemini for AI inference
  3. Generate an AGENTS.md file in the current directory
You’ll see output like: 
⬛ Beacon — scanning ./my-project...
   📁 Scanning: /Users/you/projects/my-project
   ✓ README found
   ✓ Package manifest found: package.json
   ✓ Scan complete — 12 source files collected
📦 Repo: my-project (12 source files)
   🤖 Provider: gemini
   ✓ Inferred 3 capabilities
   ✓ Inferred 5 endpoints
   ✓ Written to AGENTS.md

✅ Done! AGENTS.md written to: AGENTS.md
   Provider:     gemini
   Capabilities: 3
   Endpoints:    5

​
Step 4: Review the generated file

Open the generated AGENTS.md file: 
cat AGENTS.md
You’ll see a structured document with sections like:
AGENTS.md
# AGENTS.md — my-project

> A REST API for managing user accounts and authentication

**Version:** 1.0.0

---

## Authentication

**Type:** `bearer`

Requires a JWT token in the Authorization header.

---

## Capabilities

What an agent can do with this repository:

### `authenticate_user`

Authenticates a user with email and password, returning a JWT token.

**Input:**

```json
{
  "properties": {
    "email": {
      "type": "string",
      "description": "User's email address"
    },
    "password": {
      "type": "string",
      "description": "User's password"
    }
  },
  "required": ["email", "password"],
  "type": "object"
}
Output: 
{
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "JWT authentication token"
    }
  }
}
Examples:
  • POST /auth/login with email and password

​
Endpoints

​
POST /auth/login

Authenticate a user and receive a JWT token.
ParameterTypeRequiredDescription
emailstring✅User’s email address
passwordstring✅User’s password

​
GET /users/:id

Retrieve user information by ID.
ParameterTypeRequiredDescription
idstring✅User’s unique identifier
Generated by Beacon — Make any repo agent-ready. Instantly. 

## Step 5: Validate the output

Ensure the generated file is valid:

```bash
beacon validate ./AGENTS.md
You should see: 
⬛ Beacon — validating ./AGENTS.md...
   ✅ Schema valid

📋 Validation Report
   Valid:    ✅ Yes
   Errors:   0
   Warnings: 0

​
Optional: Check endpoint reachability

If your service is running locally, you can validate that the documented endpoints are actually reachable: 
beacon validate ./AGENTS.md --check-endpoints
This will attempt to reach each documented endpoint and report the results: 
⬛ Beacon — validating ./AGENTS.md...
   ✅ Schema valid
   🌐 Checking endpoint reachability...
   🔍 Checking: POST http://localhost:3000/auth/login
   ✅ http://localhost:3000/auth/login → 200
   🔍 Checking: GET http://localhost:3000/users/:id
   ✅ http://localhost:3000/users/:id → 404

📋 Validation Report
   Valid:    ✅ Yes
   Errors:   0
   Warnings: 0

🌐 Endpoint Results:
   ✅ POST /auth/login (200)
   ✅ GET /users/:id (404)
A 404 is considered “reachable” — it means the server responded. Only 5xx errors are marked as unreachable.

​
Customization options

​
Use a different AI provider

Switch to Claude or OpenAI: 
export CLAUDE_API_KEY=your_key_here
beacon generate ./my-project --provider claude
See the AI providers guide for a detailed comparison.

​
Custom output path

Write the AGENTS.md file to a different location: 
beacon generate ./my-project --output ./docs/AGENTS.md

​
Analyze a GitHub repository

You can pass a GitHub URL instead of a local path: 
beacon generate https://github.com/user/repo
GitHub URL support requires the repository to be public. Private repositories are not currently supported.

​
What’s in the generated file?

Beacon analyzes your codebase and generates these sections:
High-level actions an AI agent can perform with your repository. Each capability includes:
  • Name (snake_case identifier)
  • Description (what it does)
  • Input schema (JSON schema for parameters)
  • Output schema (JSON schema for return value)
  • Examples (common use cases)
HTTP API endpoints extracted from your source code. Includes:
  • Method (GET, POST, PUT, DELETE)
  • Path (with parameter placeholders)
  • Description
  • Parameter table (name, type, required, description)
How agents should authenticate with your service:
  • Type: bearer, api_key, or none
  • Description of the authentication flow
API rate limiting information:
  • Requests per minute
  • Requests per day
  • Additional notes

​
Next steps

Now that you’ve generated your first AGENTS.md file:

Understand how it works

Learn about the scanning and inference process

CLI reference

Explore all available commands and options

Multiple providers

Compare Gemini, Claude, OpenAI, and Beacon Cloud

Deploy as an API

Run Beacon as a web service with Docker

​
Troubleshooting

​
”No API key” error

If you see: 
Error: No API key for gemini. Pass --api-key or set GEMINI_API_KEY in your environment.
Make sure you’ve exported the key: 
export GEMINI_API_KEY=your_key_here
Or pass it directly: 
beacon generate ./my-project --api-key your_key_here

​
“Failed to reach [Provider] API” error

This usually means:
  • Network connectivity issues
  • Invalid API key
  • Rate limiting from the provider
Double-check your API key and try again. If the problem persists, try a different provider.

​
Empty or minimal AGENTS.md

If Beacon generates a very minimal file with few capabilities:
  • Ensure your project has a README explaining what it does
  • Check that source files are being scanned (look for “X source files collected”)
  • Try adding inline comments to your endpoint handlers
  • Consider using a different AI provider

​
”File not found” when validating

Make sure you’re pointing to the correct file: 
beacon validate ./AGENTS.md
Not: 
beacon validate AGENTS.md  # May fail if not in current directory

Build docs developers (and LLMs) love

Get started for freeTalk to us