Concepts
FORG is built around a small set of primitives that compose into a complete observability and cost-control system. Understanding these building blocks makes it much easier to configure budgets, 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 FORG ingestion atforg.pro/engine/v1/. - Ingestion + Dashboard — a Cloudflare Worker that classifies signals, checks budgets, stores behavioral data in Supabase Postgres, 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 → FORG ingestion → 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.
Daily and monthly token/cost budgets, how they reset, and how the block action works.
Anomaly flags, deterministic spend forecasts, and efficiency insights — computed from your telemetry.
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. |
| Budget | A daily or monthly cost/token limit with alert thresholds and optional gateway hard-blocks. |
| Alert | A notification triggered by a budget threshold or detected anomaly. |
| 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 heuristic flag raised when usage deviates from recent patterns. Examples: sudden spike in tokens, unexpected model usage. Statistical/baseline detection is on the roadmap. |