> ## Documentation Index > Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt > Use this file to discover all available pages before exploring further. # Agent Sessions > What gets captured, where it's stored, and how to resume on any machine. # Agent Sessions A **session** is one continuous conversation with a coding agent: every message, every file edit, every tool call, plus the branch and commit it produced. The CLI captures sessions in the background — you don't `bb start` anything — and lets you resume them later, on any machine, by anyone on your team with access to the repo. This is what makes `bb agent-sessions resume` feel like time travel. ## How capture works The moment `bb` is installed, it watches the on-disk session log of every supported coding agent: | Agent | Source it tails | | ----------- | --------------------------------------------- | | Claude Code | `~/.claude/projects//sessions/*.jsonl` | | Codex CLI | `~/.codex/sessions/*.jsonl` | | Cursor | Cursor's local SQLite + workspaceStorage logs | | Copilot CLI | `~/.config/github-copilot/cli/sessions/` | | Gemini CLI | `~/.gemini/sessions/` | | Windsurf | Windsurf workspace storage | | Amazon Q | `~/.aws/q/sessions/` | Whenever an agent writes to its log, `bb` indexes the new turns, attaches the current `git` state (repo, branch, HEAD commit, dirty paths), and writes a normalized session record to `~/.buildbetter/sessions/`. If you're signed in (`bb login`), the record syncs to your free BuildBetter workspace within a few seconds. Capture is passive. There's no daemon to start, nothing to remember, no flag to set on the agent. Install the CLI once and every session from then on is captured. ## Where sessions are stored ``` ~/.buildbetter/ ├── bin/bb ├── config.toml ├── sessions/ │ ├── index.db # SQLite — fast lookup by repo/branch/commit │ ├── 2026/05/07/ │ │ ├── ee7f3a-codex.session.json # one file per session │ │ └── 1f2c8d-claude.session.json │ └── pending/ # awaiting sync to the cloud └── logs/bb.log ``` Each `.session.json` is a self-contained record: ```json theme={null} { "id": "ee7f3a", "agent": "codex", "repo": "buildbetter-app/bbapp", "branch": "codex/llm-data-source", "commit": "9f3a1c2", "author": "spencer@buildbetter.app", "started_at": "2026-05-07T10:14:33Z", "ended_at": "2026-05-07T12:08:51Z", "messages": 247, "file_edits": 12, "tool_calls": 38, "summary": "Ingest LLM chat history as a new data source...", "open_questions": [ "Should agent_logs be its own model or stay on conversation?" ], "linked_pr": 3308 } ``` The full transcript lives next to the metadata (or in the cloud, depending on size). Source code is **not** copied — `bb` only stores the file paths and diffs the agent touched. ## Resuming a session The most common call: ```bash theme={null} bb agent-sessions resume ``` The CLI lists sessions tied to the current branch (yours and your team's), most recent first, and hydrates the chosen one into your active agent: ``` ? Resume which session? ❯ codex/llm-data-source · spencer · 2h ago · 247 msgs bb-recorder-pass-through · nikhil · 3d ago · 89 msgs websocket-rpc-stream · spencer · 6d ago · 312 msgs ✓ Hydrating session ee7f3a — 247 messages, 12 file edits Codex › Picking up Spencer's exec plan for LLM ingestion. Last open question was the conversation/agent_logs split. > _ ``` What "hydrate" actually does: 1. Loads the prior conversation into the agent's context window (compacted if it's long) 2. Replays the file edits as a virtual diff so the agent knows what it changed 3. Surfaces the **open questions** the prior session left behind — not just a transcript, but a state you can keep working from ### Resume by ID If you already know the session you want — say it's linked from a PR comment or a teammate sent it to you: ```bash theme={null} bb agent-sessions resume ee7f3a ``` ### Resume on a branch you didn't start You don't need to be the original author. The picker shows everyone's sessions for the current branch, and resuming pulls the conversation into *your* agent on *your* machine: ```bash theme={null} git checkout nikhil/payments-stripe-webhook bb agent-sessions resume ``` This is the "no copy-paste handoff" flow — see the [Branch handoff](#workflow-branch-handoff) workflow below. ## Searching across sessions Resume is for the current branch. When you need to find a session from somewhere else — a PR you reviewed last month, a feature whose name you forgot — search: ```bash theme={null} bb agent-sessions search "agent_logs" # full-text across all sessions bb agent-sessions list --author maya --since 30d # everything Maya did this month bb agent-sessions list --branch "feat/exports" # by branch bb agent-sessions show ee7f3a # full metadata + summary ``` Output supports `--json` if you want to pipe it into something: ```bash theme={null} bb agent-sessions search "OAuth" --json | jq '.[].id' ``` ## PR linking When you push a branch and open a PR, `bb` auto-attaches the session(s) that produced it. Reviewers can pull the chat to understand *why* the code looks the way it does — better than the PR description, and impossible to lose to a closed tab. ```bash theme={null} bb agent-sessions link 3308 # manually link the current session to PR #3308 bb agent-sessions show ee7f3a # see which PR a session is linked to ``` To disable auto-linking for a specific repo: ```bash theme={null} bb config set pr.auto_link false ``` ## Workflows ### Workflow: branch handoff Spencer started a feature, has to step away. Maya picks it up. ```bash theme={null} # Spencer (Monday, EOD) git push -u origin spencer/llm-data-source # bb auto-syncs the session as a side effect of normal coding # Maya (Tuesday morning, on her laptop) git fetch && git checkout spencer/llm-data-source bb agent-sessions resume # > picks Spencer's session · 247 msgs · 2h ago # Codex hydrates with everything Spencer worked through, including the # open question he left for her. ``` No Slack screenshots. No "wait, what were you trying to do?" The agent already knows. ### Workflow: post-merge context recovery Six months later, a customer ticket lands on a system someone else built. ```bash theme={null} git log -- src/agent_logs # find the commit / PR git checkout # check out the historical state bb agent-sessions list --branch HEAD # see every session that touched this code bb agent-sessions resume # pull the chat that produced it ``` The agent loads the original reasoning — including any decisions the PR description never mentioned ("we picked denormalized to keep report queries under 50ms"). ### Workflow: ticket → spec → PR loop The full close-the-loop play with skills + sessions: ```bash theme={null} # 1. Customer ticket #4127 lands. Pull it into a spec with team conventions. /bb-specify "CSV export fails for orgs > 10k rows — see ticket #4127" # 2. Plan and implement against the spec. /bb-plan /bb-implement # 3. Verify in a real browser before merging. /trust-but-verify # 4. Push. Session auto-attaches to the PR for reviewers. git push -u origin fix/large-csv-export # 5. Months later, when the next ticket hits this code: bb agent-sessions resume # the chat that produced this code is right here ``` ### Workflow: scripting in a pre-commit hook Make sure every commit has an attached session, so the chat is never lost: ```bash theme={null} # .git/hooks/pre-commit test -n "$(bb agent-sessions list --branch HEAD --since 1d --json | jq '.[0]')" \ || { echo "No active agent session — run an agent or bb agent-sessions link"; exit 1; } ``` ## Privacy & access | What's stored | Where | Who can see it | | ------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------- | | Chat messages, tool calls, file paths, diffs, branch metadata | Your free BuildBetter workspace, encrypted in transit and at rest | Anyone with access to the same repo in your workspace | | Source code | Never copied — only paths and diffs | n/a | | Sessions before `bb login` | `~/.buildbetter/sessions/` on your machine | You only | | Sessions in a repo nobody else has access to | Same as above | You only | To delete: ```bash theme={null} bb agent-sessions delete # one session bb agent-sessions purge --repo . # everything for the current repo bb agent-sessions purge --before 90d # everything older than 90 days ``` To opt a sensitive repo out of cloud sync entirely: ```bash theme={null} cd path/to/sensitive-repo bb config set sync.enabled false ``` To exclude specific branches from being captured at all: ```bash theme={null} bb config set sessions.exclude_branches "secret/*,scratch/*" ``` ## Working offline If you skip `bb login`, capture still works — sessions land in `~/.buildbetter/sessions/` and you can `resume` your own sessions on the same machine. You just lose cross-machine sync and teammate-resumable sessions. Sign in any time and the local backlog back-fills the cloud index. ```bash theme={null} bb sync --status # see how many local sessions are pending sync bb sync # force the back-fill now ``` ## Next steps Every `bb` command in one place The slash commands that work alongside session resume