How background session sync works
AgentDrive lets one coding agent resume a session another one started. To make that work without asking you to save anything, it has to sync sessions in the background, safely, and without slowing the agent down. This po
AgentDrive lets one coding agent resume a session another one started. To make that work without asking you to save anything, it has to sync sessions in the background, safely, and without slowing the agent down. This post walks through how that works in the adrive CLI and the MCP server. All of the code described here is in the Apache-2.0 client packages.
1. A hook in every agent
Each supported agent CLI has a lifecycle hook system, and AgentDrive registers the same command in each one. Antigravity's hook payloads carry no event name, so its entries add --event <name>.
command -v adrive >/dev/null 2>&1 && adrive hook <harness> || npx -y @adrive/cli hook <harness>
The npx fallback exists because agents launched from a GUI often don't have the global npm bin directory on their PATH.
| Agent | Where the hook lives | Events |
|---|---|---|
| Claude Code | the AgentDrive plugin |
SessionStart, Stop, SessionEnd, PreCompact
|
| Codex | ~/.codex/hooks.json |
SessionStart, Stop, SessionEnd, PreCompact
|
| Cursor | ~/.cursor/hooks.json |
sessionStart, stop, sessionEnd, preCompact
|
| Antigravity |
~/.gemini/config/hooks.json, plus ~/.gemini/settings.json, which setup creates or updates |
SessionStart, Stop (in settings.json: SessionStart, AfterAgent, SessionEnd, PreCompress) |
| OpenCode | a plugin in ~/.config/opencode/plugins/
|
session.created, session.idle
|
adrive init merges these entries into the existing config files. It keeps any hooks you already have, in their original order, and re-running it produces identical output. Codex only runs hooks it trusts, so setup also records that approval for you; on an older Codex you approve them once via /hooks.
2. The hook returns fast, and sync runs detached
Hooks run inline with the agent. Codex caps hook timeouts at 3 seconds, so adrive hook does almost nothing itself. It reads the event payload (session id, working directory, transcript path), records which directory the session belongs to, starts a detached adrive sync process and exits 0. A hook failure is swallowed, so it can't block or break your session.
On a session-start event, if auto-context is on, the hook also asks AgentDrive for this project's recent sessions. It puts the newest session from each other agent first and returns up to three as extra context for the agent, with a hint to call drive_resume. OpenCode's plugin API has no way to inject context, so OpenCode skips this step.
The detached sync then does the real work:
-
Locking. One sync runs at a time, coordinated through a lock file in
~/.config/agentdrive/. A sync started by a burst of hook events waits up to 30 seconds for the lock instead of giving up. -
Debounce. A turn-end event (
Stop,stop,AfterAgent) re-syncs a session at most every two minutes. Session-end and compaction events skip the debounce, so the final state always lands. OpenCode has no session-end event, so itssession.idleskips the debounce too. - Sweep. Each sync also checks every agent for sessions that changed since the last sweep. The first sweep looks back 14 days and handles at most 50 sessions per run. A session that was killed before its end event gets finalized once it has been idle for 30 minutes.
-
Reading transcripts. Each agent stores sessions differently. Claude Code keeps JSONL under
~/.claude/projects, Codex keeps rollout files under$CODEX_HOME/sessions, Cursor under~/.cursor/projects, Antigravity under~/.gemini/<app>/brainand~/.gemini/tmp, and OpenCode exposes them throughopencode session listandopencode export. A parser for each one normalizes the session into turns, tool calls and touched paths.
3. Redaction and ignore rules
Two layers run on your machine before anything is uploaded.
Path rules decide which files can be uploaded at all. Artifact sync only looks at files the agent touched in that session. A file is skipped unless every check below passes:
- It is inside your home directory or the session's project.
- It doesn't match the built-in deny list. That list covers
.envand.env.*,.dev.vars,.ssh/,.aws/,.kube/,.npmrc,.netrc,*.pem,*.key,credentials.json,auth.json, shell history, SQLite databases,node_modules/,dist/and more. The deny list is a hard gate: a project's.adriveignorecan't override it. - It doesn't match the project's
.adriveignore. This file uses a subset of gitignore syntax: comments,!negation,/anchoring,*and**. - It is untracked and not ignored by git, or it sits outside any repository. Tracked files are already in git, and gitignored files are where secrets tend to live. If
git statusfails for any other reason, the file is skipped. - It is no larger than 1 MB and doesn't look binary (no NUL byte in the first 8 KB).
Content redaction scrubs what does get uploaded. The transcript and every synced file go through a pattern-based redactor. It replaces AWS access keys and secrets, GCP service-account private keys, Stripe, GitHub, Anthropic, OpenAI, Slack and AgentDrive tokens, JWTs, PEM private-key blocks, and SOMETHING_KEY=...-style assignments with markers like [redacted:github-token]. The version message records which kinds were redacted, never the values.
The redactor is best-effort, and it is not a security boundary. Pattern matching will miss secrets that don't look like secrets. That's why the path rules come first, and why Private Workspace exists.
4. Storage layout
Each session is rendered as plain markdown: a header with the project, working directory, title and turn count, a "Files touched" list, then one ## user or ## assistant section per turn with > tool: lines for tool calls. The sync writes it to:
sessions/<project>/<harness>/<session-id>.md
sessions/<project>/files/<path relative to the project>
A file outside the project, but inside your home directory, goes under files/_external/ with a short hash of its path in the name.
The project key is derived from where you work, so every agent files the same repo under the same key:
- With a git remote, it's the normalized remote URL, such as
github.com__acme__api. - With a local repo and no remote, it's the repo folder name plus a short hash of its path.
- Outside a repo, it's
local__<folder>-<hash>. - Sessions from a Claude Code worktree that has since been removed file under its parent repo.
Workspace files are versioned and content-addressed, so re-uploading an unchanged file costs nothing. Each session is also recorded as a run with the id <harness>:<session-id>. The run carries the session title, its status (in_progress or success), the ids of the files it uploaded, the transcript path, the paths it touched and the time of the last turn. Every request is stamped with the agent as its agent platform, which is where provenance comes from: the timeline shows that Codex wrote this file and Claude Code read it.
5. Building the handoff brief
When an agent calls drive_resume with no arguments, AgentDrive picks the latest session in this project from a different agent. Resuming in Codex therefore gives you the Claude Code session, not Codex's own last run. If no other agent has a session there, it falls back to the latest one. You can also pass a specific id from drive_sessions.
The full transcript would usually be too large to load, so the brief is built to a character budget (12,000 by default, from 1,000 up to 50,000):
- A one-line intro naming the source agent and session, with an instruction to check file state on disk before relying on it.
- The session metadata.
- Goal: the first user message, capped at 1,500 characters, or an eighth of the budget if that is smaller.
-
Files touched, plus the file ids of the uploaded copies, so an agent on another machine can fetch them with
drive_read. - Recent turns, picked from the newest back until the budget runs out and shown in order, with a marker for how many earlier turns were left out.
If the head is too large, the file lists shrink first, so even a small budget carries the latest turns. Resume works the same way through /agentdrive:resume in Claude Code and adrive resume in a shell.
6. Private Workspace
Turn it on with adrive privacy --private-workspace on, and the sync changes in four ways:
- Transcripts and synced files are encrypted on your machine with AES-256-GCM before upload. The data key is generated locally and stored wrapped in your AgentDrive config directory. The server only ever sees ciphertext.
- The project key is replaced with a hash (
p-plus 16 hex characters), and synced files are stored under hashed names, so repo names and file paths don't appear in storage paths. - Run metadata, which the server has to read, leaves out the working directory, the title and the touched paths. The session appears as "Private session".
- The MCP server can't decrypt, so
drive_resumetells the agent to runadrive resume <id>in a shell. That command decrypts locally and prints the brief.
The trade-off is that server-side features can't read encrypted content. That's the point.
Try it
curl -fsSL agentdrive.sh/install | sh
adrive sync --dry-run # parse local sessions and report, upload nothing
adrive privacy --show # see what's on
The sessions docs cover the same ground in reference form.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes โ full credit and traffic to the original publisher.