How FORG Works

FORG is a three-layer system: a local agent on each developer machine, cloud ingestion and analytics services, and a dashboard that aggregates analytics. No AI model traffic passes through FORG — only metadata.

The three components

1. The local agent (forg)

A lightweight Go binary that runs on each developer's machine. It listens on 127.0.0.1:6247 and accepts signal payloads from adapters. The agent:

• Validates HMAC signatures on incoming signals
• Forwards signals to FORG over HTTPS
• Returns budget responses for opt-in gateway hard-blocks
• Caches license and identity in the OS keychain
• Manages session keys for adapter authentication

The agent is single-tenant — it only knows about the currently activated developer. It holds no other users' data.

2. FORG ingestion (forg.pro/engine/*)

A Cloudflare Worker that runs at the edge, closest to the developer's network location. It receives signals from the local agent, checks budgets, writes telemetry to Supabase, and returns a response within milliseconds.

FORG ingestion has no access to:

• Prompt or completion content (the agent never sends it)
• Raw code or files from the developer's machine
• Other tenants' data (org-isolated in Supabase via RLS)

3. The dashboard (forg.pro)

A Next.js application that reads from the org's Supabase schema and presents analytics, budget management, alerts, and settings. The dashboard is org-scoped — an admin at Company A cannot see Company B's data.

Signal path (happy path)

Developer uses Claude Code
        ↓
Claude Code calls Anthropic API → gets response
        ↓
PostToolUse hook fires → passes signal JSON to forg CLI
        ↓
forg CLI POSTs to 127.0.0.1:6247/emit (HMAC signed)
        ↓
Local agent forwards to forg.pro/engine/v1/emit (TLS)
        ↓
FORG checks budgets → { blocked: false }
        ↓
FORG writes signal to Supabase (async)
        ↓
Response returns to local agent → to forg CLI → hook exits 0
        ↓
Claude Code tool call completes normally

Block path

... same as above up to FORG ingestion ...
        ↓
FORG checks opt-in gateway budget → { blocked: true, message: "Monthly cap reached" }
        ↓
Response returns to local agent → to forg CLI → hook exits 2
        ↓
Claude Code receives non-zero hook exit → surfaces error to developer

Fail-open design

If the local agent is not running, or if FORG ingestion is unreachable (network outage, Cloudflare incident), the adapter defaults to allowing all calls. FORG is never in the critical path for AI tool functionality — it observes and can block, but cannot cause an outage that prevents developers from working.

Data isolation

All org data in Supabase is protected by Row Level Security (RLS) policies that restrict access to rows matching the authenticated org ID. Even database administrators cannot query across org boundaries without explicit policy changes, which are audited.