--- title: "Sessions" description: "A session is one AI-agent coding conversation - the atomic unit everything in Cadence is built from." url: "https://teamcadence.ai/docs/concepts/sessions/" --- ## What counts as a session A session is one conversation with a coding agent - Claude Code, Codex, Cursor, or any other [supported agent](/docs/integrations/agents/) - from start to finish, in the working directory of a git repo. It's the atomic unit Cadence analyzes: everything else (cost, coaching, org rollups) is built by aggregating sessions. Each session carries: - **Token counts and cost**, broken into input, output, cache-read, and cache-write buckets (see [Cost & tokens](/docs/concepts/cost-and-tokens/)) - **A phase mix** - roughly how much of the session was spent planning, exploring the codebase, implementing, testing, or recovering from errors - **Links to the commits and pull requests** it produced, resolved via git notes and your org's GitHub webhooks - **A quality/outcome read** - did the session land cleanly, or show signs of the agent (or the developer) struggling Very short or trivial sessions are tracked but flagged as insignificant, and excluded from most views by default - the CLI's `--include-insignificant` flag opts back in. ## From session to commit Cadence links sessions to the git history they produced using git notes (`refs/notes/ai-sessions`) plus GitHub webhooks, so a session is attached to the PR it fed into rather than floating on its own. That link is also how [`cadence blame`](/docs/cli/commands/) can tell you which session produced a given line of code. ## Reading your own session history The [CLI](/docs/cli/commands/) can list, search, and view your own sessions directly, without opening the app: ```bash cadence session list --repo your-org/your-repo --limit 10 cadence session search "flaky auth test" --repo your-org/your-repo cadence session view <session-id> --full ``` This is also the mechanism [Cadence Cue](/docs/cue/overview/) is built on - Cue turns your session history into evidence an agent can use before it starts a new task. ## Session detail in the desktop app The [desktop app's local session detail view](/docs/desktop/overview/) presents a session like a meeting transcript: chaptered, summarized, with coaching notes (Stop doing / Start doing / Keep doing) anchored to specific points in the conversation.
Docs/Sessions
Sessions
A session is one AI-agent coding conversation - the atomic unit everything in Cadence is built from.
What counts as a session
A session is one conversation with a coding agent - Claude Code, Codex, Cursor, or any other supported agent - from start to finish, in the working directory of a git repo. It’s the atomic unit Cadence analyzes: everything else (cost, coaching, org rollups) is built by aggregating sessions.
Each session carries:
- Token counts and cost, broken into input, output, cache-read, and cache-write buckets (see Cost & tokens)
- A phase mix - roughly how much of the session was spent planning, exploring the codebase, implementing, testing, or recovering from errors
- Links to the commits and pull requests it produced, resolved via git notes and your org’s GitHub webhooks
- A quality/outcome read - did the session land cleanly, or show signs of the agent (or the developer) struggling
Very short or trivial sessions are tracked but flagged as insignificant, and excluded from most views by default - the CLI’s --include-insignificant flag opts back in.
From session to commit
Cadence links sessions to the git history they produced using git notes (refs/notes/ai-sessions) plus GitHub webhooks, so a session is attached to the PR it fed into rather than floating on its own. That link is also how cadence blame can tell you which session produced a given line of code.
Reading your own session history
The CLI can list, search, and view your own sessions directly, without opening the app:
cadence session list --repo your-org/your-repo --limit 10
cadence session search "flaky auth test" --repo your-org/your-repo
cadence session view <session-id> --fullThis is also the mechanism Cadence Cue is built on - Cue turns your session history into evidence an agent can use before it starts a new task.
Session detail in the desktop app
The desktop app’s local session detail view presents a session like a meeting transcript: chaptered, summarized, with coaching notes (Stop doing / Start doing / Keep doing) anchored to specific points in the conversation.