Skip to main content
When you start a conversation with a coding agent — Claude Code, Codex, Cursor, OpenCode, or any other supported tool — Terma opens a session and records everything that happens until the conversation ends. That record is the foundation for attribution, spend tracking, and every finding Terma surfaces. Understanding what a session contains and how to query it gives you the full picture of what your AI tooling is actually doing.

​
Session lifecycle

A session follows the natural lifecycle of a coding conversation:
  1. Start — The agent fires a SessionStart hook (or equivalent). Terma opens a session record, assigns it a routing key, and begins collecting events.
  2. Tool calls — Every tool invocation triggers a PostToolUse hook. Terma records the tool name, arguments, result, and the token cost of the surrounding exchange.
  3. End — The agent fires a SessionEnd hook. Terma closes the session, finalizes token counts, and marks it ready for attribution.
Events are spooled locally as they arrive and delivered to Terma in the background with automatic backoff. If the network is unavailable, nothing is lost — use terma spool status to see what is queued and terma spool flush to deliver it immediately.

​
What a session contains

Each session record includes:

​
Session replay

In the Terma dashboard, you can replay any session in full conversational order. Every event in the session — prompts, tool calls, file edits, model responses — is presented in the sequence it occurred. You can filter the timeline to show only conversation turns, only tool calls, or only errors, and search across messages, tool names, and file paths. This makes it straightforward to trace exactly what an agent did during a long or expensive session.

​
Routing keys

Every session has a routing key: a stable identifier you use to reference that session in CLI commands, in the dashboard, and in the commit trailers Terma appends to git commits. Routing keys appear in terma session list output and in the Agent-Session-Id commit trailer. Use routing keys with the session sub-commands to pull up any session’s details:
Pass -o json to any session command to get machine-readable output suitable for piping into other tools or dashboards.

​
Spooling

Terma uses a local spool to buffer session events before delivery. This means the prepare-commit-msg git hook — which reads spool manifests to find sessions that touched staged files — never makes a network call. The hook completes in under 50 ms regardless of network conditions. Use the spool commands to inspect and manage buffered events:
If a session was created while offline, run terma spool flush before committing so the session is available for attribution when the commit hook runs.