> ## Documentation Index
> Fetch the complete documentation index at: https://docs.terma.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# What Is a Terma Session? Messages, Tools, and Cost

> A Terma session captures the full timeline of an AI coding conversation: prompts, tool calls, model responses, file edits, and token cost.

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:

| Field                  | Description                                                                   |
| ---------------------- | ----------------------------------------------------------------------------- |
| **Routing key**        | Unique identifier used in CLI commands and commit trailers                    |
| **Source agent**       | The tool that generated the session (e.g. `claude-code`, `codex`, `opencode`) |
| **Model**              | The model used, including version                                             |
| **User / principal**   | The engineer attributed to the session                                        |
| **Prompt count**       | Number of user turns                                                          |
| **Message count**      | Total messages exchanged                                                      |
| **Tool call count**    | Number of tool invocations                                                    |
| **Input tokens**       | Tokens in prompts and context                                                 |
| **Output tokens**      | Tokens in model responses                                                     |
| **Cache read tokens**  | Tokens served from prompt cache                                               |
| **Cache write tokens** | Tokens written to prompt cache                                                |
| **Total tokens**       | Sum of all token counts                                                       |
| **Cost (USD)**         | Total cost derived from the entitlement rail used                             |
| **Duration**           | Wall-clock time from SessionStart to SessionEnd                               |
| **Files touched**      | Paths read or written during the session                                      |

## 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:

```bash theme={null}
# List recent sessions for a specific user
terma session list --user ada --since 7d

# Show a single session's roll-up (cost, tokens, tool calls)
terma session get <routing-key>

# Replay all events in conversational order, tool calls only
terma session events <routing-key> --tools-only

# Show git and GitHub actions the session performed
terma session git <routing-key>
```

<Tip>
  Pass `-o json` to any session command to get machine-readable output suitable for piping into other tools or dashboards.
</Tip>

## 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:

```bash theme={null}
# Show what is queued locally
terma spool status

# Deliver queued events to Terma now (rather than waiting for backoff)
terma spool flush
```

<Note>
  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.
</Note>