Concepts

Sessions

A sessionis FORG's unit for grouping a related sequence of AI tool calls by a single developer. Sessions provide the context for per-session cost attribution, rule scoping, and analytics aggregation.

Session lifecycle

Start — A session begins when an adapter emits a SessionStart hook, or when the first signal arrives after a timeout.
Active — While signals arrive within the session_timeout window (default: 1800 seconds), they are grouped into the current session.
End — A session ends when an adapter emits a SessionEnd hook, when the timeout expires, or when the user logs out of the tool.

Session attributes

Attribute	Description
`session_id`	Unique identifier, format: `sess_<12hex>`
`user_id`	Developer identity associated with this session
`project_id`	Project context (if provided by the adapter)
`adapter`	The tool adapter that generated the session
`started_at`	Timestamp of the first signal
`ended_at`	Timestamp of the last signal (or explicit end)
`total_cost_usd`	Sum of all signal costs in the session
`total_tokens_in`	Sum of input tokens across all signals
`total_tokens_out`	Sum of output tokens across all signals
`signal_count`	Number of AI calls made in the session

Session timeout

The session timeout controls how long of an inactivity gap is allowed before a new session is started. The default is 30 minutes (1800 seconds). Adjust in Dashboard → Settings → Sessions or via the config file:

{
  "session_timeout": 3600   // 1 hour
}

Session scoping in rules

Rules with scope: "session" evaluate the cumulative signal data within the current session. This is useful for per-task cost limits:

// Block if a single session exceeds $5
{
  "scope": "session",
  "condition": { "cost_usd": { "gt": 5 } },
  "action": "block"
}