Skip to main content

Overview

Beacon supports four AI providers for capability inference. Each has different strengths, pricing, and use cases.

Gemini 2.5 Flash

Default — Fast and cost-effectiveBest for most repositories

Claude Sonnet 4.5

Most Accurate — Best reasoningIdeal for complex codebases

OpenAI GPT-4o

Balanced — Good all-rounderStrong with TypeScript/JavaScript

Beacon Cloud

No API Key — Pay per runPerfect for one-off usage

Provider Comparison

ProviderFlagSpeedAccuracyCostAPI Key Required
Gemini 2.5 Flashgemini⚡⚡⚡⭐⭐⭐⭐$
Claude Sonnet 4.5claude⚡⚡⭐⭐⭐⭐⭐$$$
OpenAI GPT-4oopenai⚡⚡⭐⭐⭐⭐$$
Beacon Cloudbeacon-ai-cloud⚡⚡⚡⭐⭐⭐⭐Fixed $0.09

Gemini 2.5 Flash (Default)

Why It’s Default

Gemini 2.5 Flash offers the best balance of speed, accuracy, and cost for most repositories.
Gemini’s native JSON mode (responseMimeType: "application/json") ensures reliable structured output, reducing parsing errors.

Setup

1

Get API Key

  1. Go to Google AI Studio
  2. Click “Get API key”
  3. Copy your key
2

Configure Beacon

export GEMINI_API_KEY=your_key_here
beacon generate ./my-project
Or pass directly:
beacon generate ./my-project --provider gemini --api-key your_key_here

Implementation Details

From src/inferrer.rs:63:
async fn call_gemini(prompt: &str, api_key: &str) -> Result<AgentsManifest> {
    let response = CLIENT
        .post(format!("{}?key={}", GEMINI_URL, api_key))
        .json(&json!({
            "contents": [{ "parts": [{ "text": prompt }] }],
            "generationConfig": {
                "temperature": 0.2,  // Low temp for consistency
                "responseMimeType": "application/json"  // Enforced JSON
            }
        }))
        .send()
        .await?;
    
    let raw: Value = response.json().await?;
    let text = raw["candidates"][0]["content"]["parts"][0]["text"]
        .as_str()
        .context("Unexpected Gemini response shape")?;
    
    parse_manifest(text)
}
Key features:
  • Temperature 0.2 — Deterministic, focused output
  • JSON response mode — Guaranteed valid JSON (no markdown wrapping)
  • Fast inference — Typically 2-5 seconds

When to Choose Gemini

Projects with clear API patterns (REST, OpenAPI)
Repositories with good existing documentation
CI/CD workflows where speed matters
Budget-conscious users (generous free tier)

Claude Sonnet 4.5

Why Claude Excels

Claude Sonnet 4.5 has the strongest reasoning capabilities, making it ideal for complex or poorly documented codebases.
Claude is particularly good at inferring intent from code structure when documentation is sparse.

Setup

1

Get API Key

  1. Go to Anthropic Console
  2. Navigate to API Keys
  3. Create a new key
2

Configure Beacon

export CLAUDE_API_KEY=sk-ant-your_key_here
beacon generate ./my-project --provider claude

Implementation Details

From src/inferrer.rs:90:
async fn call_claude(prompt: &str, api_key: &str) -> Result<AgentsManifest> {
    let response = CLIENT
        .post(CLAUDE_URL)
        .header("x-api-key", api_key)
        .header("anthropic-version", "2023-06-01")
        .json(&json!({
            "model": "claude-sonnet-4-5",
            "max_tokens": 4096,
            "messages": [{
                "role": "user",
                "content": prompt
            }]
        }))
        .send()
        .await?;
    
    let raw: Value = response.json().await?;
    let text = raw["content"][0]["text"]
        .as_str()
        .context("Unexpected Claude response shape")?;
    
    parse_manifest(text)
}
Key features:
  • 4096 max tokens — Room for detailed capability descriptions
  • Strong code reasoning — Understands complex abstractions
  • Slower but more accurate — 3-8 seconds typical

When to Choose Claude

Complex monorepos with multiple services
Legacy codebases with minimal documentation
Projects mixing REST, GraphQL, gRPC, etc.
When accuracy is more important than cost

OpenAI GPT-4o

Why GPT-4o

GPT-4o is well-balanced and particularly strong with JavaScript/TypeScript ecosystems.

Setup

1

Get API Key

  1. Go to OpenAI Platform
  2. Create a new secret key
  3. Copy the key (you won’t see it again)
2

Configure Beacon

export OPENAI_API_KEY=sk-your_key_here
beacon generate ./my-project --provider openai

Implementation Details

From src/inferrer.rs:119:
async fn call_openai(prompt: &str, api_key: &str) -> Result<AgentsManifest> {
    let response = CLIENT
        .post(OPENAI_URL)
        .bearer_auth(api_key)
        .json(&json!({
            "model": "gpt-4o",
            "temperature": 0.2,
            "response_format": { "type": "json_object" },  // Structured output
            "messages": [
                {
                    "role": "system",
                    "content": "You are an expert at analyzing software repositories. Always respond with valid JSON only."
                },
                {
                    "role": "user",
                    "content": prompt
                }
            ]
        }))
        .send()
        .await?;
    
    let raw: Value = response.json().await?;
    let text = raw["choices"][0]["message"]["content"]
        .as_str()
        .context("Unexpected OpenAI response shape")?;
    
    parse_manifest(text)
}
Key features:
  • JSON object mode — Enforced structured output
  • System prompt — Guides the model to focus on repository analysis
  • Strong with JS/TS — Trained extensively on Node.js patterns

When to Choose OpenAI

TypeScript or JavaScript projects
When you’re already using OpenAI for other tasks
Libraries and SDKs (good at understanding usage patterns)
If you have OpenAI credits to use

Beacon Cloud

How It Works

Beacon Cloud is a hosted inference service that accepts payment in USDC (stablecoin) instead of requiring API keys.
Beacon Cloud uses Gemini 2.5 Flash under the hood, but handles API key management for you.

Payment Flow

From src/inferrer.rs:156:
async fn call_beacon_cloud(ctx: &RepoContext, _prompt: &str) -> Result<AgentsManifest> {
    let initial_res = CLIENT
        .post(&generate_url)
        .json(&ctx)
        .send()
        .await?;
    
    // Server returns 402 Payment Required
    if initial_res.status() == reqwest::StatusCode::PAYMENT_REQUIRED {
        let headers = initial_res.headers();
        let amount = headers.get("x-payment-amount")...;  // "0.09"
        let run_id = headers.get("x-payment-run-id")...;
        let base_addr = headers.get("x-payment-address-base")...;
        let sol_addr = headers.get("x-payment-address-solana")...;
        
        // User sends USDC to provided address
        // User provides transaction hash
        
        let final_res = CLIENT
            .post(&generate_url)
            .header("x-payment-run-id", run_id)
            .header("x-payment-chain", chain)
            .header("x-payment-txn-hash", txn_hash)
            .json(&ctx)
            .send()
            .await?;
        
        // Server verifies payment on-chain and returns result
    }
}

Setup

1

Run Beacon

beacon generate ./my-project --provider beacon-ai-cloud
No API key needed!
2

Payment Prompt

Beacon will display:
💰 Payment required to proceed.

Please send 0.09 USDC to one of these addresses:
  - Base:   0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
  - Solana: 9vMJfxuKxXBoEa7rM12mYLMwTacLMLDJqHozw96WQL8i
3

Send USDC

Use your wallet (MetaMask, Phantom, etc.) to send 0.09 USDC to either address.
4

Provide Transaction Hash

Which chain did you pay on? (base/solana)
> base

Please paste the transaction hash:
> 0x1234567890abcdef...
5

Verification

Beacon verifies the payment on-chain and generates your AGENTS.md.

Payment Verification

The server verifies payments using blockchain explorers (see src/verifier.rs):
  • Base — Verified via BaseScan API
  • Solana — Verified via Solana RPC
Once verified, the transaction hash is marked as used to prevent double-spending.

When to Choose Beacon Cloud

You don’t have AI API keys and don’t want to set them up
One-off usage (generating AGENTS.md once)
You prefer crypto payments over credit cards
Contributing to open source projects (no API key sharing needed)
Beacon Cloud requires on-chain payment verification, which adds 10-30 seconds to generation time. Use Gemini directly if speed is critical.

Choosing the Right Provider

Use Gemini (default)Fast, accurate, and generous free tier. Perfect for trying Beacon.
export GEMINI_API_KEY=your_key
beacon generate ./my-project
Use ClaudeBest reasoning capabilities for inferring capabilities from code structure.
beacon generate ./my-project --provider claude --api-key sk-ant-...
Use OpenAI GPT-4oStrongest performance on JS/TS ecosystems.
beacon generate ./my-project --provider openai --api-key sk-...
Use Beacon CloudPay $0.09 in USDC, no signup required.
beacon generate ./my-project --provider beacon-ai-cloud
Use GeminiFastest inference (2-5s) and cheapest (~$0.01/run).
- name: Generate AGENTS.md
  env:
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
  run: beacon generate . --output AGENTS.md
Use Gemini~0.010.03perrunvs0.01-0.03 per run vs 0.10-0.30 for Claude/OpenAI.At 1000 runs/month:
  • Gemini: ~$20
  • OpenAI: ~$150
  • Claude: ~$200

Provider-Specific Tips

Gemini

Enable billing even if using the free tier — this removes the 60 requests/minute rate limit.

Claude

Claude performs best on large context windows. If your repo has extensive documentation, Claude will leverage it better than other providers.

OpenAI

Use tier-based pricing — once you hit higher usage tiers, OpenAI becomes more cost-competitive with Gemini.

Beacon Cloud

Keep your transaction hashes — they serve as receipts and proof of payment. Beacon Cloud marks them as “used” after verification.

Switching Providers

You can always regenerate your AGENTS.md with a different provider:
# Initial generation with Gemini
beacon generate ./my-project --output AGENTS.md

# Regenerate with Claude for comparison
beacon generate ./my-project --provider claude --output AGENTS-claude.md

# Compare the results
diff AGENTS.md AGENTS-claude.md
Different providers may identify different capabilities or describe them differently, but the core structure will be consistent.

Advanced: Custom Provider URLs

Beacon Cloud URL can be overridden:
export BEACON_CLOUD_URL=https://my-beacon-instance.com
beacon generate ./my-project --provider beacon-ai-cloud
This is useful for:
  • Self-hosted Beacon Cloud instances
  • Testing custom inference pipelines
  • Enterprise deployments with internal payment systems

Next Steps

Generate Your First AGENTS.md

Try Beacon with your preferred provider

How It Works

Understand Beacon’s inference pipeline

AGENTS.md Spec

Learn the AGENTS.md format in detail

API Reference

Use Beacon as a hosted service

Build docs developers (and LLMs) love