Concepts
FORG is built around a small set of primitives that compose into a complete observability and policy system. Understanding these building blocks makes it much easier to configure rules, interpret dashboard data, and build on the API.
Architecture overview
Every FORG deployment has three layers:
- Adapters — thin hooks in your AI tools (Claude Code, Cursor, etc.) that emit structured signals to the local agent over HTTP.
- Local agent — the
forgbinary running on the developer's machine. It authenticates signals with HMAC-SHA256, buffers them, and forwards batches to the Rule Engine atforg.pro/engine/v1/. - Rule Engine + Dashboard — a Cloudflare Worker that classifies signals, evaluates rules in real time, stores behavioral data in Supabase + pgvector, and surfaces insights via the dashboard and API.
No prompt or completion text is ever transmitted. Every signal is metadata-only: model, token counts, latency, cost, and error code.
Core concepts
End-to-end architecture: adapter → local agent → Rule Engine → dashboard. Understand every hop.
How FORG groups signals into sessions, when a new session starts, and what session metadata looks like.
The atomic unit of FORG telemetry. Schema, lifecycle, and what each field means.
How rules are evaluated, priority ordering, action types, and combining conditions.
Daily and monthly token/cost budgets, how they reset, and how the block action works.
Anomaly detection, cost forecasting, model recommendations, and the insight engine.
Key terms
| Term | Definition |
|---|---|
| Signal | A single structured event emitted by an adapter after an AI tool call. Contains model, tokens, cost, and context IDs. |
| Session | A contiguous sequence of signals from one developer with less than 30 min of inactivity between them. |
| Rule | A policy evaluated against each incoming signal. Rules have conditions (e.g., cost > $0.50/day), actions (block, warn, notify), and a scope (user, team, org). |
| Budget | A special rule type that enforces a cumulative cost or token limit over a rolling window (daily or monthly). |
| Adapter | Any component that emits signals to the local FORG agent. First-party adapters exist for major AI tools; third-party and custom adapters use the open protocol. |
| Project | A grouping of signals by repository or codebase, identified by a project_id. Used for per-project cost attribution. |
| Anomaly | A statistical deviation from a baseline, detected by the intelligence layer. Examples: sudden spike in tokens, unexpected model usage. |