# Session Model *Work has a grain. Aura respects the grain.* When you sit down to work, you are not producing commits. You are working on a problem. You read some code, you form a plan, you make some edits, you try them, you adjust. At some point the problem is solved and you commit. At another point the problem is set aside and you pick up a different one. Commits are the artifacts that outlive your session. But the session itself — the coherent stretch of thinking, editing, and iterating that produced those commits — is the thing that actually happened. Git does not know about sessions. It sees only the commits that drop out the end. Aura models the session directly. A session is a named, durable container for a stretch of related work. Intents, snapshots, edits, commits, and plans are all grouped by session. When you come back to a project after three days away, you resume the session — not just the branch — and pick up where you left off. > A commit is what you shipped. A session is what you did. ## What a session contains A session is a record of a coherent period of work. It bundles: - **Identity**: a unique session ID and an optional human label. - **Branch**: the git branch the session is operating on. - **Intents**: the [intent log](/intent-tracking) accumulated during the session. - **Snapshots**: every [pre-edit snapshot](/snapshot-vs-commit) taken. - **Edits**: the set of files touched and the AST-level operations applied. - **Commits**: the git commits produced, if any. - **Checkpoints**: optional milestones within the session. - **Notes**: arbitrary metadata (agent name, context summary, plan references). A session starts implicitly when you begin working (or explicitly with an Aura command) and ends implicitly when you stop (or explicitly when you close it). Between those moments, everything you do is attributed to the session. ## Why a session, not just a branch A branch is a code line. A session is a work line. They are related but not the same. - One session typically operates on one branch — but a session can move between branches (check out `main` to diagnose a bug, come back) and still be the same session. - One branch can accumulate many sessions — several days of work, each a distinct session, all landing on `feat/auth`. - A session can end without producing any commits (you were debugging, or you decided to throw the work away). A branch persists whether or not work lands on it. The branch describes where you are. The session describes what you are doing. ## Session resume The most visible affordance of the session model is resume. Three days after setting work aside, you return. You run `aura session resume ` (or use the MCP tool), and Aura restores: - The intent log, so you remember what you were trying to do. - The list of files you had been editing, with their pre-edit snapshots available. - The plan you were working from, if one exists. - The checkpoints you had reached. - The team context (messages, impacts) relevant to the session. This is dramatically more useful than `git status` on its own. `git status` tells you which files have uncommitted changes. Resume tells you *why* they have uncommitted changes, what you were about to do, what you had already done, and what the team has been up to in the meantime. ## Session summarize The counterpart to resume is summarize. At any point you can ask Aura to produce a summary of the session so far: ```bash aura session summarize ``` The summary is a dense, structured description of the work: - Intents logged, in order. - Functions modified, by identity. - Commits produced. - Verdicts (consistent, flagged, unresolved). - Outstanding impact alerts. - Handoff-ready notes. Summaries are useful for: - **Handover to another agent.** A successor reads the summary and picks up. - **Context compaction.** A long AI session burns through tokens; the summary replaces the full history with a compressed equivalent. - **Writing PR descriptions.** The summary is frequently the draft of the PR body you were going to write anyway. - **Self-reflection.** Scanning the summary before a commit catches drift between what you meant to do and what you actually did. ## Session-level rewind Because a session records its snapshots and AST operations as a set, a session can be rewound as a unit. "Undo everything I did this afternoon" is a coherent operation in Aura. It is not a coherent operation in Git without manual commit selection. Session rewind interacts cleanly with git: - Edits made but not committed: reverted to pre-session state via snapshots. - Commits made within the session: reverted via git, with Aura producing the revert commits semantically. - Commits made outside the session that landed during it (pulls, merges): left alone. This is a stronger undo than Git offers. Git's undo operates on commits; session rewind operates on a period of work, including work that never became commits. ## Checkpoints within a session A session may accumulate many intents and many edits over hours. Checkpoints are intermediate markers, finer than commits, that let you rewind to a point in the middle of a session without going all the way back. You can think of checkpoints as breadcrumbs. Every intent log creates a natural checkpoint; you can also create named checkpoints manually: ``` session ├── checkpoint: "started refactor" ├── intent: "extract token validation" ├── edit: src/auth.rs ├── checkpoint: "validation extracted" ├── intent: "add rate limiting" ├── edit: src/middleware.rs ├── edit: tests/rate_limit.test.ts ├── commit: "feat: rate limiting" └── checkpoint: "rate limiting merged" ``` At any point you can rewind to "validation extracted" — undoing the rate limiting work while keeping the extraction. Without checkpoints, the only options are: revert the whole session, or cherry-pick edits by hand. ## Sessions and AI agents The session model was refined in the course of making Aura usable for AI agents. An agent working on a task naturally has a session. The agent's intents are a record of what it attempted. Its snapshots allow human review and rewind. Its edits are attributed cleanly. When an agent hands off to another agent — perhaps because context is full, perhaps because the task exceeds the first agent's capabilities — the handover is a session summary, not a file list. The successor starts from the summary with full context. A fleet of agents running in parallel on a repo produces a fleet of sessions, each with its own ID, each attributable. A human supervising the fleet sees which sessions are active, what each intends, what each has changed. The session is the unit of attribution. ## Sessions across team members On a team using Aura's mothership, sessions are broadcast. Your teammates can see (at a high level) that you have a session open on `feat/auth`, with intent "refactor token validation." This is useful for coordination: - Before starting work, a teammate can check whether the function they intend to edit is already in someone's active session. - Zone claims — the mechanism that prevents two agents from stomping on each other's work — are session-scoped. Releasing a zone requires ending or adjusting the session. - Team messages can be addressed to a session, not just a person. "Heads up, the function you're working on in your session `sess_4f2a...` has an impact alert." This is not Slack. It is a fine-grained coordination layer attached directly to work, not to chat. ## Session lifecycle The common transitions: - **Start**: implicit on first Aura action in a period of inactivity, or explicit. - **Active**: edits, intents, snapshots, commits accumulate. - **Paused**: explicit pause (`aura session pause`) or timeout. State preserved. - **Resumed**: explicit resume. State restored. - **Summarized**: snapshot of current state, session continues. - **Handed over**: summary generated for a successor; session marked handed over. - **Closed**: explicit close when work is done. Session archived. - **Rewound**: full or partial rollback of session work. Sessions do not need to be closed cleanly for their history to persist. An abandoned session is archived automatically after inactivity. Nothing is lost. ## Session data and privacy A session's data lives in the [shadow store](/shadow-branches). Intents, snapshots, summaries — all of it is local by default. On teams using the mothership, some session metadata is synchronized (session existence, high-level intent, branch) to support coordination; the full contents remain with you unless you explicitly share. You can export a session summary to paste into an issue tracker, send to a teammate, or hand to another agent. Export is an explicit action; sessions are not automatically broadcast wholesale. ## Sessions versus other granularities A cheat sheet: | Unit | Scope | Lifetime | Audience | |---|---|---|---| | Edit | A single change to a file | Seconds | You | | Snapshot | A file state before an edit | Until aged out | You | | Intent | A stated goal for a stretch of edits | Within a session | You, reviewer | | Checkpoint | A marker within a session | Until session closes | You | | Commit | A coherent unit of work | Permanent | The team | | Session | A stretch of related work | Until archived | You, coordinators | | Branch | A line of code | Until deleted | The team | These granularities compose. An edit creates (or uses) a snapshot. A snapshot is grouped under a checkpoint. Checkpoints aggregate under a session. A session may produce zero or more commits on a branch. The hierarchy is not strict but it is useful as a mental model. ## Resume as the killer feature If any one feature of the session model justifies the whole concept, it is resume. Software work is interrupted constantly. Meetings, questions, lunches, other branches, multi-day context switches. Without resume, the cost of interruption is the cost of reconstructing where you were — reading diffs, recalling what you were trying to do, rebuilding the mental model. With resume, the reconstruction is automatic. You open the session, read the summary, see your intents, see your snapshots, see the pending edits. You are back in flow in seconds. For humans this is valuable. For AI agents, which have even less tolerance for reconstructed context, it is essential. ## Related Sessions aggregate [intents](/intent-tracking) and [snapshots](/snapshot-vs-commit). They produce [commits](/pre-commit-hook-explained) that are validated against intent. Session state is stored on the [shadow branch](/shadow-branches) alongside semantic history.