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
Quick Reference
Pricing Details
Best For
Provider Flag Speed Accuracy Cost API Key Required Gemini 2.5 Flash gemini⚡⚡⚡ ⭐⭐⭐⭐ $ ✅ Claude Sonnet 4.5 claude⚡⚡ ⭐⭐⭐⭐⭐ $$$ ✅ OpenAI GPT-4o openai⚡⚡ ⭐⭐⭐⭐ $$ ✅ Beacon Cloud beacon-ai-cloud⚡⚡⚡ ⭐⭐⭐⭐ Fixed $0.09 ❌
Gemini 2.5 Flash
Input: $0.075 / 1M tokens
Output: $0.30 / 1M tokens
Typical run: ~$0.01-0.03
Free tier: 1500 requests/day
Claude Sonnet 4.5
Input: $3.00 / 1M tokens
Output: $15.00 / 1M tokens
Typical run: ~$0.10-0.30
Free tier: None
OpenAI GPT-4o
Input: $2.50 / 1M tokens
Output: $10.00 / 1M tokens
Typical run: ~$0.08-0.25
Free tier: $5 credit for new accounts
Beacon Cloud
Fixed: $0.09 per run (paid in USDC)
No usage tiers — same price regardless of repo size
Chains: Base or Solana
Gemini 2.5 Flash
Standard web apps with clear API patterns
Microservices with REST endpoints
Projects with good documentation (README, OpenAPI specs)
CI/CD pipelines where speed matters
Claude Sonnet 4.5
Complex monorepos with multiple services
Poorly documented codebases (Claude excels at inference)
Projects mixing multiple paradigms (REST + GraphQL + gRPC)
When accuracy is critical and cost is secondary
OpenAI GPT-4o
TypeScript/JavaScript projects (GPT-4o is particularly strong here)
Libraries and SDKs where understanding usage patterns matters
Projects with existing AI tooling (consistency with other OpenAI services)
When you already have OpenAI credits
Beacon Cloud
One-off generations where you don’t want to manage API keys
Open source projects where contributors might not have AI credits
When you prefer crypto payments over traditional billing
Testing Beacon before committing to a provider
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
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
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
Get API Key
Go to OpenAI Platform
Create a new secret key
Copy the key (you won’t see it again)
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
Run Beacon
beacon generate ./my-project --provider beacon-ai-cloud
No API key needed!
Payment Prompt
Beacon will display: 💰 Payment required to proceed.
Please send 0.09 USDC to one of these addresses:
- Base: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
- Solana: 9vMJfxuKxXBoEa7rM12mYLMwTacLMLDJqHozw96WQL8i
Send USDC
Use your wallet (MetaMask, Phantom, etc.) to send 0.09 USDC to either address.
Provide Transaction Hash
Which chain did you pay on? (base/solana)
> base
Please paste the transaction hash:
> 0x1234567890abcdef...
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
I'm generating for the first time
Use Gemini (default)Fast, accurate, and generous free tier. Perfect for trying Beacon. export GEMINI_API_KEY = your_key
beacon generate ./my-project
My codebase is complex with minimal docs
Use Claude Best reasoning capabilities for inferring capabilities from code structure. beacon generate ./my-project --provider claude --api-key sk-ant-...
I'm working with TypeScript/JavaScript
Use OpenAI GPT-4o Strongest performance on JS/TS ecosystems. beacon generate ./my-project --provider openai --api-key sk-...
I don't want to manage API keys
Use Beacon Cloud Pay $0.09 in USDC, no signup required. beacon generate ./my-project --provider beacon-ai-cloud
Use Gemini Fastest 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
Cost is critical (high volume)
Use Gemini ~0.01 − 0.03 p e r r u n v s 0.01-0.03 per run vs 0.01 − 0.03 p err u n v s 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